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.
Description of feature
docket fmtcanonically 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-formatlooks 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[.TestFmtTasksFormatOverridesFileExtensionreads clearly here: it writes a JSON5 body intorecipe.ymland passes--tasks-format json5so 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
--formattoinitandexportto state the format of what those commands write, as the output-side counterpart to--tasks-format.fmtwas 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:tasks.ymlholding JSON5? That is a file whose extension lies about its contents, and a laterdocket validate --tasks tasks.ymlpicks its parser from the extension and fails.tasks.ymltotasks.json? That makesfmta command that deletes files, which is a large change in what the command is.--output, making conversion a single-file operation?fmtcurrently takes many paths and expands directories.--checkand--diff? A conversion is always a diff, so--checkwould report every file as unformatted, which is not what the CI lint job using it means.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.