@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/clients/cli/commands/discover.sources.test.mjs

@@ -0,0 +1,267 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover` with a discover source: the list, a package page, a
+ * search, and the refused option pair, driven through the real CLI against a
+ * hermetic project whose astryx.config sets `discover`. Saved copies go to a
+ * temp cache directory, never the project.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const CONFIG = `
+const packages = [
+  {
+    package: '@test/kit',
+    integration: 'test-kit',
+    aliases: [],
+    latest: '3.2.0',
+    versions: [
+      {version: '3.2.0', publishedAt: '2026-09-29T00:00:00.000Z', prerelease: false, status: 'ok'},
+      {version: '3.1.4', publishedAt: '2026-09-01T00:00:00.000Z', prerelease: false, status: 'ok'},
+    ],
+    contributions: [{kind: 'component', name: 'Dial'}],
+  },
+  {
+    package: '@test/charts',
+    integration: 'test-charts',
+    aliases: [],
+    latest: '2.0.0',
+    versions: [
+      {version: '2.1.0-beta.1', publishedAt: '2026-09-25T00:00:00.000Z', prerelease: true, status: 'ok'},
+      {version: '2.0.0', publishedAt: '2026-09-20T00:00:00.000Z', prerelease: false, status: 'ok'},
+    ],
+    contributions: [
+      {kind: 'component', name: 'Chart'},
+      {kind: 'template', name: 'pages/Report'},
+    ],
+  },
+  {
+    package: '@test/boards',
+    integration: 'test-boards',
+    aliases: [],
+    latest: '1.0.0',
+    versions: [
+      {version: '1.0.0', publishedAt: '2026-09-10T00:00:00.000Z', prerelease: false, status: 'ok'},
+    ],
+    contributions: [{kind: 'template', name: 'pages/DialBoard'}],
+  },
+];
+
+export default {
+  integrations: ['@test/kit'],
+  async discover({package: name}) {
+    return {
+      schemaVersion: 1,
+      source: {name: 'Test catalog', generatedAt: '2026-09-30T00:00:00.000Z', complete: true},
+      packages: packages.filter(p => name == null || p.package === name),
+    };
+  },
+};
+`;
+
+let tmpDir;
+let project;
+/** @type {Record<string, string | undefined>} */
+let savedEnv;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-sources-'));
+  project = path.join(tmpDir, 'project');
+  const pkgDir = path.join(project, 'node_modules', '@test', 'kit');
+  fs.mkdirSync(path.join(pkgDir, 'components'), {recursive: true});
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({
+      name: 'proj',
+      version: '1.0.0',
+      dependencies: {'@test/kit': '3.1.4'},
+    }),
+  );
+  fs.writeFileSync(path.join(project, 'astryx.config.mjs'), CONFIG);
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@test/kit', version: '3.1.4'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default {components: './components'};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'components', 'Dial.doc.mjs'),
+    `export const docs = {name: 'Dial', usage: {description: 'A dial.'}};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'components', 'Dial.tsx'),
+    `export function Dial() { return null; }\n`,
+  );
+  // The saved copy lives in the per-user cache; point it at the temp dir.
+  savedEnv = {
+    HOME: process.env.HOME,
+    XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+    LOCALAPPDATA: process.env.LOCALAPPDATA,
+  };
+  process.env.HOME = path.join(tmpDir, 'home');
+  process.env.XDG_CACHE_HOME = path.join(tmpDir, 'cache');
+  process.env.LOCALAPPDATA = path.join(tmpDir, 'localappdata');
+});
+
+afterEach(() => {
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** The per-user cache directory this platform uses under the redirected env. */
+function userCacheDir() {
+  if (process.platform === 'win32') {
+    return path.join(tmpDir, 'localappdata', 'astryx', 'Cache');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(tmpDir, 'home', 'Library', 'Caches', 'astryx');
+  }
+  return path.join(tmpDir, 'cache', 'astryx');
+}
+
+describe('astryx discover with a discover source', () => {
+  it('lists what the project has and what it could add, in --json', async () => {
+    const {status, stdout} = await runCli(['discover', '--json'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    const {data, meta} = JSON.parse(stdout);
+    expect(data).toEqual([
+      expect.objectContaining({
+        name: '@test/kit',
+        components: ['Dial'],
+        version: '3.1.4',
+        latest: '3.2.0',
+      }),
+    ]);
+    expect(meta.available).toEqual([
+      {
+        name: '@test/charts',
+        components: ['Chart'],
+        version: '2.0.0',
+        templates: ['pages/Report'],
+        source: 'Test catalog',
+      },
+      {
+        name: '@test/boards',
+        components: [],
+        version: '1.0.0',
+        templates: ['pages/DialBoard'],
+        source: 'Test catalog',
+      },
+    ]);
+    expect(meta.sources).toEqual([
+      expect.objectContaining({
+        name: 'Test catalog',
+        from: 'astryx.config',
+        status: 'fresh',
+      }),
+    ]);
+  });
+
+  it('prints both sides as records', async () => {
+    const {status, stdout} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^Installed$/m);
+    expect(stdout).toMatch(/^Available$/m);
+    expect(stdout).toMatch(/^name:\s+@test\/charts$/m);
+    expect(stdout).toMatch(/^latest:\s+3\.2\.0$/m);
+  });
+
+  it('shows a package it does not have with its releases and the command that adds it, and never runs it', async () => {
+    const {status, stdout} = await runCli(['discover', '@test/charts'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^installed:\s+false$/m);
+    expect(stdout).toContain('- 2.0.0  2026-09-20  latest');
+    expect(stdout).not.toContain('2.1.0-beta.1  ');
+    expect(stdout).toContain('1 prerelease is not listed.');
+    // The verb follows the detected package manager.
+    expect(stdout).toMatch(
+      /^(npm install|pnpm add|yarn add|bun add) @test\/charts$/m,
+    );
+    expect(
+      fs.existsSync(path.join(project, 'node_modules', '@test', 'charts')),
+    ).toBe(false);
+  });
+
+  it('says which item is missing from a package only a source lists', async () => {
+    const {status, stdout} = await runCli(
+      ['discover', '@test/charts/Nope', '--json'],
+      {cwd: project},
+    );
+
+    expect(status).toBe(1);
+    const {code, error} = JSON.parse(stdout);
+    expect(code).toBe('ERR_UNKNOWN_COMPONENT');
+    expect(error).toBe('"Nope" not found in @test/charts');
+  });
+
+  it('searches every kind in every source', async () => {
+    const {status, stdout} = await runCli(['discover', 'report', '--json'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).data.matches).toEqual([
+      {
+        package: '@test/charts',
+        component: 'pages/Report',
+        kind: 'template',
+        installed: false,
+      },
+    ]);
+  });
+
+  it('refuses --installed with --available', async () => {
+    const {status, stdout} = await runCli(
+      ['discover', '--installed', '--available', '--json'],
+      {cwd: project},
+    );
+
+    expect(status).toBe(1);
+    expect(JSON.parse(stdout).code).toBe('ERR_INVALID_OPTION');
+  });
+
+  it('lists every match for a free-text query, even an exact component name, and opens one by its package path', async () => {
+    const exact = await runCli(['discover', 'Dial', '--json'], {cwd: project});
+    const {type, data} = JSON.parse(exact.stdout);
+    expect(type).toBe('discover.search');
+    expect(data.matches.map(m => [m.component, m.installed])).toEqual([
+      ['Dial', true],
+      ['pages/DialBoard', false],
+    ]);
+
+    const opened = await runCli(['discover', '@test/kit/Dial', '--json'], {
+      cwd: project,
+    });
+    expect(JSON.parse(opened.stdout).type).toBe('discover.detail.doc');
+  });
+
+  it('saves the answer in the user cache and writes nothing into the project', async () => {
+    const before = fs.readdirSync(project).sort();
+    await runCli(['discover', '--json'], {cwd: project});
+
+    expect(fs.readdirSync(project).sort()).toEqual(before);
+    expect(fs.existsSync(path.join(project, 'node_modules', '.cache'))).toBe(
+      false,
+    );
+    expect(fs.readdirSync(path.join(userCacheDir(), 'discover'))).toHaveLength(
+      1,
+    );
+  });
+});

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

@@ -47,7 +47,7 @@ export const doc = {
     {label: 'One section', cli: 'astryx docs theme quick-start'},
     {label: 'The CLI docs tree', cli: 'astryx docs cli'},
     {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
-    {label: 'A whole guide', cli: 'astryx docs cli/integrations --full'},
+    {label: 'A whole guide', cli: 'astryx docs cli/integrations/quick-start --full'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

package/clients/cli/commands/docs.mjs

@@ -7,7 +7,8 @@
  * open one section by its key, and `--full` prints the whole topic. `--json`
  * keeps the docs() contract: a topic returns its whole doc, and `--index` its
  * sections.
- * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
+ * Supports --detail (full|compact|brief) and --lang (en|zh|dense). A code
+ * block's label prints above its fence, and table cells escape their pipes.
  *
  * Usage:
  *   astryx docs                          List available topics
@@ -42,21 +43,35 @@ import {doc as docsFn} from '../../../api/docs/docs.doc.mjs';
 
 // ─── Formatting ──────────────────────────────────────────────────────────────
 
+/**
+ * A table cell with its pipes escaped. Columns are separated by ` | `, and a
+ * union type such as `'light' | 'dark'` is spelled with the same character,
+ * so an unescaped cell reads as extra columns. `astryx component` escapes its
+ * prop tables the same way.
+ * @param {string | undefined} cell
+ * @returns {string}
+ */
+function tableCell(cell) {
+  return (cell || '').replaceAll('|', '\\|');
+}
+
 /**
  * @param {string[]} headers
  * @param {string[][]} rows
  * @returns {string}
  */
 function formatTable(headers, rows) {
-  const widths = headers.map((h, i) =>
-    Math.max(h.length, ...rows.map(r => (r[i] || '').length)),
+  const head = headers.map(tableCell);
+  const cells = rows.map(r => r.map(tableCell));
+  const widths = head.map((h, i) =>
+    Math.max(h.length, ...cells.map(r => (r[i] || '').length)),
   );
   const sep = widths.map(w => '-'.repeat(w)).join(' | ');
-  const head = headers.map((h, i) => h.padEnd(widths[i])).join(' | ');
-  const body = rows
-    .map(r => r.map((c, i) => (c || '').padEnd(widths[i])).join(' | '))
+  const top = head.map((h, i) => h.padEnd(widths[i])).join(' | ');
+  const body = cells
+    .map(r => r.map((c, i) => c.padEnd(widths[i])).join(' | '))
     .join('\n');
-  return `${head}\n${sep}\n${body}`;
+  return `${top}\n${sep}\n${body}`;
 }
 
 /**
@@ -65,15 +80,19 @@ function formatTable(headers, rows) {
  * @returns {string}
  */
 function formatTableCompact(headers, rows) {
-  return rows.map(r => r.join(' = ')).join('\n');
+  // An empty cell, such as a Default with none, adds nothing to the line.
+  return rows
+    .map(r => r.filter(cell => String(cell ?? '').trim() !== '').join(' = '))
+    .join('\n');
 }
 
 /**
+ * One content block as text. Exported for its tests.
  * @param {import('@astryxdesign/cli/authoring').ReferenceContentBlock} block
  * @param {'full' | 'compact' | 'brief'} detail
  * @returns {string | null}
  */
-function formatBlock(block, detail) {
+export function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
       return block.text;
@@ -84,13 +103,20 @@ function formatBlock(block, detail) {
     case 'code':
       if (detail === 'compact' || detail === 'brief') return null;
       {
-        const label = block.label ? `// ${block.label}\n` : '';
-        return `\`\`\`${block.lang}\n${label}${block.code}\n\`\`\``;
+        // The label names the block, so it prints above the fence, not
+        // inside it: `// label` is not a comment in bash, CSS, JSON, or
+        // HTML, and a reader who copies the block would copy it too.
+        const label = block.label
+          ? `${block.label.replace(/:\s*$/, '')}:\n`
+          : '';
+        return `${label}\`\`\`${block.lang}\n${block.code}\n\`\`\``;
       }
 
     case 'table':
       if (detail === 'brief') {
-        return block.rows.map(r => r.slice(0, 2).join('=')).join(' | ');
+        return block.rows
+          .map(r => r.slice(0, 2).map(tableCell).join('='))
+          .join(' | ');
       }
       if (detail === 'compact') {
         return formatTableCompact(block.headers, block.rows);
@@ -202,16 +228,23 @@ function emitIndex(index, run) {
 }
 
 /**
- * One child row of a namespace: its route name, then the doc's own title when
- * it is not the route name (`assertResponse()`, `search()`), then its summary.
+ * One child row of a namespace. Namespace and guide route names are already
+ * readable, so repeating their titles adds noise (`start-a-template  Start a
+ * template`). Typed docs keep a distinct title when it carries the real symbol
+ * name (`assert-response  assertResponse()`).
  * @param {import('../../../api/docs/docs.type.mjs').DocsNodeChild} child
  * @returns {{name: string, summary: string}}
  */
 function childRow(child) {
+  const titleAddsIdentity =
+    child.kind !== 'namespace' &&
+    child.kind !== 'generic' &&
+    child.title !== child.name;
   return {
     name: child.name,
-    summary:
-      child.title === child.name ? child.summary : `${child.title}: ${child.summary}`,
+    summary: titleAddsIdentity
+      ? `${child.title}: ${child.summary}`
+      : child.summary,
   };
 }
 
@@ -227,6 +260,17 @@ function emitNode(node, detail, run) {
   if (node.kind === 'namespace') {
     emit(
       section(node.title, wrapText(node.summary)),
+      // A namespace may author intro `blocks`; they render above its children.
+      ...(node.content?.length
+        ? [
+            text(
+              node.content
+                .map(b => formatBlock(b, detail))
+                .filter(Boolean)
+                .join('\n\n'),
+            ),
+          ]
+        : []),
       ...node.slots.flatMap(slot => [
         // A namespace with one slot titled like itself needs no second heading.
         ...(node.slots.length === 1 && slot.title === node.title
@@ -235,7 +279,6 @@ function emitNode(node, detail, run) {
         records(slot.children.map(childRow), {
           fields: ['name', 'summary'],
           layout: 'inline',
-          overflow: 'truncate',
         }),
       ]),
       text(

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

@@ -5,7 +5,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {Command} from 'commander';
-import {registerDocs} from './docs.mjs';
+import {formatBlock, registerDocs} from './docs.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 import {displayWidth} from '../formatters/index.mjs';
 
@@ -119,7 +119,7 @@ describe('progressive reads', () => {
   it("prints a topic's section index with the keys to read by", async () => {
     const {status, stdout} = await runCli(['docs', 'theme', '--index']);
     expect(status).toBe(0);
-    expect(stdout).toMatch(/^quick-start +Quick Start/m);
+    expect(stdout).toMatch(/^quick-start +Wrap your app in a theme/m);
     expect(stdout).toContain('docs theme <section>');
     expect(stdout).toMatch(/Read everything: +\S.* docs theme --full$/m);
     expect(widest(stdout)).toBeLessThanOrEqual(120);
@@ -128,7 +128,7 @@ describe('progressive reads', () => {
   it('prints one section by its key', async () => {
     const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);
     expect(status).toBe(0);
-    expect(stdout).toMatch(/^## Quick Start/m);
+    expect(stdout).toMatch(/^## Wrap your app in a theme/m);
   }, SLOW);
 
   it("lists a topic's sections by default; --full prints the whole topic", async () => {
@@ -136,7 +136,7 @@ describe('progressive reads', () => {
     expect((await runCli(['docs', 'theme'])).stdout).toBe(index.stdout);
     const full = await runCli(['docs', 'theme', '--full']);
     expect(full.status).toBe(0);
-    expect(full.stdout).toMatch(/^## Quick Start/m);
+    expect(full.stdout).toMatch(/^## Wrap your app in a theme/m);
     expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);
     expect((await runCli(['--detail', 'full', 'docs', 'theme', '--full'])).stdout).toBe(
       full.stdout,
@@ -157,6 +157,52 @@ describe('progressive reads', () => {
   }, SLOW);
 });
 
+describe('blocks as text', () => {
+  const SLOW = 60_000;
+
+  it('prints a code label above the fence, never inside it', () => {
+    for (const lang of ['bash', 'css', 'json', 'html', 'text', 'tsx']) {
+      expect(
+        formatBlock({type: 'code', lang, label: 'Terminal', code: 'x'}, 'full'),
+      ).toBe(`Terminal:\n\`\`\`${lang}\nx\n\`\`\``);
+    }
+    expect(formatBlock({type: 'code', lang: 'bash', code: 'x'}, 'full')).toBe(
+      '```bash\nx\n```',
+    );
+    // A label that already ends in a colon does not get a second one.
+    expect(
+      formatBlock({type: 'code', lang: 'css', label: 'globals.css:', code: 'x'}, 'full'),
+    ).toBe('globals.css:\n```css\nx\n```');
+  });
+
+  it('escapes pipes in table cells, so a union type stays one column', () => {
+    const table = {
+      type: /** @type {const} */ ('table'),
+      headers: ['Prop', 'Type', 'Default'],
+      rows: [
+        ['mode', "'system' | 'light' | 'dark'", "'system'"],
+        ['theme', 'DefinedTheme', '-'],
+      ],
+    };
+    const lines = /** @type {string} */ (formatBlock(table, 'full')).split('\n');
+    expect(lines).toHaveLength(4);
+    // Every line has exactly two column separators, all at the same place.
+    for (const line of lines) expect(line.split(' | ')).toHaveLength(3);
+    expect(new Set(lines.map(line => line.indexOf(' | '))).size).toBe(1);
+    expect(lines[2]).toContain("'system' \\| 'light' \\| 'dark'");
+    expect(formatBlock(table, 'brief')).toBe(
+      "mode='system' \\| 'light' \\| 'dark' | theme=DefinedTheme",
+    );
+  });
+
+  it('prints the labels of a real section above their fences', async () => {
+    const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);
+    expect(status).toBe(0);
+    expect(stdout).toContain('Install a theme package:\n```bash\nnpm install');
+    expect(stdout).not.toContain('// Install a theme package');
+  }, SLOW);
+});
+
 describe('the docs tree, one level at a time', () => {
   const SLOW = 60_000;
   /** @param {string} out */
@@ -179,12 +225,24 @@ describe('the docs tree, one level at a time', () => {
     expect(stdout).toMatch(/^search +search\(\): Unified ranked search/m);
   }, SLOW);
 
+  it('wraps namespace summaries without discarding searchable words', async () => {
+    const {status, stdout} = await runCli([
+      'docs',
+      'cli/integrations/building-blocks/templates',
+    ]);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^start-a-template +Help others build apps faster/m);
+    expect(stdout).not.toMatch(/^start-a-template +Start a template:/m);
+    expect(stdout).toMatch(/full page or page\s+section\./);
+    expect(widest(stdout)).toBeLessThanOrEqual(120);
+  }, SLOW);
+
   it('prints a namespace: each slot, its children, and how to go down and up', async () => {
     const {status, stdout} = await runCli(['docs', 'cli/api']);
     expect(status).toBe(0);
     expect(stdout).toMatch(/^API$/m);
     expect(stdout).toMatch(/^Reference$/m);
-    expect(stdout).toMatch(/^functions +Functions: Every function/m);
+    expect(stdout).toMatch(/^functions +Every function/m);
     expect(stdout).toMatch(/^schemas +/m);
     expect(stdout).toMatch(/^enums +/m);
     // One level only: no function is listed on the api page.
@@ -216,25 +274,57 @@ describe('the docs tree, one level at a time', () => {
     expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');
   }, SLOW);
 
-  it('reads the integration guide by its route, and not by its old name', async () => {
-    const guide = await runCli(['docs', 'cli/integrations', '--index']);
+  it('reads the integration guides by their routes, and not by the old name', async () => {
+    // cli/integrations is a namespace: one level, its guides by slot.
+    const level = await runCli(['docs', 'cli/integrations']);
+    expect(level.status).toBe(0);
+    expect(level.stdout).toMatch(
+      /^quick-start +Create a new integration package/m,
+    );
+    expect(level.stdout).toMatch(/^building-blocks +/m);
+    const guide = await runCli([
+      'docs',
+      'cli/integrations/building-blocks/codemods',
+      '--index',
+    ]);
     expect(guide.status).toBe(0);
-    expect(guide.stdout).toMatch(/Read one section: .*docs cli\/integrations <section>/);
+    expect(guide.stdout).toMatch(
+      /Read one section: .*docs cli\/integrations\/building-blocks\/codemods <section>/,
+    );
     // A bare read is one level too: the sections, and how to read it all.
-    const bare = await runCli(['docs', 'cli/integrations']);
+    const bare = await runCli([
+      'docs',
+      'cli/integrations/building-blocks/codemods',
+    ]);
     expect(bare.status).toBe(0);
     expect(bare.stdout).toBe(guide.stdout);
-    expect(bare.stdout).toMatch(/Read everything: +.*docs cli\/integrations --full$/m);
-    const one = await runCli(['docs', 'cli/integrations', 'codemods']);
+    expect(bare.stdout).toMatch(
+      /Read everything: +.*docs cli\/integrations\/building-blocks\/codemods --full$/m,
+    );
+    const one = await runCli([
+      'docs',
+      'cli/integrations/building-blocks/codemods',
+      'which-codemods-run',
+    ]);
     expect(one.status).toBe(0);
-    expect(one.stdout).toMatch(/^## Codemods$/m);
-    expect(one.stdout).toMatch(/^Up: .*docs cli\/integrations --index$/m);
-    expect(one.stdout).toMatch(/^Previous: .*docs cli\/integrations agent-docs$/m);
-    expect(one.stdout).toMatch(/^Next: .*docs cli\/integrations recording-runs$/m);
-    const full = await runCli(['docs', 'cli/integrations', '--full']);
+    expect(one.stdout).toMatch(/^## Choose when a codemod runs$/m);
+    expect(one.stdout).toMatch(
+      /^Up: .*docs cli\/integrations\/building-blocks\/codemods --index$/m,
+    );
+    expect(one.stdout).toMatch(
+      /^Previous: .*docs cli\/integrations\/building-blocks\/codemods write-the-transform$/m,
+    );
+    expect(one.stdout).toMatch(
+      /^Next: .*docs cli\/integrations\/building-blocks\/codemods run-codemods-in-an-app$/m,
+    );
+    const full = await runCli([
+      'docs',
+      'cli/integrations/building-blocks/codemods',
+      '--full',
+    ]);
     expect(full.status).toBe(0);
-    expect(full.stdout).toMatch(/^## Overview$/m);
-    expect(full.stdout.length).toBeGreaterThan(bare.stdout.length * 4);
+    expect(full.stdout).toMatch(/^## Add a codemod$/m);
+    expect(full.stdout.length).toBeGreaterThan(bare.stdout.length * 2);
     const old = await runCli(['docs', 'cli-integrations']);
     expect(old.status).toBe(1);
     expect(old.stderr).toContain('Unknown topic "cli-integrations"');
@@ -251,12 +341,11 @@ describe('the docs tree, one level at a time', () => {
     expect(section.status).toBe(1);
     const error = JSON.parse(section.stdout);
     expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
-    expect(error.suggestions.map(s => s.name)).toEqual([
-      'cli/integrations',
-      'cli/writing-docs',
-      'cli/commands',
-      'cli/api',
-    ]);
+    // It names the namespace's children, in the order its slots list them.
+    expect(error.suggestions.map(s => s.name)).toEqual(
+      node.data.slots.flatMap(slot => slot.children.map(child => child.route)),
+    );
+    expect(error.suggestions.map(s => s.name)).toContain('cli/commands');
   }, SLOW);
 });
 

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -10,9 +10,10 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
   description:
-    'Reports intentional Core topic replacements and extensions as information. ' +
+    'Checks the docs tree the package adds, every link in its docs, and overlaps with Core topics. ' +
+    'Intentional replacements and extensions are information. ' +
     'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
-    'and fails until the author declares the relationship or renames it.',
+    'and fails until the author declares the relationship or renames it. See {@link generic:check-your-docs}.',
   fn: 'integrationDocConflicts',
   args: [
     {