Improve tz normalize error message

terrazzoapp · Dec 15, 2024 · bcfc934 · bcfc934
1 parent d54632a
commit bcfc934
Show file tree

Hide file tree

Showing 5 changed files with 28 additions and 3 deletions.
diff --git a/.changeset/shiny-planets-give.md b/.changeset/shiny-planets-give.md
@@ -0,0 +1,7 @@
+---
+"@terrazzo/cli": patch
+"@terrazzo/parser": patch
+"@terrazzo/token-tools": patch
+---
+
+Improve error message for tz normalize
diff --git a/packages/cli/bin/cli.js b/packages/cli/bin/cli.js
@@ -48,6 +48,7 @@ const { values: flags, positionals } = parseArgs({
   options: {
     config: { type: 'string', short: 'c' },
     out: { type: 'string', short: 'o' },
+    output: { type: 'string' },
     help: { type: 'boolean' },
     silent: { type: 'boolean' },
     quiet: { type: 'boolean' }, // secret alias for --silent because I can’t remember it
@@ -92,7 +93,7 @@ export default async function main() {
 
   // normalize
   if (cmd === 'normalize') {
-    await normalizeCmd(positionals[1], { logger, output: flags.out });
+    await normalizeCmd(positionals[1], { logger, output: flags.out ?? flags.output });
     process.exit(0);
   }
 

diff --git a/packages/cli/src/normalize.ts b/packages/cli/src/normalize.ts
@@ -19,7 +19,7 @@ function findMember(name: string) {
 export async function normalizeCmd(filename: string, { logger, output }: NormalizeOptions) {
   try {
     if (!filename) {
-      logger.error({ message: 'Expected input: `tz normalize input.json -o output.json`' });
+      logger.error({ message: 'Expected input: `tz normalize <tokens.json> -o output.json`' });
       return;
     }
     const sourceLoc = new URL(filename, cwd);

diff --git a/packages/cli/test/normalize.test.ts b/packages/cli/test/normalize.test.ts
@@ -7,10 +7,27 @@ const cmd = '../../../bin/cli.js';
 
 describe('tz normalize', () => {
   test('basic', async () => {
+    const cwd = new URL('./fixtures/normalize/', import.meta.url);
+    await execa(cmd, ['normalize', 'input.json', '--output', 'actual.json'], { cwd });
+    await expect(fs.readFileSync(new URL('./actual.json', cwd), 'utf8')).toMatchFileSnapshot(
+      fileURLToPath(new URL('./want.json', cwd)),
+    );
+  });
+
+  test('basic (shortcut)', async () => {
     const cwd = new URL('./fixtures/normalize/', import.meta.url);
     await execa(cmd, ['normalize', 'input.json', '-o', 'actual.json'], { cwd });
     await expect(fs.readFileSync(new URL('./actual.json', cwd), 'utf8')).toMatchFileSnapshot(
       fileURLToPath(new URL('./want.json', cwd)),
     );
   });
+
+  test('missing input', async () => {
+    const cwd = new URL('./fixtures/normalize/', import.meta.url);
+    await expect(execa(cmd, ['normalize', '--output', 'actual.json'], { cwd })).rejects.toThrow(
+      `Command failed with exit code 1: ../../../bin/cli.js normalize --output actual.json
+
+✗  Expected input: \`tz normalize input.json -o output.json\``,
+    );
+  });
 });
diff --git a/www/src/pages/docs/cli/commands.md b/www/src/pages/docs/cli/commands.md
@@ -52,7 +52,7 @@ npx tz check [filename]
 The DTCG format has gone through many iterations over the years. Terrazzo lenient in the inputs it allows, such as allowing legacy sRGB hex colors without throwing a parsing error. To quickly update your tokens to the latest version of the format, run the following command:
 
 ```sh
-tz normalize tokens.json -o normalized.json
+tz normalize <input.json> -o normalized.json
 ```
 
 This will keep your tokens 100% as-authored, but will upgrade older DTCG files to the updated format and will safely fix minor issues. But just as a safety precaution, it requires saving to a new location just so you can review the changes before committing them.