@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/clients/cli/commands/doctor-integration.test.mjs

@@ -2,10 +2,18 @@
 
 /**
  * @file Command-level coverage for `astryx doctor integration` authoring checks.
+ * @input Integration fixtures and the post-0.7 conflict projection.
+ * @output Assertions for human and typed command responses.
+ * @position CLI adapter coverage; 0.6.x API shape is verified separately.
  */
 
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+vi.mock('../../../foundation/discovery/template-conflict-release.mjs', () => ({
+  expandedTemplateConflictSchemaActive: () => true,
+}));
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import {Command} from 'commander';
 import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
@@ -31,6 +39,8 @@ function writeIntegration({
   id,
   name = 'Integration template',
   missingRoot = false,
+  replacements,
+  type = 'page',
 }) {
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
@@ -44,8 +54,8 @@ function writeIntegration({
   const stem = path.join(tmpDir, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
-    `export default {type: 'page', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
+    `${stem}.doc.mjs`,
+    `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'${replacements?.[id] == null ? '' : `, replaces: ${JSON.stringify(replacements[id])}`}};\n`,
   );
   fs.writeFileSync(
     `${stem}.tsx`,
@@ -124,7 +134,12 @@ describe('doctor integration — command', () => {
       return true;
     });
 
-    await createProgram().parseAsync(['node', 'astryx', 'doctor', 'integration']);
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+    ]);
 
     const output = writes.join('');
     expect(output).toContain('validate [package]');
@@ -136,7 +151,9 @@ describe('doctor integration — command', () => {
 
   it('explains the optional package argument in every leaf help', () => {
     const program = createProgram();
-    const doctor = program.commands.find(command => command.name() === 'doctor');
+    const doctor = program.commands.find(
+      command => command.name() === 'doctor',
+    );
     const integration = doctor?.commands.find(
       command => command.name() === 'integration',
     );
@@ -152,7 +169,10 @@ describe('doctor integration — command', () => {
   });
 
   it('templates explains how to check an installed package when no local manifest exists', async () => {
-    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'plain'}));
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
     process.chdir(tmpDir);
 
     await createProgram().parseAsync([
@@ -239,6 +259,71 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('templates reports an intentional replacement and the Core-original command', async () => {
+    const core = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      type: core.type,
+      replacements: {'acme-app-shell': core.dirName},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual([]);
+    expect(parsed.data.conflicts).toEqual([
+      expect.objectContaining({
+        id: 'acme-app-shell',
+        relationship: 'replaces',
+        replaces: core.dirName,
+        severity: 'info',
+      }),
+    ]);
+    expect(parsed.data.conflicts[0].command).toContain(
+      `--package @astryxdesign/core`,
+    );
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('templates exits 1 for a missing replacement target', async () => {
+    writeIntegration({
+      id: 'acme-app-shell',
+      replacements: {'acme-app-shell': 'missing-core-shell'},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          severity: 'error',
+        }),
+      ]),
+    );
+    expect(process.exitCode).toBe(1);
+  });
+
   it('templates exits 1 when structural errors prevent a trustworthy check', async () => {
     writeIntegration({missingRoot: true});
     process.chdir(tmpDir);
@@ -260,6 +345,35 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBe(1);
   });
 
+  it('components exits 1 when Core is missing, with no [ok] after the failure', async () => {
+    // Outside the repo, so nothing above the package resolves Core.
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-core-'));
+    const previousTmp = tmpDir;
+    tmpDir = outside;
+    try {
+      writeComponentIntegration('AcmeCarousel');
+      expect(findCoreDir(outside)).toBeNull();
+      process.chdir(outside);
+
+      await createProgram().parseAsync([
+        'node',
+        'astryx',
+        'doctor',
+        'integration',
+        'components',
+      ]);
+
+      const printed = logCalls.join('\n');
+      expect(printed).toContain('core_not_found');
+      expect(printed).not.toContain('[ok]');
+      expect(process.exitCode).toBe(1);
+    } finally {
+      tmpDir = previousTmp;
+      process.chdir(previousCwd);
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
+
   it('components warns with the exact package-qualified command', async () => {
     const coreDir = findCoreDir(tmpDir);
     expect(coreDir).not.toBeNull();
@@ -278,9 +392,7 @@ describe('doctor integration — command', () => {
     const output = logCalls.join('\n');
     expect(output).toContain('[warn]');
     expect(output).toContain(core.name);
-    expect(output).toContain(
-      `component ${core.name} --package @acme/widgets`,
-    );
+    expect(output).toContain(`component ${core.name} --package @acme/widgets`);
     expect(process.exitCode).toBeUndefined();
   });
 
@@ -351,6 +463,29 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('docs exits 1 for a placement that hides a guide, with no [ok] after the failure', async () => {
+    writeDocIntegration({name: 'deploying'});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
+      "export default {type: 'generic', name: 'deploying', title: 'Deploying', description: 'Deploy.', placement: {parent: 'namespace:nope', slot: 'guides'}, sections: [{title: 'Deploy', content: [{type: 'prose', text: 'Deploy.'}]}]};\n",
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'docs',
+    ]);
+
+    const printed = logCalls.join('\n');
+    expect(printed).toContain('[fail]');
+    expect(printed).toContain('invalid_doc_graph');
+    expect(printed).not.toContain('[ok]');
+    expect(process.exitCode).toBe(1);
+  });
+
   it('docs exits 1 for an accidental same-name Core topic', async () => {
     const [coreTopic] = Object.keys(discoverBuiltinTopics());
     writeDocIntegration({name: coreTopic});

package/clients/cli/commands/doctor.doc.mjs

@@ -12,11 +12,13 @@ export const doc = {
   type: 'command',
   name: 'doctor',
   displayName: 'astryx doctor',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Diagnose Astryx projects and integration packages',
   description:
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
-    'install and version alignment, themes, config, agent docs, and package manager. ' +
+    'install and version alignment, themes, config, integrations (linked without a config entry, ' +
+    'provider identity, contribution issues), agent docs, core peer dependencies, package manager, ' +
+    "and the docs the CLI reads. It writes nothing, but loading astryx.config runs that file's code. " +
     'The `integration` subcommands provide authoring checks for one integration package.',
   fn: 'doctor',
   subcommands: ['integration'],

package/clients/cli/commands/doctor.mjs

@@ -3,7 +3,12 @@
 /**
  * @file `astryx doctor` project health and integration-authoring diagnostics.
  * Human output uses plain stable tokens; every leaf also has a typed JSON
- * response. Exit 1 means a check found an error, while warnings remain exit 0.
+ * response. Template-conflict fields follow the package release boundary.
+ * Exit 1 means a check found an error, while warnings remain exit 0.
+ *
+ * @input Typed Doctor and integration-authoring API responses.
+ * @output Human-readable records or pass-through typed JSON.
+ * @position CLI presentation adapter for project and integration health.
  */
 
 import {runChecks} from '../../../api/doctor/doctor.mjs';
@@ -17,7 +22,7 @@ import {
   validateIntegration,
 } from '../../../api/integration/validate-integration.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, records, text} from '../formatters/index.mjs';
+import {emit, section, record, records, text} from '../formatters/index.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as doctorCommand} from './doctor.doc.mjs';
 import {doc as doctorIntegrationGroup} from './doctor-integration.doc.mjs';
@@ -31,6 +36,8 @@ import {doc as integrationTemplateConflictsFn} from '../../../api/integration/in
 import {doc as integrationComponentConflictsFn} from '../../../api/integration/integrationComponentConflicts.doc.mjs';
 import {doc as integrationDocConflictsFn} from '../../../api/integration/integrationDocConflicts.doc.mjs';
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 
 const STATUS = {
   pass: '[ok]',
@@ -55,7 +62,7 @@ function integrationLabel(data) {
  * @param {import('../../../api/doctor/doctor.mjs').DoctorReport} report
  */
 function printHuman(report) {
-  const {pass, warn, fail, info} = report.summary;
+  const {warn, fail} = report.summary;
   const closing =
     fail > 0
       ? 'Some checks failed. Address the items marked [fail] above.'
@@ -63,18 +70,15 @@ function printHuman(report) {
         ? 'No failures — but review the [warn] warnings above when you can.'
         : 'All checks passed. Your Astryx setup looks healthy.';
 
+  // Field names are the JSON keys, so text and --json map one to one.
   emit(
     section('astryx doctor — diagnosing your setup'),
     records(report.checks, {
-      fields: ['status', 'label', 'message', 'fix'],
-      labels: {label: 'check'},
+      fields: ['id', 'status', 'label', 'message', 'fix'],
       format: {status: statusToken},
     }),
-    text(
-      `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
-        `${fail} failure${fail === 1 ? '' : 's'}` +
-        (info ? `, ${info} info` : ''),
-    ),
+    section('summary'),
+    record(report.summary, {fields: ['pass', 'warn', 'fail', 'info']}),
     text(closing),
   );
 }
@@ -128,25 +132,41 @@ function printTemplateConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
-  if (data.conflicts.length === 0) {
+  if (data.conflicts.length === 0 && data.issues.length === 0) {
     output.push(text('[ok] No template ids conflict with Core.'));
-  } else {
+  } else if (data.conflicts.length > 0) {
+    const expanded = data.conflicts.some(
+      conflict => 'relationship' in conflict,
+    );
     output.push(
       records(data.conflicts, {
-        fields: [
-          'severity',
-          'id',
-          'integrationPackage',
-          'integrationType',
-          'integrationName',
-          'message',
-          'command',
-        ],
+        fields: expanded
+          ? [
+              'severity',
+              'relationship',
+              'id',
+              'replaces',
+              'integrationPackage',
+              'integrationType',
+              'integrationName',
+              'message',
+              'command',
+            ]
+          : [
+              'severity',
+              'id',
+              'integrationPackage',
+              'integrationType',
+              'integrationName',
+              'message',
+              'command',
+            ],
         format: {severity: statusToken},
       }),
       text(
-        `${data.conflicts.length} Core template conflict(s). ` +
-          'Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.',
+        expanded
+          ? `${data.conflicts.length} Core template relationship(s).`
+          : `${data.conflicts.length} Core template conflict(s). Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.`,
       ),
     );
   }
@@ -163,12 +183,20 @@ function printComponentConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
+  // An [ok] after a failed check reads as a pass: say nothing it could not check.
+  const failed = data.issues.some(issue => issue.severity === 'error');
   if (data.conflicts.length === 0) {
-    output.push(text('[ok] No component names conflict with Core.'));
+    if (!failed) output.push(text('[ok] No component names conflict with Core.'));
   } else {
     output.push(
       records(data.conflicts, {
-        fields: ['severity', 'name', 'integrationPackage', 'message', 'command'],
+        fields: [
+          'severity',
+          'name',
+          'integrationPackage',
+          'message',
+          'command',
+        ],
         format: {severity: statusToken},
       }),
       text(
@@ -190,8 +218,19 @@ function printDocConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
+  if (
+    !data.issues.some(
+      issue => issue.severity === 'error' || issue.code === 'invalid_doc_graph',
+    )
+  ) {
+    output.push(
+      text('[ok] The docs tree and every link in these docs check out.'),
+    );
+  }
   if (data.findings.length === 0) {
-    output.push(text('[ok] No doc topics overlap with Core.'));
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] No doc topics overlap with Core.'));
+    }
   } else {
     output.push(
       records(data.findings, {
@@ -275,32 +314,64 @@ async function runAuthoringCheck(program, pkg, kind) {
   const structuralErrors = summarizeIssues(result.data.issues).errors;
   const docErrors =
     result.type === 'integration.doc-conflicts'
-      ? result.data.findings.filter(finding => finding.severity === 'error').length
+      ? result.data.findings.filter(finding => finding.severity === 'error')
+          .length
       : 0;
   if (structuralErrors > 0 || docErrors > 0) process.exitCode = 1;
   return NO_RESULT_SET;
 }
 
+/**
+ * The first word after a command group, which names a subcommand it does not
+ * have, or null.
+ * @param {import('commander').Command | undefined} invoked
+ * @returns {string | null}
+ */
+function unknownWord(invoked) {
+  const word = (invoked?.args ?? []).find(arg => !String(arg).startsWith('-'));
+  return word == null ? null : String(word);
+}
+
+/**
+ * Report an unknown subcommand, in text as in JSON, with the ones the group has.
+ * @param {import('commander').Command} group
+ * @param {string} label the group's full name
+ * @param {string} word
+ */
+function unknownSubcommand(group, label, word) {
+  return cliError(`unknown subcommand '${label} ${word}'`, {
+    suggestions: group.commands.map(child => ({
+      name: child.name(),
+      reason: 'available subcommand',
+    })),
+    code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
+  });
+}
+
 /**
  * Register `astryx doctor` and its integration-authoring leaves.
  * @param {import('commander').Command} program
  */
 export function registerDoctor(program) {
-  const doctorCmd = defineCommand(program, doctorCommand, {
+  /** @type {import('commander').Command} */
+  let doctorCmd;
+  doctorCmd = defineCommand(program, doctorCommand, {
     fn: doctorFn,
-    action: async () => runProjectDoctor(program),
+    // `doctor integrations` is a mistyped subcommand, not a project check.
+    action: async (options, invoked) => {
+      const word = unknownWord(invoked);
+      if (word != null) return unknownSubcommand(doctorCmd, 'doctor', word);
+      return runProjectDoctor(program);
+    },
   });
-  doctorCmd.addHelpText(
-    'after',
-    '\nExit code:\n' +
-      '  0  no failures (warnings are allowed) — safe as a CI gate\n' +
-      '  1  one or more checks failed\n',
-  );
-
   /** @type {import('commander').Command} */
   let integrationCmd;
   integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {
-    action: () => {
+    action: (options, invoked) => {
+      const word = unknownWord(invoked);
+      if (word != null) {
+        return unknownSubcommand(integrationCmd, 'doctor integration', word);
+      }
       integrationCmd.outputHelp();
       return NO_RESULT_SET;
     },

package/clients/cli/commands/doctor.test.mjs

@@ -354,3 +354,45 @@ describe('doctor — command', () => {
     }
   });
 });
+
+describe('doctor — text output mirrors the JSON', () => {
+  /** @param {string} line */
+  const field = line => /^(\w+):\s+(.*)$/.exec(line)?.slice(1) ?? [line, ''];
+
+  it('prints every check and summary field under its JSON key', async () => {
+    const prevCwd = process.cwd();
+    const prevExit = process.exitCode;
+    process.chdir(tmpDir);
+    try {
+      await createProgram().parseAsync(['node', 'astryx', '--json', 'doctor']);
+      const {checks, summary} = JSON.parse(logCalls.join('\n')).data;
+      logCalls = [];
+      await createProgram().parseAsync(['node', 'astryx', 'doctor']);
+      const blocks = logCalls
+        .join('\n')
+        .split(/\n{2,}/)
+        .map(block => block.split('\n').map(field));
+
+      for (const check of checks) {
+        const block = blocks.find(fields =>
+          fields.some(([key, value]) => key === 'id' && value === check.id),
+        );
+        expect(block, `no text record for check ${check.id}`).toBeDefined();
+        expect(
+          /** @type {string[][]} */ (block).map(([key]) => key).sort(),
+        ).toEqual(Object.keys(check).sort());
+      }
+
+      const heading = blocks.findIndex(
+        fields => fields.length === 1 && fields[0][0] === 'summary',
+      );
+      expect(heading, 'no summary section').toBeGreaterThan(-1);
+      expect(blocks[heading + 1]).toEqual(
+        Object.entries(summary).map(([key, count]) => [key, String(count)]),
+      );
+    } finally {
+      process.chdir(prevCwd);
+      process.exitCode = prevExit;
+    }
+  }, 60_000);
+});

package/clients/cli/commands/gap-report.doc.mjs

@@ -10,54 +10,66 @@ export const doc = {
   type: 'command',
   name: 'gap-report',
   displayName: 'astryx gap-report',
-  namespace: 'cli',
-  summary: 'Route a design-system gap to its owning package',
+  namespace: 'cli/commands',
+  summary: 'Report a missing component or feature to the package that owns it',
   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.',
+    'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability to the package that owns it: the --package you name, else the one package that provides the component, else Core. ' +
+    'Every configured handler receives the report: the project config handler first, then each integration handler in config order. Public handlers run only with --confirm-public; internal handlers always run. A failing handler does not stop the others. ' +
+    "With no handler it files a GitHub issue for the owning package, only with --confirm-public (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+    'The report records whether an agent or a person ran it.',
   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>',
       param: 'options.package',
-      description: 'Route to a specific loaded package',
+      description:
+        'Package that owns the gap: @astryxdesign/core or a loaded integration. Overrides automatic routing; needed when more than one package provides the component',
     },
     {
       flag: '--confirm-public',
       param: 'options.confirmPublic',
-      description: 'Consent to public handlers or GitHub issue creation',
+      description:
+        'Allow public delivery: public handlers run, and with no handler it files a GitHub issue with your gh login',
     },
     {
       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: [
     {label: 'List categories', cli: 'astryx gap-report --list-categories'},
     {
-      label: 'Route an agent report',
+      label: 'Prepare a report (nothing public happens without --confirm-public)',
       cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size'",
     },
-    {
-      label: 'Confirm public filing',
-      cli: "astryx gap-report Button --category docs_gap --reason 'Missing keyboard example' --confirm-public",
-    },
   ],
   exitCodes: [
     {

package/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'});
+  });
+});