Skip to content

Let docket fmt convert a recipe between YAML and JSON5 #418

Description

@josegonzalez

Description of feature

docket fmt canonically formats a recipe, but it can only ever write back the format it read. There is no way to turn a YAML recipe into its JSON5 twin, or the reverse.

--tasks-format looks like it might do this, but it is a reader override, not a converter. It states what the bytes on disk already are, for when the extension is absent or misleading, or when a flow-style YAML recipe would sniff as JSON5 because it opens with [. TestFmtTasksFormatOverridesFileExtension reads clearly here: it writes a JSON5 body into recipe.yml and passes --tasks-format json5 so the JSON5 formatter is selected. The content was already JSON5. Pointing the same flag at a genuinely-YAML file hands block-style YAML to the JSON5 parser and errors out.

Converting today means going out to another tool and back, which loses the comments both formatters otherwise preserve.

#410 added --format to init and export to state the format of what those commands write, as the output-side counterpart to --tasks-format. fmt was deliberately left out of that change because conversion raises questions the init/export case does not, and they are worth settling before any flag is added:

  • Does it rewrite in place under the existing name, leaving tasks.yml holding JSON5? That is a file whose extension lies about its contents, and a later docket validate --tasks tasks.yml picks its parser from the extension and fails.
  • Does it rename tasks.yml to tasks.json? That makes fmt a command that deletes files, which is a large change in what the command is.
  • Does it require an explicit --output, making conversion a single-file operation? fmt currently takes many paths and expands directories.
  • What happens with --check and --diff? A conversion is always a diff, so --check would report every file as unformatted, which is not what the CI lint job using it means.
  • Is docket fmt --format json5 - just a pipe-friendly converter, and is that the whole feature people actually want?

The stdin form may be the useful 90% and the safe place to start: cat tasks.yml | docket fmt --format json5 - writes the converted recipe to stdout, touches nothing on disk, and sidesteps every naming question above.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions