@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/api/doctor/doctor.mjs

@@ -34,8 +34,8 @@ import {
   docsIndexBytes,
   oversizedDocSections,
 } from '../../foundation/discovery/docs-output-budget.mjs';
-import {compileTopic, overlayLanguages} from '../docs/_adapter.mjs';
-import {detailView} from '../../foundation/doc-compiler/lenses.mjs';
+import {compileTopic, lowerTopic, overlayLanguages} from '../docs/_adapter.mjs';
+import {detailView, indexView} from '../../foundation/doc-compiler/lenses.mjs';
 import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
 
 /**
@@ -721,38 +721,144 @@ function joinProblems(problems) {
     : `${problems.length} problems: ${problems.join('; ')}`;
 }
 
+/** How the self-doc audit's problems are fixed. */
+const AUTHORING_DOCS_FIX =
+  'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.';
+
+/** How the public-surface audit's problems are fixed. */
+const AUTHORING_SURFACE_FIX =
+  'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
+
+/** Types one problem names before it counts the rest. */
+const NAMED_TYPES = 40;
+
+/**
+ * @param {string[]} names
+ * @returns {string}
+ */
+function nameTypes(names) {
+  return names.length <= NAMED_TYPES
+    ? names.join(', ')
+    : `${names.slice(0, NAMED_TYPES).join(', ')} and ${names.length - NAMED_TYPES} more`;
+}
+
+/**
+ * The section keys `astryx docs authoring --index` lists, read the way that
+ * command reads them.
+ * @returns {Promise<{keys: Set<string>} | {keys: null, error: string}>}
+ */
+async function authoringTopicKeys() {
+  try {
+    const catalog = DocsCatalog.fromBuiltins();
+    const entry = catalog.resolve('authoring');
+    if (!entry) return {keys: null, error: 'it is not a built-in topic'};
+    const index = indexView(await lowerTopic(catalog, entry));
+    return {keys: new Set(index.sections.map(section => section.id))};
+  } catch (err) {
+    return {
+      keys: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof import('../../foundation/discovery/authoring-surface.mjs').auditAuthoringSurface>>} surface
+ * @returns {string[]}
+ */
+function surfaceProblems(surface) {
+  /** @type {string[]} */
+  const problems = [];
+  if (surface.types === 0 && surface.untraced.length === 0) {
+    problems.push(
+      '@astryxdesign/cli/authoring exports no types, so nothing was compared with `astryx docs authoring`',
+    );
+  }
+  for (const {module, names, reason, source, key} of surface.unreadable) {
+    const why =
+      reason === 'no-self-doc'
+        ? `no self-doc sits beside ${module}`
+        : reason === 'unregistered'
+          ? `${source} is not listed in AUTHORING_SELF_DOCS`
+          : reason === 'failed'
+            ? `${source} does not load`
+            : `${source} renders section "${key}", which the topic's index does not list`;
+    problems.push(
+      `${nameTypes(names)} from ${module} ${names.length === 1 ? 'has' : 'have'} no doc in \`astryx docs authoring\`: ${why}`,
+    );
+  }
+  for (const {name, reason} of surface.untraced) {
+    problems.push(
+      `${name} cannot be traced to the module that declares it: ${reason}`,
+    );
+  }
+  for (const {source, subject} of surface.unmatched) {
+    problems.push(
+      subject
+        ? `${source} documents ${subject}, which @astryxdesign/cli/authoring does not export`
+        : `${source} documents no type @astryxdesign/cli/authoring exports`,
+    );
+  }
+  return problems;
+}
+
 /**
  * Every authoring self-doc is reachable from `astryx docs authoring`, loads,
- * and fits in one read. The audit is imported here, inside the try, so a
- * malformed self-doc is reported rather than taking Doctor down.
+ * and fits in one read, and every type `@astryxdesign/cli/authoring` exports
+ * has its doc there: the self-doc beside the module that declares it. The
+ * audits are imported here, inside the try, so a malformed self-doc is
+ * reported rather than taking Doctor down.
  * @param {DoctorContext} [_ctx]
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   Another authoring tree, list, or topic index to audit (for tests).
  * @returns {Promise<DoctorCheck>}
  */
-export async function checkAuthoringDocs(_ctx) {
+export async function checkAuthoringDocs(_ctx, options = {}) {
   const id = 'authoring-docs';
   const label = 'Authoring docs';
   try {
-    const {auditAuthoringSelfDocs} = await import(
-      '../../foundation/discovery/authoring-self-docs.mjs'
-    );
-    const audit = await auditAuthoringSelfDocs();
+    const {auditAuthoringSelfDocs} =
+      await import('../../foundation/discovery/authoring-self-docs.mjs');
+    const {auditAuthoringSurface} =
+      await import('../../foundation/discovery/authoring-surface.mjs');
+    const {root, sources} = options;
+    const audit = await auditAuthoringSelfDocs({root, sources});
     const problems = [
       ...audit.unreachable.map(
         source => `${source} is not in \`astryx docs authoring\``,
       ),
-      ...audit.failed.map(({source, error}) => `${source} failed to load: ${error}`),
+      ...audit.failed.map(
+        ({source, error}) => `${source} failed to load: ${error}`,
+      ),
       ...audit.oversized.map(
         ({key, bytes}) =>
           `authoring section "${key}" is ${kilobytes(bytes)}, over the ${kilobytes(DOC_OUTPUT_BUDGET_BYTES)} one read may return`,
       ),
     ];
-    if (problems.length > 0) {
+    const topic =
+      options.topicKeys === undefined
+        ? await authoringTopicKeys()
+        : {keys: options.topicKeys};
+    const surface = [
+      ...('error' in topic
+        ? [`\`astryx docs authoring\` could not be read: ${topic.error}`]
+        : []),
+      ...surfaceProblems(
+        await auditAuthoringSurface({root, sources, topicKeys: topic.keys}),
+      ),
+    ];
+    if (problems.length + surface.length > 0) {
       return {
         id,
         label,
         status: 'fail',
-        message: joinProblems(problems),
-        fix: 'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.',
+        message: joinProblems([...problems, ...surface]),
+        fix: [
+          problems.length > 0 ? AUTHORING_DOCS_FIX : null,
+          surface.length > 0 ? AUTHORING_SURFACE_FIX : null,
+        ]
+          .filter(Boolean)
+          .join(' '),
       };
     }
     return {
@@ -772,6 +878,71 @@ export async function checkAuthoringDocs(_ctx) {
   }
 }
 
+/** How the CLI-docs audit's problems are fixed. */
+const CLI_DOCS_FIX =
+  "Set `namespace` on each CLI doc to the one that reads it: cli/commands for a command, cli/api for an API function or the output schema, error codes, and response types, and authoring for a file an author writes (and list it in AUTHORING_SELF_DOCS).";
+
+/**
+ * Every command, API function, schema, and enum doc the CLI ships declares a
+ * namespace, and the topic that namespace names reads it: `astryx docs cli`
+ * for `cli/commands` and `cli/api`, `astryx docs authoring` for `authoring`.
+ * @param {DoctorContext | Partial<DoctorContext>} _ctx
+ * @param {{root?: string, sources?: string[], authoringSources?: string[]}} [options]
+ *   test seams: the CLI root, the docs to audit, and the authoring topic's list
+ * @returns {Promise<DoctorCheck>}
+ */
+export async function checkCliDocs(_ctx, options = {}) {
+  const id = 'cli-docs';
+  const label = 'CLI docs';
+  try {
+    const {auditCliSelfDocs} =
+      await import('../../foundation/discovery/cli-self-docs.mjs');
+    const audit = await auditCliSelfDocs(options);
+    const problems = [
+      ...audit.missing.map(
+        source =>
+          `${source} has no namespace, so no \`astryx docs\` topic reads it`,
+      ),
+      ...audit.unknown.map(
+        ({source, namespace}) =>
+          `${source} has namespace "${namespace}", which no \`astryx docs\` topic reads`,
+      ),
+      ...audit.misfiled.map(({message}) => message),
+      ...audit.failed.map(
+        ({source, error}) => `${source} failed to load: ${error}`,
+      ),
+      ...audit.keyProblems.map(problem => `\`astryx docs cli\`: ${problem}`),
+      ...audit.oversized.map(
+        ({key, bytes}) =>
+          `cli section "${key}" is ${kilobytes(bytes)}, over the ${kilobytes(DOC_OUTPUT_BUDGET_BYTES)} one read may return`,
+      ),
+    ];
+    if (problems.length > 0) {
+      return {
+        id,
+        label,
+        status: 'fail',
+        message: joinProblems(problems),
+        fix: CLI_DOCS_FIX,
+      };
+    }
+    return {
+      id,
+      label,
+      status: 'pass',
+      message: `All ${audit.docs} CLI docs are readable: ${audit.sections} in \`astryx docs cli\` and ${audit.authoring} in \`astryx docs authoring\`.`,
+    };
+  } catch (err) {
+    return {
+      id,
+      label,
+      status: 'fail',
+      message: `The CLI docs could not be audited: ${err instanceof Error ? err.message : String(err)}`,
+      fix: 'Reinstall @astryxdesign/cli.',
+    };
+  }
+}
+
 /**
  * Every topic reads progressively, in every language it ships: it loads, its
  * section index and each of its sections fit in one read, and no contributed
@@ -823,7 +994,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
     return {
       id,
       label,
-      status: 'fail',
+      status: 'warn',
       message: joinProblems(problems),
       fix: 'Fix the doc each problem names; split a section that is too large into smaller ones, each with its own key.',
     };
@@ -929,6 +1100,7 @@ export async function runChecks(options = {}) {
     }
   }
   checks.push(await checkAuthoringDocs(ctx));
+  checks.push(await checkCliDocs(ctx));
   checks.push(await checkDocsProgressiveDisclosure(ctx));
 
   const summary = {pass: 0, warn: 0, fail: 0, info: 0};

package/api/doctor/doctor.test.mjs

@@ -6,15 +6,23 @@
  * invariant (the counts must always add up to the number of checks).
  */
 
-import {describe, it, expect, afterEach} from 'vitest';
+import {describe, it, expect, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
+import {
+  AUTHORING_ROOT,
+  AUTHORING_SELF_DOCS,
+  auditAuthoringSelfDocs,
+} from '../../foundation/discovery/authoring-self-docs.mjs';
+import {docs} from '../docs/docs.mjs';
+import {auditCliSelfDocs} from '../../foundation/discovery/cli-self-docs.mjs';
 import {
   doctor,
   checkAuthoringDocs,
+  checkCliDocs,
   checkDocsProgressiveDisclosure,
   checkImplicitIntegrations,
   checkProviderIdentity,
@@ -383,7 +391,7 @@ describe('checkDocsProgressiveDisclosure', () => {
     expect(c.message).toMatch(/^\d+ topics: /);
   }, SLOW);
 
-  it('fails on an invalid doc an integration contributed', async () => {
+  it('warns on an invalid doc an integration contributed', async () => {
     const c = await checkDocsProgressiveDisclosure({
       docsCatalogIssues: [
         {
@@ -394,13 +402,13 @@ describe('checkDocsProgressiveDisclosure', () => {
         },
       ],
     });
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toBe('@acme/widgets: bad.doc.mjs exports no doc');
   });
 
-  it('fails when the docs catalog cannot be built', async () => {
+  it('warns when the docs catalog cannot be built', async () => {
     const c = await checkDocsProgressiveDisclosure({docsCatalogError: 'boom'});
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toContain('boom');
   });
 
@@ -428,7 +436,7 @@ describe('checkDocsProgressiveDisclosure', () => {
       }),
       docsCatalogIssues: [],
     });
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toMatch(/^2 problems: /);
     expect(c.message).toContain('huge everything: 41 KB, over the 32 KB one read may return');
     expect(c.message).toContain('broken: ');
@@ -444,6 +452,323 @@ describe('checkAuthoringDocs', () => {
   }, SLOW);
 });
 
+describe('checkCliDocs', () => {
+  const CLI_DOCS_FIX =
+    'Set `namespace` on each CLI doc to the one that reads it: cli/commands for a command, cli/api for an API function or the output schema, error codes, and response types, and authoring for a file an author writes (and list it in AUTHORING_SELF_DOCS).';
+
+  /** A doc tree under the working directory, as the CLI root. */
+  function writeRoot(/** @type {Record<string, any>} */ docsByPath) {
+    const root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-cli-docs-'));
+    tmpDirs.push(root);
+    for (const [rel, doc] of Object.entries(docsByPath)) {
+      const file = path.join(root, rel);
+      fs.mkdirSync(path.dirname(file), {recursive: true});
+      fs.writeFileSync(file, `export const doc = ${JSON.stringify(doc)};\n`);
+    }
+    return root;
+  }
+
+  it(
+    'passes on this repo, counting where each CLI doc is read',
+    async () => {
+      const audit = await auditCliSelfDocs();
+      expect(await checkCliDocs()).toEqual({
+        id: 'cli-docs',
+        label: 'CLI docs',
+        status: 'pass',
+        message: `All ${audit.docs} CLI docs are readable: ${audit.sections} in \`astryx docs cli\` and ${audit.authoring} in \`astryx docs authoring\`.`,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'fails on a doc with no namespace and one no topic reads, and names the fix',
+    async () => {
+      const root = writeRoot({
+        'api/alpha/alpha.doc.mjs': {
+          type: 'function',
+          kind: 'api',
+          name: 'alpha',
+          displayName: 'alpha()',
+          summary: 'The alpha function.',
+          params: [],
+          returns: [{type: 'alpha', description: 'The alpha.'}],
+        },
+        'clients/cli/commands/beta.doc.mjs': {
+          type: 'command',
+          name: 'beta',
+          displayName: 'astryx beta',
+          namespace: 'cli',
+          summary: 'Do beta',
+        },
+      });
+      expect(
+        await checkCliDocs(undefined, {root, authoringSources: []}),
+      ).toEqual({
+        id: 'cli-docs',
+        label: 'CLI docs',
+        status: 'fail',
+        message:
+          '2 problems: api/alpha/alpha.doc.mjs has no namespace, so no `astryx docs` topic reads it; clients/cli/commands/beta.doc.mjs has namespace "cli", which no `astryx docs` topic reads',
+        fix: CLI_DOCS_FIX,
+      });
+    },
+    SLOW,
+  );
+});
+
+describe('checkAuthoringDocs against the public authoring surface', () => {
+  const NAMESPACE = 'doctypes/namespace/namespace.doc.mjs';
+  const NAMESPACE_TYPES =
+    'NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in `astryx docs authoring`';
+  const SURFACE_FIX =
+    'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
+
+  /** A copy of this repo's authoring tree, to break one piece of at a time. */
+  function copyAuthoring() {
+    const root = fs.mkdtempSync(
+      path.join(process.cwd(), '.astryx-doctor-authoring-'),
+    );
+    tmpDirs.push(root);
+    fs.cpSync(AUTHORING_ROOT, root, {
+      recursive: true,
+      filter: src => !src.endsWith('.test.mjs'),
+    });
+    return root;
+  }
+
+  /** @param {string} source */
+  const without = source => AUTHORING_SELF_DOCS.filter(s => s !== source);
+
+  /** @param {string} text */
+  const escape = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  it(
+    'passes on this repo and prints exactly what it printed before',
+    async () => {
+      expect(await checkAuthoringDocs()).toEqual({
+        id: 'authoring-docs',
+        label: 'Authoring docs',
+        status: 'pass',
+        message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`astryx docs authoring\`.`,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'passes on an unchanged copy of the tree, and writes nothing to it',
+    async () => {
+      const root = copyAuthoring();
+      const before = snapshot(root);
+      expect(await checkAuthoringDocs(undefined, {root})).toMatchObject({
+        status: 'pass',
+      });
+      expect(snapshot(root)).toEqual(before);
+    },
+    SLOW,
+  );
+
+  it(
+    'fails when the NamespaceDoc self-doc is left out of AUTHORING_SELF_DOCS',
+    async () => {
+      const root = copyAuthoring();
+      const c = await checkAuthoringDocs(undefined, {
+        root,
+        sources: without(NAMESPACE),
+      });
+      expect(c.status).toBe('fail');
+      expect(c.message).toBe(
+        `2 problems: ${NAMESPACE} is not in \`astryx docs authoring\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    "fails when the topic's index no longer exposes the NamespaceDoc section",
+    async () => {
+      const index = await docs('authoring', undefined, {index: true});
+      const topicKeys = new Set(
+        index.data.sections
+          .map((/** @type {any} */ s) => s.id)
+          .filter((/** @type {string} */ id) => id !== 'namespace-doc'),
+      );
+      const c = await checkAuthoringDocs(undefined, {topicKeys});
+      expect(c).toMatchObject({
+        status: 'fail',
+        message: `${NAMESPACE_TYPES}: ${NAMESPACE} renders section "namespace-doc", which the topic's index does not list`,
+        fix: SURFACE_FIX,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'fails when @astryxdesign/cli/authoring stops exporting NamespaceDoc',
+    async () => {
+      const root = copyAuthoring();
+      const index = path.join(root, 'index.d.ts');
+      const before = fs.readFileSync(index, 'utf8');
+      const after = before.replace(
+        /^export type \{NamespaceDoc\} from .*\n/m,
+        '',
+      );
+      expect(after).not.toBe(before);
+      fs.writeFileSync(index, after);
+      expect(await checkAuthoringDocs(undefined, {root})).toMatchObject({
+        status: 'fail',
+        message: `${NAMESPACE} documents NamespaceDoc, which @astryxdesign/cli/authoring does not export`,
+        fix: SURFACE_FIX,
+      });
+    },
+    SLOW,
+  );
+
+  it.each([
+    [
+      'the graph-fields doc',
+      'doctypes/base/graph-fields.doc.mjs',
+      'doctypes/base/type.ts',
+      [
+        'AuthoredDocKind',
+        'DocAudience',
+        'DocPlacement',
+        'AuthoredDocGraphFields',
+      ],
+    ],
+    [
+      'the identity doc',
+      'identity/identity.doc.mjs',
+      'identity/type.ts',
+      [
+        'ProviderId',
+        'ArtifactId',
+        'DocId',
+        'ProviderInstance',
+        'AuthoredDocEntry',
+      ],
+    ],
+    [
+      'the semantic-block doc',
+      'doctypes/reference/reference.doc.mjs',
+      'doctypes/reference/type.ts',
+      [
+        'WorkflowStep',
+        'WorkflowDocBlock',
+        'CollectionDocBlock',
+        'ReferenceDocBlock',
+      ],
+    ],
+  ])(
+    'fails when %s is removed, which the self-doc audit alone passes',
+    async (_what, source, module, names) => {
+      const root = copyAuthoring();
+      fs.rmSync(path.join(root, source));
+      const sources = without(source);
+      expect(await auditAuthoringSelfDocs({root, sources})).toEqual({
+        sections: sources.length,
+        unreachable: [],
+        failed: [],
+        oversized: [],
+      });
+      const c = await checkAuthoringDocs(undefined, {root, sources});
+      expect(c.status).toBe('fail');
+      expect(c.fix).toBe(SURFACE_FIX);
+      expect(c.message).toMatch(
+        new RegExp(
+          `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`astryx docs authoring\`: no self-doc sits beside ${escape(module)}$`,
+        ),
+      );
+      for (const name of names) {
+        expect(c.message).toMatch(new RegExp(`(^|, )${name}(,| from)`));
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps the message and fix of a failure only the self-doc audit reports',
+    async () => {
+      const root = copyAuthoring();
+      fs.writeFileSync(
+        path.join(root, 'identity', 'broken.doc.mjs'),
+        'export const doc = {;\n',
+      );
+      const c = await checkAuthoringDocs(undefined, {
+        root,
+        sources: [...AUTHORING_SELF_DOCS, 'identity/broken.doc.mjs'],
+      });
+      expect(c.status).toBe('fail');
+      expect(c.message).toMatch(/^identity\/broken\.doc\.mjs failed to load: /);
+      expect(c.fix).toBe(
+        'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.',
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'reports a topic it cannot read rather than skipping the comparison',
+    async () => {
+      const spy = vi
+        .spyOn(DocsCatalog, 'fromBuiltins')
+        .mockImplementationOnce(() => {
+          throw new Error('no built-in docs');
+        });
+      try {
+        expect(await checkAuthoringDocs()).toMatchObject({
+          status: 'fail',
+          message:
+            '`astryx docs authoring` could not be read: no built-in docs',
+          fix: SURFACE_FIX,
+        });
+      } finally {
+        spy.mockRestore();
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'fails rather than passes when the surface exports no types at all',
+    async () => {
+      const root = copyAuthoring();
+      fs.writeFileSync(
+        path.join(root, 'index.d.ts'),
+        "export {parseDoc} from './doctypes/parse.mjs';\n",
+      );
+      const c = await checkAuthoringDocs(undefined, {root});
+      expect(c.status).toBe('fail');
+      expect(c.message).toContain(
+        '@astryxdesign/cli/authoring exports no types, so nothing was compared with `astryx docs authoring`',
+      );
+    },
+    SLOW,
+  );
+});
+
+/**
+ * Every file under `root` with its contents.
+ * @param {string} root
+ * @returns {Record<string, string>}
+ */
+function snapshot(root) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  /** @param {string} dir */
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else out[path.relative(root, full)] = fs.readFileSync(full, 'utf8');
+    }
+  };
+  walk(root);
+  return out;
+}
+
 describe('doctor docs checks', () => {
   it('runs both docs checks and they pass on the repo', async () => {
     const r = await doctor({cwd});
@@ -487,7 +812,7 @@ describe('checkDocsProgressiveDisclosure languages', () => {
       docsCatalog: DocsCatalog.fromBuiltins({deploying: path.join(dir, 'deploying.doc.mjs')}),
       docsCatalogIssues: [],
     });
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toContain('deploying [zh]: zh overlay broken');
     expect(c.message).toContain('deploying [dense] overview: 41 KB');
     expect(c.message).not.toMatch(/deploying overview:/);

package/api/gap-report/gap-report.doc.mjs

@@ -10,6 +10,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'gapReport',
+  namespace: 'cli/api',
   displayName: 'gapReport()',
   summary: 'Route a design-system gap through the fan-out handler composition.',
   description: