From d7f8d77fb4a7b0c7096a069649e864ba133e4976 Mon Sep 17 00:00:00 2001 From: wonjang <48057918+wonjangcloud9@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:16:19 +0000 Subject: [PATCH] fix(cli): help shows each option's default once (#7953) citty's help appends "(Default: )" to every arg whose `default` is set, and 22 descriptions also spelled the default out, so `--help` read "(default: 5) (Default: 5)". Drop the hand-written copies, reword the lint-verbose and `measure extract --audio` flags whose "(default: a one-line summary)" sat next to "(Default: false)", and add a test that fails when a description with "(default:" has a `default` too. Co-authored-by: Claude Opus 5.5 --- packages/cli/src/commands/argDefaults.test.ts | 52 +++++++++++++++++++ packages/cli/src/commands/check.ts | 8 +-- packages/cli/src/commands/cloud/delete.ts | 2 +- packages/cli/src/commands/cloud/render.ts | 2 +- packages/cli/src/commands/events.ts | 2 +- packages/cli/src/commands/layout.ts | 10 ++-- packages/cli/src/commands/measure/extract.ts | 2 +- packages/cli/src/commands/preview.ts | 2 +- packages/cli/src/commands/publish.ts | 2 +- .../cli/src/commands/remove-background.ts | 2 +- packages/cli/src/commands/render.ts | 2 +- packages/cli/src/commands/snapshot.ts | 8 +-- packages/cli/src/commands/validate.ts | 2 +- 13 files changed, 74 insertions(+), 22 deletions(-) create mode 100644 packages/cli/src/commands/argDefaults.test.ts diff --git a/packages/cli/src/commands/argDefaults.test.ts b/packages/cli/src/commands/argDefaults.test.ts new file mode 100644 index 0000000000..91a6e72982 --- /dev/null +++ b/packages/cli/src/commands/argDefaults.test.ts @@ -0,0 +1,52 @@ +import { readdirSync, readFileSync } from "node:fs"; +import { dirname, join, relative } from "node:path"; +import { fileURLToPath } from "node:url"; +import ts from "typescript"; +import { describe, expect, it } from "vitest"; + +const commandsDir = dirname(fileURLToPath(import.meta.url)); + +function commandSources(dir: string): string[] { + return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const path = join(dir, entry.name); + if (entry.isDirectory()) return commandSources(path); + return entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts") ? [path] : []; + }); +} + +function propertyNamed(node: ts.ObjectLiteralExpression, name: string) { + return node.properties.find( + (p): p is ts.PropertyAssignment => + ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === name, + ); +} + +// citty's help appends "(Default: )" to every arg whose `default` is set. +function argsStatingTheirDefault(path: string): string[] { + const source = ts.createSourceFile(path, readFileSync(path, "utf8"), ts.ScriptTarget.Latest); + const found: string[] = []; + const visit = (node: ts.Node): void => { + const fallback = ts.isObjectLiteralExpression(node) + ? propertyNamed(node, "default") + : undefined; + if (fallback && fallback.initializer.getText(source) !== "undefined") { + const description = + propertyNamed(node as ts.ObjectLiteralExpression, "description")?.initializer.getText( + source, + ) ?? ""; + if (/\(default:/i.test(description)) { + const { line } = source.getLineAndCharacterOfPosition(node.getStart(source)); + found.push(`${relative(commandsDir, path)}:${line + 1}`); + } + } + ts.forEachChild(node, visit); + }; + visit(source); + return found; +} + +describe("command arg descriptions", () => { + it("leave the default of an arg that has one to citty's help", () => { + expect(commandSources(commandsDir).flatMap(argsStatingTheirDefault)).toEqual([]); + }); +}); diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.ts index 3188d9d7ea..50b469f42c 100644 --- a/packages/cli/src/commands/check.ts +++ b/packages/cli/src/commands/check.ts @@ -199,7 +199,7 @@ const CHECK_COMMAND_ARGS = { }, samples: { type: "string", - description: "Number of midpoint samples across the duration (default: 9)", + description: "Number of midpoint samples across the duration", default: "9", }, range: { @@ -229,17 +229,17 @@ const CHECK_COMMAND_ARGS = { }, "max-issues": { type: "string", - description: "Maximum issues to print or return after static collapse (default: 80)", + description: "Maximum issues to print or return after static collapse", default: "80", }, "collapse-static": { type: "boolean", - description: "Collapse repeated static issues across samples (default: true)", + description: "Collapse repeated static issues across samples", default: true, }, tolerance: { type: "string", - description: "Allowed pixel overflow before reporting an issue (default: 2)", + description: "Allowed pixel overflow before reporting an issue", default: "2", }, budget: { diff --git a/packages/cli/src/commands/cloud/delete.ts b/packages/cli/src/commands/cloud/delete.ts index c9cde36014..2ea9e52d57 100644 --- a/packages/cli/src/commands/cloud/delete.ts +++ b/packages/cli/src/commands/cloud/delete.ts @@ -37,7 +37,7 @@ export default defineCommand({ confirm: { type: "boolean", description: - "Prompt before deleting (default: true). Pass `--no-confirm` to skip — required for scripts and --json.", + "Prompt before deleting. Pass `--no-confirm` to skip — required for scripts and --json.", default: true, }, }, diff --git a/packages/cli/src/commands/cloud/render.ts b/packages/cli/src/commands/cloud/render.ts index 0c14e14ca5..613f5f5bd4 100644 --- a/packages/cli/src/commands/cloud/render.ts +++ b/packages/cli/src/commands/cloud/render.ts @@ -210,7 +210,7 @@ export default defineCommand({ wait: { type: "boolean", description: - "Poll until completion and download the video (default: true). Pass `--no-wait` for fire-and-forget — submits and exits with the render_id.", + "Poll until completion and download the video. Pass `--no-wait` for fire-and-forget — submits and exits with the render_id.", default: true, }, output: { diff --git a/packages/cli/src/commands/events.ts b/packages/cli/src/commands/events.ts index a381f7f043..0e9853f4a0 100644 --- a/packages/cli/src/commands/events.ts +++ b/packages/cli/src/commands/events.ts @@ -32,7 +32,7 @@ export default defineCommand({ }, event: { type: "string", - description: "Event name: skill_invoked | skill_completed (default: skill_invoked)", + description: "Event name: skill_invoked | skill_completed", default: "skill_invoked", }, outcome: { diff --git a/packages/cli/src/commands/layout.ts b/packages/cli/src/commands/layout.ts index de47b2c99d..67cf7c795c 100644 --- a/packages/cli/src/commands/layout.ts +++ b/packages/cli/src/commands/layout.ts @@ -454,7 +454,7 @@ export function createInspectCommand(commandName: "inspect" | "layout") { json: { type: "boolean", description: "Output agent-readable JSON", default: false }, samples: { type: "string", - description: "Number of midpoint samples across the duration (default: 9)", + description: "Number of midpoint samples across the duration", default: "9", }, at: { @@ -474,22 +474,22 @@ export function createInspectCommand(commandName: "inspect" | "layout") { }, tolerance: { type: "string", - description: "Allowed pixel overflow before reporting an issue (default: 2)", + description: "Allowed pixel overflow before reporting an issue", default: "2", }, timeout: { type: "string", - description: "Ms to wait for runtime to initialize (default: 5000)", + description: "Ms to wait for runtime to initialize", default: "5000", }, "max-issues": { type: "string", - description: "Maximum issues to print or return after static collapse (default: 80)", + description: "Maximum issues to print or return after static collapse", default: "80", }, "collapse-static": { type: "boolean", - description: "Collapse repeated static issues across samples (default: true)", + description: "Collapse repeated static issues across samples", default: true, }, strict: { diff --git a/packages/cli/src/commands/measure/extract.ts b/packages/cli/src/commands/measure/extract.ts index 310487a8be..055fe2d345 100644 --- a/packages/cli/src/commands/measure/extract.ts +++ b/packages/cli/src/commands/measure/extract.ts @@ -161,7 +161,7 @@ export default defineCommand({ to: { type: "string", description: "A clip's end second" }, audio: { type: "boolean", - description: "Keep the clip's sound (default: picture only)", + description: "Keep the clip's sound instead of picture only", default: false, }, crf: { type: "string", description: "Clip quality, lower is better (default 14)" }, diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.ts index 54b8857213..cab34665bb 100644 --- a/packages/cli/src/commands/preview.ts +++ b/packages/cli/src/commands/preview.ts @@ -199,7 +199,7 @@ export default defineCommand({ }, "lint-verbose": { type: "boolean", - description: "Show full lint findings on startup (default: a one-line summary)", + description: "Show full lint findings on startup instead of a one-line summary", default: false, }, open: { diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts index d20b6e59bd..ddc9e79f30 100644 --- a/packages/cli/src/commands/publish.ts +++ b/packages/cli/src/commands/publish.ts @@ -98,7 +98,7 @@ export default defineCommand({ }, "lint-verbose": { type: "boolean", - description: "Show full lint findings before publishing (default: a one-line summary)", + description: "Show full lint findings before publishing instead of a one-line summary", default: false, }, }, diff --git a/packages/cli/src/commands/remove-background.ts b/packages/cli/src/commands/remove-background.ts index 82cac9812f..a4903da9d2 100644 --- a/packages/cli/src/commands/remove-background.ts +++ b/packages/cli/src/commands/remove-background.ts @@ -79,7 +79,7 @@ export default defineCommand({ }, quality: { type: "string", - description: `Encoder quality preset for .webm output: ${QUALITIES.join(", ")} (default: ${DEFAULT_QUALITY}). Higher quality = closer color match when overlaying on the source mp4, larger file. Ignored for .mov / .png.`, + description: `Encoder quality preset for .webm output: ${QUALITIES.join(", ")}. Higher quality = closer color match when overlaying on the source mp4, larger file. Ignored for .mov / .png.`, default: DEFAULT_QUALITY, }, info: { diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index a46d143937..d72083ad0e 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -240,7 +240,7 @@ export default defineCommand({ "video-frame-format": { type: "string", description: - "Source video frame extraction format: auto, jpg, png (default: auto). " + + "Source video frame extraction format: auto, jpg, png. " + "Use png for UI recordings, screen captures, and color-sensitive source videos; " + "alpha-capable sources always extract as PNG.", default: "auto", diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts index 3eb6bb3fc3..4135168093 100644 --- a/packages/cli/src/commands/snapshot.ts +++ b/packages/cli/src/commands/snapshot.ts @@ -1799,7 +1799,7 @@ export default defineCommand({ }, frames: { type: "string", - description: "Number of evenly-spaced frames to capture (default: 5)", + description: "Number of evenly-spaced frames to capture", default: "5", }, at: { @@ -1819,7 +1819,7 @@ export default defineCommand({ }, timeout: { type: "string", - description: `Ms to wait for the composition to become render-ready, and for each still's seek to settle, up to 170 s (default: ${RENDER_READY_TIMEOUT_MS})`, + description: `Ms to wait for the composition to become render-ready, and for each still's seek to settle, up to 170 s`, default: String(RENDER_READY_TIMEOUT_MS), }, angle: { @@ -1830,7 +1830,7 @@ export default defineCommand({ end: { type: "boolean", description: - "Always include a readable end-of-timeline frame (default: true). Pass --no-end to capture only your exact --at times.", + "Always include a readable end-of-timeline frame. Pass --no-end to capture only your exact --at times.", default: true, }, keep: { @@ -1846,7 +1846,7 @@ export default defineCommand({ }, "zoom-scale": { type: "string", - description: "Device-scale-factor density for --zoom crops (default: 3)", + description: "Device-scale-factor density for --zoom crops", default: "3", }, against: { diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts index 98ff0fc0c7..f86e9b04a7 100644 --- a/packages/cli/src/commands/validate.ts +++ b/packages/cli/src/commands/validate.ts @@ -660,7 +660,7 @@ Examples: timeout: { type: "string", description: - "Ms to wait for scripts to settle and media to load (default: 3000). Also raises the " + + "Ms to wait for scripts to settle and media to load. Also raises the " + "page-navigation budget above its 10s floor when a slow external