@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/api/discover/search/search.mjs

@@ -1,44 +1,76 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file discover.search leaf — free-text search across external packages.
+ * @file discover.search leaf — free-text search across installed packages and,
+ * when the project has discover sources, everything it could add.
  *
- * Resolution order (matching the flat command exactly):
- *   1. exact component name  -> discover.detail.doc
- *   2. single substring hit  -> discover.detail.doc
- *   3. multiple substring hits -> discover.search
- *   4. fuzzy hits (distance <= 3) -> throw ERR_NOT_FOUND with suggestions
- *   5. otherwise             -> throw ERR_NOT_FOUND
+ * A free-text query always answers with a list, so its response type depends
+ * on the form of the query and never on what the project has:
+ *   1. any matches                -> discover.search
+ *   2. fuzzy hits (distance <= 3) -> throw ERR_NOT_FOUND with suggestions
+ *   3. otherwise                  -> throw ERR_NOT_FOUND
+ * Matches are installed components, the project's other installed items,
+ * packages, and every item a source lists for a package the project could add.
+ * A caller opens one item by its package path, which ../detail answers.
  *
- * @position api/discover/search — projection over ../_adapter's resolver;
- *   delegates the single-component cases to ../detail/doc.
+ * @position api/discover/search — pure ranking over the installed component
+ *   names and ../_catalog-view's search items.
  */
 
-import {findComponent} from '../_adapter.mjs';
-import {docFromResult} from '../detail/doc/doc.mjs';
 import {levenshteinDistance} from '../../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {DISCOVER_KINDS} from '../../../authoring/discover/parse.mjs';
 
 /**
  * @typedef {import('../_package-scanner.mjs').ScannedPackage} ScannedPackage
+ * @typedef {import('../_catalog-view.mjs').SearchItem} SearchItem
  */
 
+const KIND_ORDER = ['package', ...DISCOVER_KINDS];
+
+/**
+ * How well an item matches: 0 exact name, 1 name prefix, 2 name substring,
+ * 3 title, summary, keyword, or description; null for no match.
+ * @param {SearchItem} item
+ * @param {string} lower
+ * @returns {number | null}
+ */
+function rank(item, lower) {
+  const name = item.name.toLowerCase();
+  if (name === lower) return 0;
+  if (name.startsWith(lower)) return 1;
+  if (name.includes(lower)) return 2;
+  const text = [
+    item.title,
+    item.summary,
+    item.description,
+    ...(item.keywords ?? []),
+  ]
+    .filter(Boolean)
+    .join('\n')
+    .toLowerCase();
+  return text.includes(lower) ? 3 : null;
+}
+
 /**
  * Search all packages for `query` (a free-text term that never starts with
- * `@`). Resolves to a single component's docs when unambiguous, a search
- * response when several match, or throws AstryxError (ERR_NOT_FOUND) — with
- * fuzzy suggestions when any exist.
+ * `@`). Resolves to a search response when anything matches, even a single
+ * item or an exact component name, or throws AstryxError (ERR_NOT_FOUND) —
+ * with fuzzy suggestions when any exist.
  *
- * @param {ScannedPackage[]} packages
+ * @param {ScannedPackage[]} packages installed packages
  * @param {string} query
- * @param {{lang?: string | null, zh?: boolean}} opts
- * @returns {Promise<
- *   import('../discover.type.mjs').DiscoverDetailDocResponse |
- *   import('../discover.type.mjs').DiscoverSearchResponse
- * >}
+ * @param {{
+ *   items?: SearchItem[],
+ *   type?: import('../../../authoring/discover/type').DiscoverKind,
+ *   only?: 'installed' | 'available',
+ *   limit?: number,
+ * }} opts
+ * @returns {Promise<import('../discover.type.mjs').DiscoverSearchResponse>}
  */
-export async function search(packages, query, {lang, zh}) {
+export async function search(packages, query, opts) {
+  const {items = [], type, only, limit} = opts;
   // An empty query must error, not match every component via `.includes('')`
   // (parity with the api/search leaf). The discover() dispatcher already routes
   // an empty query to list, but the leaf must be safe on its own.
@@ -51,50 +83,64 @@ export async function search(packages, query, {lang, zh}) {
   }
   const lower = query.toLowerCase();
 
-  const exact = findComponent(packages, query);
-  if (exact) return await docFromResult(exact, {lang, zh});
-
-  const substringMatches =
-    /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
-  for (const pkg of packages) {
-    for (const comp of pkg.components) {
-      if (comp.toLowerCase().includes(lower)) {
-        substringMatches.push({pkg, comp});
-      }
-    }
-  }
+  /** @type {SearchItem[]} */
+  const installedComponents = packages.flatMap(pkg =>
+    pkg.components.map(name => ({
+      package: pkg.name,
+      kind: /** @type {const} */ ('component'),
+      name,
+      installed: true,
+    })),
+  );
 
-  if (substringMatches.length === 1) {
-    const match = substringMatches[0];
-    const result = findComponent([match.pkg], match.comp);
-    if (result) return await docFromResult(result, {lang, zh});
-  }
+  const ranked = [...installedComponents, ...items]
+    .filter(item => (type == null ? true : item.kind === type))
+    .filter(item =>
+      only === 'installed'
+        ? item.installed
+        : only === 'available'
+          ? !item.installed
+          : true,
+    )
+    .map(item => ({item, score: rank(item, lower)}))
+    .filter(
+      /** @returns {m is {item: SearchItem, score: number}} */
+      m => m.score != null,
+    )
+    .sort(
+      (a, b) =>
+        a.score - b.score ||
+        Number(b.item.installed) - Number(a.item.installed) ||
+        KIND_ORDER.indexOf(a.item.kind) - KIND_ORDER.indexOf(b.item.kind) ||
+        a.item.package.localeCompare(b.item.package) ||
+        a.item.name.localeCompare(b.item.name),
+    );
 
-  if (substringMatches.length > 1) {
+  if (ranked.length > 0) {
+    const matches = ranked.map(({item}) => ({
+      package: item.package,
+      component: item.name,
+      kind: item.kind,
+      installed: item.installed,
+      ...(item.title ? {title: item.title} : {}),
+      ...(item.summary ? {summary: item.summary} : {}),
+    }));
+    const shown = limit == null ? matches : matches.slice(0, limit);
     return {
       type: 'discover.search',
       data: {
         query,
-        matches: substringMatches.map(m => ({
-          package: m.pkg.name,
-          component: m.comp,
-        })),
+        matches: shown,
+        ...(shown.length < matches.length ? {total: matches.length} : {}),
       },
     };
   }
 
-  // Fuzzy fallback
-  const allComponents =
-    /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
-  for (const pkg of packages) {
-    for (const comp of pkg.components) {
-      allComponents.push({pkg, comp});
-    }
-  }
-  const fuzzyMatches = allComponents
-    .map(item => ({
-      ...item,
-      distance: levenshteinDistance(lower, item.comp.toLowerCase()),
+  // Fuzzy fallback over installed components.
+  const fuzzyMatches = installedComponents
+    .map(entry => ({
+      ...entry,
+      distance: levenshteinDistance(lower, entry.name.toLowerCase()),
     }))
     .filter(m => m.distance <= 3)
     .sort((a, b) => a.distance - b.distance)
@@ -104,7 +150,7 @@ export async function search(packages, query, {lang, zh}) {
     throw new AstryxError(
       `"${query}" not found`,
       fuzzyMatches.map(m => ({
-        name: m.pkg.name + '/' + m.comp,
+        name: m.package + '/' + m.name,
         reason: 'similar name',
       })),
       ERROR_CODES.ERR_NOT_FOUND,

package/api/discover/search/search.test.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Colocated tests for the discover.search leaf. Exact/single matches load
- * a real `.doc.mjs`, so these drive a small temp docs directory.
+ * @file Colocated tests for the discover.search leaf, over a small temp docs
+ * directory shaped like a scanned package.
  */
 
 import {describe, it, expect, beforeAll, afterAll} from 'vitest';
@@ -47,16 +47,31 @@ afterAll(() => {
 });
 
 describe('discover.search leaf', () => {
-  it('an exact component name resolves to its docs', async () => {
+  it('lists an exact component name first, with every other match', async () => {
     const res = await search(packages, 'Alpha', {});
-    expect(res.type).toBe('discover.detail.doc');
-    expect(res.data.name).toBe('Alpha');
+    expect(res.type).toBe('discover.search');
+    expect(res.data.matches.map(m => m.component)).toEqual([
+      'Alpha',
+      'AlphaCard',
+    ]);
   });
 
-  it('a single substring match resolves to its docs', async () => {
+  it('lists a single match too, so the response type never depends on the data', async () => {
     const res = await search(packages, 'card', {});
-    expect(res.type).toBe('discover.detail.doc');
-    expect(res.data.name).toBe('AlphaCard');
+    expect(res).toEqual({
+      type: 'discover.search',
+      data: {
+        query: 'card',
+        matches: [
+          {
+            package: '@acme/widgets',
+            component: 'AlphaCard',
+            kind: 'component',
+            installed: true,
+          },
+        ],
+      },
+    });
   });
 
   it('multiple substring matches return a search response', async () => {
@@ -66,8 +81,18 @@ describe('discover.search leaf', () => {
       data: {
         query: 'alph',
         matches: [
-          {package: '@acme/widgets', component: 'Alpha'},
-          {package: '@acme/widgets', component: 'AlphaCard'},
+          {
+            package: '@acme/widgets',
+            component: 'Alpha',
+            kind: 'component',
+            installed: true,
+          },
+          {
+            package: '@acme/widgets',
+            component: 'AlphaCard',
+            kind: 'component',
+            installed: true,
+          },
         ],
       },
     });
@@ -116,3 +141,112 @@ describe('discover.search leaf — empty query (parity with api/search)', () =>
     });
   });
 });
+
+describe('discover.search leaf across every kind and source', () => {
+  /** @type {any[]} */
+  const items = [
+    {
+      package: '@acme/widgets',
+      kind: 'template',
+      name: 'pages/AlphaHome',
+      installed: true,
+    },
+    {
+      package: '@acme/charts',
+      kind: 'package',
+      name: '@acme/charts',
+      installed: false,
+      description: 'Charts for alpha dashboards',
+    },
+    {
+      package: '@acme/charts',
+      kind: 'component',
+      name: 'AlphaChart',
+      installed: false,
+    },
+    {
+      package: '@acme/charts',
+      kind: 'doc',
+      name: 'guide',
+      installed: false,
+      summary: 'How to chart',
+    },
+  ];
+
+  it('ranks every match by how closely its name matches, installed first among equals', async () => {
+    const res = await search(packages, 'alph', {items});
+    expect(res.type).toBe('discover.search');
+    expect(
+      res.data.matches.map(m => [m.kind, m.component, m.installed]),
+    ).toEqual([
+      ['component', 'Alpha', true],
+      ['component', 'AlphaCard', true],
+      ['component', 'AlphaChart', false],
+      ['template', 'pages/AlphaHome', true],
+      ['package', '@acme/charts', false],
+    ]);
+  });
+
+  it('lists an exact installed component name with the matches from every source', async () => {
+    const res = await search(packages, 'Alpha', {items});
+    expect(res.type).toBe('discover.search');
+    expect(res.data.matches[0]).toEqual({
+      package: '@acme/widgets',
+      component: 'Alpha',
+      kind: 'component',
+      installed: true,
+    });
+    expect(res.data.matches.map(m => m.component)).toContain('AlphaChart');
+  });
+
+  it('lists a single partial component match when other items match too', async () => {
+    const res = await search(packages, 'card', {
+      items: [
+        ...items,
+        {
+          package: '@acme/charts',
+          kind: 'template',
+          name: 'pages/CardGrid',
+          installed: false,
+        },
+      ],
+    });
+    expect(res.type).toBe('discover.search');
+    expect(res.data.matches.map(m => m.component)).toEqual([
+      'AlphaCard',
+      'pages/CardGrid',
+    ]);
+  });
+
+  it('lists one installed component when nothing else matches', async () => {
+    const res = await search(packages, 'card', {items});
+    expect(res.type).toBe('discover.search');
+    expect(res.data.matches.map(m => m.component)).toEqual(['AlphaCard']);
+  });
+
+  it('keeps one kind with type, and one side with only', async () => {
+    const templates = await search(packages, 'alph', {items, type: 'template'});
+    expect(templates.data.matches.map(m => m.component)).toEqual([
+      'pages/AlphaHome',
+    ]);
+    const available = await search(packages, 'alph', {
+      items,
+      only: 'available',
+    });
+    expect(available.data.matches.map(m => m.component)).toEqual([
+      'AlphaChart',
+      '@acme/charts',
+    ]);
+  });
+
+  it('caps the list at limit and reports the total', async () => {
+    const res = await search(packages, 'alph', {items, limit: 2});
+    expect(res.data.matches).toHaveLength(2);
+    expect(res.data.total).toBe(5);
+  });
+
+  it('matches titles, summaries, keywords, and descriptions too', async () => {
+    const res = await search(packages, 'how to chart', {items});
+    expect(res.data.matches.map(m => m.component)).toEqual(['guide']);
+  });
+});

package/api/docs/_adapter.d.mts

@@ -77,10 +77,12 @@ export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner,
 /**
  * What \`astryx doctor integration docs\` checks in one integration's docs: the
  * docs tree they build beside the CLI's (namespaces, placements, routes) and
- * every link in them (spec:AST-046, spec:AST-047).
+ * every link in them (spec:AST-046, spec:AST-047). A tree problem hides a doc,
+ * so it is an error; a link that names no doc prints as written, so it is a
+ * warning.
  * @param {{name: string}} integration
  * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
- * @returns {Promise<string[]>}
+ * @returns {Promise<Array<{severity: 'error' | 'warning', message: string}>>}
  */
 export function packageDocsProblems(integration: {
     name: string;
@@ -88,7 +90,10 @@ export function packageDocsProblems(integration: {
     records: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicRecord[];
     namespaces: import("../../foundation/doc-compiler/tree.mjs").TreeNamespaceInput[];
     guides: import("../../foundation/doc-compiler/tree.mjs").TreeDocInput[];
-}): Promise<string[]>;
+}): Promise<Array<{
+    severity: "error" | "warning";
+    message: string;
+}>>;
 /**
  * How a token reference finds its target: the topic it names in `catalog`,
  * lowered for the same language.

package/api/docs/_adapter.mjs

@@ -667,10 +667,12 @@ export async function docsLinkProblems(
 /**
  * What \`astryx doctor integration docs\` checks in one integration's docs: the
  * docs tree they build beside the CLI's (namespaces, placements, routes) and
- * every link in them (spec:AST-046, spec:AST-047).
+ * every link in them (spec:AST-046, spec:AST-047). A tree problem hides a doc,
+ * so it is an error; a link that names no doc prints as written, so it is a
+ * warning.
  * @param {{name: string}} integration
  * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
- * @returns {Promise<string[]>}
+ * @returns {Promise<Array<{severity: 'error' | 'warning', message: string}>>}
  */
 export async function packageDocsProblems(integration, discovered) {
   const catalog = DocsCatalog.fromBuiltins();
@@ -680,12 +682,18 @@ export async function packageDocsProblems(integration, discovered) {
     guides: discovered.guides.map(input => ({...input, rank: 1})),
   });
   const tree = await projectTree(catalog);
+  /** @type {Array<{severity: 'error' | 'warning', message: string}>} */
   const problems = tree.diagnostics
     .filter(d => d.severity === 'error' && d.provider === integration.name)
-    .map(d => `${d.source ?? integration.name}: ${d.message}`);
-  problems.push(
-    ...(await docsLinkProblems(catalog, tree, {owner: integration.name})),
-  );
+    .map(d => ({
+      severity: /** @type {const} */ ('error'),
+      message: `${d.source ?? integration.name}: ${d.message}`,
+    }));
+  for (const message of await docsLinkProblems(catalog, tree, {
+    owner: integration.name,
+  })) {
+    problems.push({severity: 'warning', message});
+  }
   return problems;
 }
 

package/api/docs/docOverlays.test.mjs

@@ -76,6 +76,32 @@ describe('reference doc overlays (#2182)', () => {
       ).toEqual([]);
     });
 
+    it(`${topic} --${variant}: every content override lands on a block of its own type`, async () => {
+      // Blocks are matched by index and type, and a mismatch is dropped with
+      // no warning: a prose override aimed at a code block leaves the base
+      // text in place, so the reader gets a translated title over an English
+      // body. Pad with null to reach the block you mean.
+      const base = await load(basePath);
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+      const byTitle = new Map(base.docs.sections.map(s => [s.title, s]));
+      const dropped = [];
+      for (const entry of overlay.sections || []) {
+        const section = byTitle.get(entry.section);
+        if (!section) continue;
+        (entry.content || []).forEach((block, i) => {
+          if (block == null) return;
+          const target = section.content[i];
+          if (target?.type !== block.type) {
+            dropped.push(
+              `${entry.section} block ${i}: ${block.type} over ${target?.type ?? 'nothing'}`,
+            );
+          }
+        });
+      }
+      expect(dropped, `${topic}.doc.${variant}.mjs overrides that never apply`).toEqual([]);
+    });
+
     it(`${topic} --${variant}: no base section is overridden twice`, async () => {
       const overlayMod = await load(overlayPath);
       const overlay = overlayMod.docsDense || overlayMod.docsZh;
@@ -127,7 +153,7 @@ describe('the reported defect: docs tokens --dense (#2182)', () => {
     const zh = await docs('theme', null, {zh: true});
     const titles = zh.data.sections.map(s => s.title);
     // Every section the overlay translates must appear once, in Chinese only.
-    expect(titles).not.toContain('Light/Dark Mode');
+    expect(titles).not.toContain('Dark mode');
     expect(titles).toContain('亮/暗模式');
   });
 });

package/api/docs/docs.doc.mjs

@@ -27,7 +27,7 @@ export const doc = {
     'A route opens a node of the docs tree instead: a namespace such as ' +
     "`cli/api` returns its children one level down, a typed doc such as " +
     "`cli/api/functions/search` returns its content, and a guide the tree " +
-    'places (`cli/integrations`) reads like any topic. ' +
+    'places (`cli/integrations/quick-start`) reads like any topic. ' +
     'Every read but the list carries `links`, the commands that move from it: ' +
     '`up` to the level it sits in, `previous` and `next` to its neighbors, and, ' +
     'for a typed doc, `related` to the docs it names (its command or function, ' +
@@ -137,7 +137,7 @@ export const doc = {
     {label: 'One API function', code: "await docs('cli/api/functions/search');"},
     {
       label: 'A whole guide from the docs tree',
-      code: "await docs('cli/integrations');",
+      code: "await docs('cli/integrations/quick-start');",
     },
     {label: 'One section by key', code: "await docs('tokens', 'spacing');"},
   ],

package/api/docs/docs.test.mjs

@@ -14,6 +14,20 @@ import {AstryxError} from '../error.mjs';
 
 const SLOW = 30_000;
 
+/**
+ * The first guide a namespace places, read from the tree rather than named,
+ * so a restructure of the guides does not break the reads under test.
+ * @param {any} node the data of a docs.node read
+ * @returns {string}
+ */
+function placedGuide(node) {
+  const guide = node.slots
+    .flatMap((/** @type {any} */ slot) => slot.children)
+    .find((/** @type {any} */ child) => child.kind === 'generic');
+  if (guide == null) throw new Error(`${node.route} places no guide`);
+  return guide.route;
+}
+
 describe('docs() dispatcher routing', () => {
   it('no topic -> docs.list', async () => {
     const r = await docs();
@@ -37,6 +51,15 @@ describe('docs() dispatcher routing', () => {
     expect(r.type).toBe('docs.index');
   }, SLOW);
 
+  it('reads a shortened section by its old key, which its title still derives', async () => {
+    const r = await docs(
+      'styling',
+      'stylex-build-setup-required-for-swizzled-components',
+    );
+    expect(r.type).toBe('docs.detail.section');
+    expect(r.data).toMatchObject({id: 'stylex-setup'});
+  }, SLOW);
+
   it('topic + section -> docs.detail.section', async () => {
     const {data} = await docs();
     let routed = null;
@@ -126,11 +149,15 @@ describe('docs() dispatcher routing', () => {
   }, SLOW);
 
   it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
-    expect((await docs('cli/integrations')).type).toBe('docs.detail');
-    const index = await docs('cli/integrations', undefined, {index: true});
-    expect(index).toMatchObject({type: 'docs.index', data: {name: 'cli/integrations'}});
+    // cli/integrations is a namespace of short guides; each guide reads like a topic.
+    const integrations = await docs('cli/integrations');
+    expect(integrations.type).toBe('docs.node');
+    const guide = placedGuide(integrations.data);
+    expect((await docs(guide)).type).toBe('docs.detail');
+    const index = await docs(guide, undefined, {index: true});
+    expect(index).toMatchObject({type: 'docs.index', data: {name: guide}});
     expect(index.data.sections.length).toBeGreaterThan(1);
-    expect((await docs('cli/integrations', 'components')).type).toBe(
+    expect((await docs(guide, index.data.sections[0].id)).type).toBe(
       'docs.detail.section',
     );
   }, SLOW);
@@ -142,22 +169,31 @@ describe('docs() dispatcher routing', () => {
     expect(leaf.links.up).toBe('astryx docs cli/api/functions');
     expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
     expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
-    const index = await docs('cli/integrations', undefined, {index: true});
+    const integrations = (await docs('cli/integrations')).data;
+    const guide = placedGuide(integrations);
+    const siblings = integrations.slots
+      .find(slot => slot.children.some(child => child.route === guide))
+      .children.map(child => child.route);
+    const at = siblings.indexOf(guide);
+    const index = await docs(guide, undefined, {index: true});
     // A guide moves across its namespace's slot, as any tree node does.
     expect(index.data.links).toEqual({
-      up: 'astryx docs cli',
-      next: 'astryx docs cli/writing-docs',
+      up: 'astryx docs cli/integrations',
+      ...(at > 0 ? {previous: `astryx docs ${siblings[at - 1]}`} : {}),
+      ...(at < siblings.length - 1
+        ? {next: `astryx docs ${siblings[at + 1]}`}
+        : {}),
     });
-    const first = (await docs('cli/integrations', index.data.sections[0].id)).data;
+    const first = (await docs(guide, index.data.sections[0].id)).data;
     expect(first.links).toEqual({
-      up: 'astryx docs cli/integrations --index',
-      next: `astryx docs cli/integrations ${index.data.sections[1].id}`,
+      up: `astryx docs ${guide} --index`,
+      next: `astryx docs ${guide} ${index.data.sections[1].id}`,
     });
     const last = index.data.sections.at(-1).id;
-    const end = (await docs('cli/integrations', last)).data;
+    const end = (await docs(guide, last)).data;
     expect(end.links.next).toBeUndefined();
     expect(end.links.previous).toBe(
-      `astryx docs cli/integrations ${index.data.sections.at(-2).id}`,
+      `astryx docs ${guide} ${index.data.sections.at(-2).id}`,
     );
     // A flat topic's home is the Unorganized level, and it moves across it.
     const flat = (await docs('principles')).data.links;
@@ -208,12 +244,12 @@ describe('docs() dispatcher routing', () => {
     const err = await docs('cli', 'commands').catch(e => e);
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.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.
+    const cli = (await docs('cli')).data;
+    expect(err.suggestions.map(s => s.name)).toEqual(
+      cli.slots.flatMap(slot => slot.children.map(child => child.route)),
+    );
+    expect(err.suggestions.map(s => s.name)).toContain('cli/commands');
   }, SLOW);
 
   it('an unknown route suggests the children of the deepest namespace it reaches', async () => {

package/api/docs/integration-tree.test.mjs

@@ -477,6 +477,23 @@ describe('integration docs in the docs tree', () => {
     );
   }, SLOW);
 
+  it('fails doctor integration docs on a placement that hides a guide, and only warns on a link', async () => {
+    scaffold({
+      ...kit(),
+      'lost.doc.mjs': guide('lost', {
+        placement: {parent: 'namespace:nope', slot: 'guides'},
+      }),
+    });
+    const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({
+        code: 'invalid_doc_graph',
+        severity: 'error',
+        message: expect.stringContaining('namespace:nope'),
+      }),
+    );
+  }, SLOW);
+
   it("resolves an extension's links against the extension's provider, not the base topic's", async () => {
     scaffold({
       ...kit(),