Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/gap-report/gap-report.doc.mjs b/packages/cli/api/gap-report/gap-report.doc.mjs
index 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.mjs
index 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.mjs
index 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'});
+ });
+});