An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): say when gap-report's inputs are required (#6518)
Joeybedd8dbca0f9
diff --git a/.changeset/cli-spec-gap-report-control-docs.md b/.changeset/cli-spec-gap-report-control-docs.mdnew file mode 100644index 0000000000..377066bb5f--- /dev/null+++ b/.changeset/cli-spec-gap-report-control-docs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx gap-report --help` and `astryx manifest` now describe the `component` argument and say that `component`, `--category`, and `--reason` are required unless `--list-categories` is set, with the character limits the command enforces. The manifest listed the argument with an empty description, and nothing said these inputs were required.++@josephfarinadiff --git a/packages/cli/api/gap-report/gap-report.doc.mjs b/packages/cli/api/gap-report/gap-report.doc.mjsindex 7b2bf26ebd..7a78527a1b 100644--- a/packages/cli/api/gap-report/gap-report.doc.mjs+++ b/packages/cli/api/gap-report/gap-report.doc.mjs@@ -32,17 +32,19 @@ export const doc = {name: 'component',type: 'string',description:- 'Component or general design-system area. Required unless listCategories is true.',+ 'Component or general design-system area, up to 120 characters. Required unless listCategories is true.',},{name: 'options.category',type: 'GapReportCategory',- description: 'Fixed category from the reported category vocabulary.',+ description:+ 'Fixed category from the reported category vocabulary. Required unless listCategories is true.',},{name: 'options.reason',type: 'string',- description: 'What capability was missing or difficult.',+ description:+ 'What capability was missing or difficult, up to 2000 characters. Required unless listCategories is true.',},{name: 'options.detail',@@ -65,7 +67,8 @@ export const doc = {{name: 'options.listCategories',type: 'boolean',- description: 'Return categories without resolving a route or writing.',+ description:+ 'Return categories without resolving a route or writing; the component and every other option are ignored.',default: 'false',},{diff --git a/packages/cli/clients/cli/commands/gap-report.doc.mjs b/packages/cli/clients/cli/commands/gap-report.doc.mjsindex 2cb9ce86ff..38e0405df8 100644--- a/packages/cli/clients/cli/commands/gap-report.doc.mjs+++ b/packages/cli/clients/cli/commands/gap-report.doc.mjs@@ -15,22 +15,32 @@ export const doc = {description:'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',fn: 'gapReport',- args: [{name: 'component', param: 'component', required: false}],+ args: [+ {+ name: 'component',+ param: 'component',+ required: false,+ description:+ 'Component or design-system area the gap is about, up to 120 characters. Required unless --list-categories is set.',+ },+ ],options: [{flag: '--category <category>',param: 'options.category',- description: 'Gap category (run --list-categories for values)',+ description:+ 'Gap category (run --list-categories for values). Required unless --list-categories is set.',},{flag: '--reason <reason>',param: 'options.reason',- description: 'What capability was missing or difficult',+ description:+ 'What capability was missing or difficult, up to 2000 characters. Required unless --list-categories is set.',},{flag: '--additional-context <text>',param: 'options.detail',- description: 'Optional additional context',+ description: 'Optional additional context, up to 8000 characters',},{flag: '--package <pkg>',@@ -45,7 +55,8 @@ export const doc = {{flag: '--list-categories',param: 'options.listCategories',- description: 'List valid report categories without filing',+ description:+ 'List valid report categories without filing; the component and the other gap-report options are ignored',},],examples: [diff --git a/packages/cli/clients/cli/commands/gap-report.test.mjs b/packages/cli/clients/cli/commands/gap-report.test.mjsindex a23a0ace9b..3db23ce4f2 100644--- a/packages/cli/clients/cli/commands/gap-report.test.mjs+++ b/packages/cli/clients/cli/commands/gap-report.test.mjs@@ -196,3 +196,75 @@ export default {};\n`,});});});++describe('gap-report control docs', () => {+ const REQUIRED = 'Required unless --list-categories is set.';++ it('help and manifest say which inputs are required and how long they may be', async () => {+ const help = await runCli(['gap-report', '--help']);+ expect(help.status).toBe(0);+ const manifest = JSON.parse((await runCli(['manifest', '--json'])).stdout);+ const entry = manifest.data.commands.find(+ (/** @type {{name: string}} */ command) => command.name === 'gap-report',+ );+ /** @param {string} flag @returns {string} */+ const option = flag =>+ entry.options.find(+ (/** @type {{flag: string}} */ item) => item.flag.split(' ')[0] === flag,+ )?.description ?? '';+ const component = entry.arguments[0].description;++ for (const text of [component, option('--category'), option('--reason')]) {+ expect(text).toContain(REQUIRED);+ expect(help.stdout).toContain(text);+ }+ expect(option('--list-categories')).toContain(+ 'the component and the other gap-report options are ignored',+ );++ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-limits-'));+ try {+ fs.writeFileSync(+ path.join(cwd, 'package.json'),+ JSON.stringify({name: 'fixture-app'}),+ );+ const base = {cwd, category: /** @type {const} */ ('docs_gap'), reason: 'x'};+ /** @type {Array<[string, (value: string) => Promise<unknown>]>} */+ const limits = [+ [component, value => gapReport(value, base)],+ [option('--reason'), value => gapReport('Button', {...base, reason: value})],+ [+ option('--additional-context'),+ value => gapReport('Button', {...base, detail: value}),+ ],+ ];+ for (const [text, call] of limits) {+ const limit = Number(/up to (\d+) characters/.exec(text)?.[1]);+ expect(limit, text).toBeGreaterThan(0);+ await expect(call('x'.repeat(limit))).resolves.toMatchObject({+ type: 'gap-report.file',+ });+ await expect(call('x'.repeat(limit + 1))).rejects.toMatchObject({+ code: 'ERR_INVALID_ARGUMENT',+ });+ }+ } finally {+ fs.rmSync(cwd, {recursive: true, force: true});+ }+ });++ it('enforces the documented requirement', async () => {+ for (const [component, options] of [+ [undefined, {category: 'docs_gap', reason: 'x'}],+ ['Button', {reason: 'x'}],+ ['Button', {category: 'docs_gap'}],+ ]) {+ await expect(gapReport(component, options)).rejects.toMatchObject({+ code: 'ERR_MISSING_ARGUMENT',+ });+ }+ await expect(+ gapReport(undefined, {listCategories: true, category: 'not_real', package: 'nope'}),+ ).resolves.toMatchObject({type: 'gap-report.categories'});+ });+});