@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/doc-compiler/tree.mjs

@@ -0,0 +1,876 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The docs tree: one home for every doc that a namespace places or
+ *   adopts (spec:AST-046).
+ *
+ * @input Namespace docs, guides that name a parent with `placement`, and typed
+ *   docs that belong to a discovery group (a CLI typed doc's `namespace`).
+ * @output {@link buildDocsTree}: every node by route, each with one parent and
+ *   ordered children per slot, plus one diagnostic for each placement that
+ *   failed. {@link loadDocsTree} builds the CLI's own tree once per process.
+ * @position Between discovery and the readers: `astryx docs <route>`,
+ *   `astryx doctor`, and the docsite build all read this tree. The CLI's docs
+ *   and each integration's have a home here, and a flat topic's home is the
+ *   generated Unorganized level.
+ *   A namespace never scans files and never lists its children: a child names
+ *   its parent, or a namespace adopts a discovery group.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {CLI_ROOT} from '../fs/paths.mjs';
+import {loadCliSelfDocs} from '../discovery/cli-self-docs.mjs';
+import {routeSegment} from '../discovery/docs-section-key.mjs';
+import {diagnostic, sortDiagnostics} from './diagnostics.mjs';
+import {readDocView} from './read.mjs';
+import {packageSource} from './source.mjs';
+import {createDocId} from '../identity/provider-identity.mjs';
+import {CLI_PROVIDER_ID} from '../identity/providers.mjs';
+
+export {routeSegment};
+
+/** Where the CLI keeps the docs that only the tree reads. */
+export const TREE_DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs', 'tree');
+
+/** The package that owns the CLI's own docs. */
+const CLI_PROVIDER = '@astryxdesign/cli';
+
+/** One route segment: lowercase letters and digits joined by single hyphens. */
+export const ROUTE_SEGMENT_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * The generated level that `groupBy: 'kind'` makes for each kind: its route
+ * segment, title, and summary.
+ * @type {Readonly<Record<string, {segment: string, title: string, summary: string}>>}
+ */
+export const KIND_GROUPS = Object.freeze({
+  command: {
+    segment: 'commands',
+    title: 'Commands',
+    summary: 'Every command and subcommand.',
+  },
+  function: {
+    segment: 'functions',
+    title: 'Functions',
+    summary: 'Every function: its signature, parameters, returns, and errors.',
+  },
+  schema: {
+    segment: 'schemas',
+    title: 'Schemas',
+    summary: 'Every shape the CLI reads or returns, field by field.',
+  },
+  enum: {
+    segment: 'enums',
+    title: 'Enums',
+    summary:
+      'Every fixed list of values, such as error codes and response types.',
+  },
+  generic: {segment: 'guides', title: 'Guides', summary: 'Every guide.'},
+});
+
+/**
+ * @typedef {import('../../authoring/doctypes/namespace/type').NamespaceDoc} NamespaceDoc
+ * @typedef {import('../../authoring/doctypes/base/type').DocPlacement} DocPlacement
+ * @typedef {import('./diagnostics.mjs').CompilerDiagnostic} CompilerDiagnostic
+ */
+
+/**
+ * @typedef {object} TreeNamespaceInput
+ * @property {string} provider the package that owns the namespace
+ * @property {string} providerId the provider's ProviderId (its manifest
+ *   `providerId`, else its package name); node ids are built from it
+ * @property {number} [rank] which provider wins a contested route: the CLI's
+ *   own docs are 0, then each integration in configured order
+ * @property {string} source `<package>/<path>` of its file
+ * @property {NamespaceDoc} doc
+ */
+
+/**
+ * @typedef {object} TreeDocInput
+ * @property {string} provider the package that authored the doc
+ * @property {string} providerId the provider's ProviderId (its manifest
+ *   `providerId`, else its package name); node ids are built from it
+ * @property {number} [rank] which provider wins a contested route: the CLI's
+ *   own docs are 0, then each integration in configured order
+ * @property {string} source
+ * @property {import('../../authoring/doctypes/base/type').AuthoredDocKind} kind
+ *   the authored kind: `generic`, `command`, `function`, `schema`, or `enum`
+ * @property {string} name the doc's stable name
+ * @property {string} title
+ * @property {string} summary
+ * @property {string | null} group the discovery group adoption reads, or null
+ * @property {DocPlacement | undefined} placement
+ * @property {any} [ref] what a reader needs to open the doc, carried as given
+ */
+
+/**
+ * @typedef {object} TreeSlot
+ * @property {string} name
+ * @property {string} title
+ * @property {string[]} children child routes, in reading order
+ */
+
+/**
+ * A flat topic: a reference topic that no namespace places. The tree gives it
+ * a home in the generated Unorganized level, under its own name.
+ * @typedef {object} TreeTopicInput
+ * @property {string} provider the package that owns the topic
+ * @property {string} providerId the provider's ProviderId
+ * @property {string} name the topic's name, which stays its route
+ * @property {string} title
+ * @property {string} summary
+ * @property {string} source where the topic comes from, for diagnostics
+ * @property {string[]} [aliases] every other name the topic answers to: the
+ *   topics it replaced, directly or through a chain
+ */
+
+/** The route of the generated level that holds every flat topic. */
+export const UNORGANIZED = 'unorganized';
+
+/**
+ * @typedef {object} TreeNode
+ * @property {string | null} id the doc's DocId, built from its provider's
+ *   ProviderId, kind, and name: stable when the route moves; null on a
+ *   generated level, which has no authored doc
+ * @property {string} route
+ * @property {string} kind `namespace` or the doc's authored kind
+ * @property {string} provider the package that owns it
+ * @property {string} providerId its provider's ProviderId
+ * @property {string} name
+ * @property {string} title
+ * @property {string} summary
+ * @property {string | null} parent the parent's route; null at the top
+ * @property {string | null} slot the parent slot this node sits in
+ * @property {number | null} order
+ * @property {boolean} generated made by the compiler (a `groupBy: 'kind'`
+ *   level, or the Unorganized level), not authored
+ * @property {TreeSlot[]} slots a namespace's slots; empty for a leaf
+ * @property {string} source
+ * @property {any} [ref]
+ */
+
+/**
+ * @typedef {object} DocsTree
+ * @property {Map<string, TreeNode>} nodes by route, in route order
+ * @property {CompilerDiagnostic[]} diagnostics sorted
+ * @property {(route: string) => TreeNode | undefined} get
+ * @property {(route: string) => TreeNode | undefined} getFolded the node at a
+ *   route compared without case, as topic names are
+ * @property {() => TreeNode[]} roots the namespaces with no parent
+ * @property {(node: TreeNode) => TreeNode[]} ancestors top first, not the node
+ */
+
+/** @param {string} a @param {string} b */
+const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The namespace a `placement.parent` names: `namespace:<name>` in the doc's own
+ * package, or `<package>/namespace/<name>` spelled out. In phase 1 a parent
+ * must belong to the doc's own package.
+ * @param {string} parent
+ * @param {string} provider
+ * @param {Map<string, TreeNamespaceInput>} declared by `provider\0name`
+ * @returns {{key: string} | {error: string}}
+ */
+function resolveParent(parent, provider, declared) {
+  let owner = provider;
+  let name;
+  const short = /^namespace:(.+)$/u.exec(parent);
+  const qualified = /^(.+)\/namespace\/([^/]+)$/u.exec(parent);
+  if (short) {
+    name = short[1];
+  } else if (qualified) {
+    [, owner, name] = qualified;
+  } else {
+    return {
+      error: `placement.parent "${parent}" is not a namespace reference. Write "namespace:<name>".`,
+    };
+  }
+  if (owner !== provider) {
+    return {
+      error: `placement.parent "${parent}" belongs to ${owner}. A doc can only be placed in a namespace of its own package (${provider}).`,
+    };
+  }
+  const key = `${owner}\u0000${name}`;
+  if (!declared.has(key)) {
+    return {
+      error: `placement.parent "${parent}" names no namespace; ${provider} declares ${
+        [...declared.values()]
+          .filter(ns => ns.provider === provider)
+          .map(ns => `"${ns.doc.name}"`)
+          .sort(byText)
+          .join(', ') || 'none'
+      }.`,
+    };
+  }
+  return {key};
+}
+
+/**
+ * Build the tree. Pure: the same inputs give the same tree, whatever order
+ * they arrive in.
+ *
+ * A doc's home is decided once, in this order: its explicit `placement`, then
+ * the one adoption rule in its package that matches its group and kind. A
+ * placement that fails withdraws the doc; it never falls back to adoption. A
+ * doc with neither is a flat topic: it keeps its flat name as its route, and its
+ * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * integration's node that would take one is withdrawn with a diagnostic.
+ *
+ * @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
+ * @returns {DocsTree}
+ */
+export function buildDocsTree({namespaces, docs, topics = []}) {
+  /** @type {CompilerDiagnostic[]} */
+  const diagnostics = [];
+  /** @param {string} code @param {{provider: string, source: string}} at @param {string} message @param {string} [field] */
+  const report = (code, at, message, field) =>
+    diagnostics.push(
+      diagnostic(code, {
+        provider: at.provider,
+        source: at.source,
+        message,
+        ...(field ? {field} : {}),
+      }),
+    );
+
+  // Routes the CLI's own docs keep (spec:AST-046 FR11): the name of each of
+  // its flat topics, and the generated Unorganized level. Its namespaces keep
+  // theirs by rank, because they go into the tree first. Routes compare
+  // without case, as topic names do, so `CLI` claims `cli`.
+  const cliRoutes = new Set(topics.length > 0 ? [UNORGANIZED] : []);
+  for (const topic of topics) {
+    if (topic.provider === CLI_PROVIDER) cliRoutes.add(topic.name.toLowerCase());
+  }
+  // Every other name a topic answers to (the topics it replaced, directly or
+  // through a chain) is that topic's route too: `astryx docs <name>` opens the
+  // replacement, so no other doc can hold it.
+  /** @type {Map<string, TreeTopicInput>} */
+  const aliasRoutes = new Map();
+  for (const topic of topics) {
+    for (const alias of topic.aliases ?? []) {
+      aliasRoutes.set(alias.toLowerCase(), topic);
+    }
+  }
+
+  // Namespaces by package and name.
+  /** @type {Map<string, TreeNamespaceInput>} */
+  const declared = new Map();
+  const sortedNamespaces = [...namespaces].sort(
+    (a, b) =>
+      (a.rank ?? 0) - (b.rank ?? 0) ||
+      byText(a.provider, b.provider) ||
+      byText(a.doc.name, b.doc.name) ||
+      byText(a.source, b.source),
+  );
+  for (const input of sortedNamespaces) {
+    const {name} = input.doc;
+    if (!ROUTE_SEGMENT_RE.test(name)) {
+      report(
+        'invalid_namespace',
+        input,
+        `Namespace "${name}" is not a route segment. Use lowercase letters and digits joined by single hyphens.`,
+        'name',
+      );
+      continue;
+    }
+    const key = `${input.provider}\u0000${name}`;
+    const first = declared.get(key);
+    if (first) {
+      report(
+        'invalid_namespace',
+        input,
+        `Namespace "${name}" is declared twice in ${input.provider}: ${first.source} and ${input.source}.`,
+        'name',
+      );
+      continue;
+    }
+    declared.set(key, input);
+  }
+
+  // Each namespace's parent, checked against the parent's slots.
+  /** @type {Map<string, {parentKey: string, slot: string, order: number | null} | null>} */
+  const parentOf = new Map();
+  for (const [key, input] of declared) {
+    const {placement} = input.doc;
+    if (placement == null) {
+      parentOf.set(key, null);
+      continue;
+    }
+    const home = checkPlacement(placement, 'namespace', input, declared);
+    if ('error' in home) {
+      report('invalid_placement', input, home.error, 'placement');
+      continue;
+    }
+    parentOf.set(key, {
+      parentKey: home.key,
+      slot: home.slot,
+      order: placement.order ?? null,
+    });
+  }
+
+  // Routes, top-down. A cycle, or an ancestor that was withdrawn, leaves a
+  // namespace (and everything under it) out of the tree.
+  /** @type {Map<string, string | null>} */
+  const routeOf = new Map();
+  /** @param {string} key @param {Set<string>} seen @returns {string | null} */
+  const routeFor = (key, seen) => {
+    if (routeOf.has(key))
+      return /** @type {string | null} */ (routeOf.get(key));
+    if (!parentOf.has(key) || seen.has(key)) return null;
+    seen.add(key);
+    const home = parentOf.get(key);
+    const name = /** @type {TreeNamespaceInput} */ (declared.get(key)).doc.name;
+    const parentRoute = home == null ? '' : routeFor(home.parentKey, seen);
+    const route =
+      parentRoute == null
+        ? null
+        : parentRoute === ''
+          ? name
+          : `${parentRoute}/${name}`;
+    routeOf.set(key, route);
+    return route;
+  };
+  for (const [key, input] of declared) {
+    if (routeFor(key, new Set()) == null && parentOf.has(key)) {
+      report(
+        'invalid_placement',
+        input,
+        `Namespace "${input.doc.name}" has no route: its placement forms a cycle, or a namespace above it was withdrawn.`,
+        'placement',
+      );
+    }
+  }
+
+  /** @type {Map<string, TreeNode>} */
+  const nodes = new Map();
+  /** @type {Map<string, TreeNode>} nodes by route, compared without case */
+  const byFoldedRoute = new Map();
+  /** @param {TreeNode} node */
+  const nodeLabel = node => node.id ?? `the generated level "${node.route}"`;
+  /** @param {TreeNode} node @param {{provider: string, source: string}} at */
+  const addNode = (node, at) => {
+    const folded = node.route.toLowerCase();
+    if (node.provider !== CLI_PROVIDER && cliRoutes.has(folded)) {
+      report(
+        'duplicate_route',
+        at,
+        `${nodeLabel(node)} takes the route "${node.route}", which the CLI's own docs keep. Rename it.`,
+      );
+      return false;
+    }
+    const alias = aliasRoutes.get(folded);
+    if (
+      alias != null &&
+      node.provider !== CLI_PROVIDER &&
+      node.ref?.flatTopic !== alias.name
+    ) {
+      report(
+        'duplicate_route',
+        at,
+        `${nodeLabel(node)} takes the route "${node.route}", which the topic "${alias.name}" also answers to, because it replaced a topic of that name. Rename it.`,
+      );
+      return false;
+    }
+    const taken = byFoldedRoute.get(folded);
+    if (taken) {
+      report(
+        'duplicate_route',
+        at,
+        `${nodeLabel(node)} and ${nodeLabel(taken)} both have the route "${node.route}". Rename or move one of them.`,
+      );
+      return false;
+    }
+    nodes.set(node.route, node);
+    byFoldedRoute.set(folded, node);
+    return true;
+  };
+
+  // Parents before children, so a namespace placed in a withdrawn namespace
+  // is withdrawn before anything is placed in it.
+  const parentsFirst = [...declared].sort(
+    ([a], [b]) =>
+      String(routeOf.get(a) ?? '').split('/').length -
+      String(routeOf.get(b) ?? '').split('/').length,
+  );
+  for (const [key, input] of parentsFirst) {
+    const route = routeOf.get(key);
+    if (route == null) continue;
+    const home = parentOf.get(key);
+    if (home != null && routeOf.get(home.parentKey) == null) {
+      routeOf.set(key, null);
+      report(
+        'invalid_placement',
+        input,
+        `Namespace "${input.doc.name}" has no route: the namespace it is placed in was withdrawn.`,
+        'placement',
+      );
+      continue;
+    }
+    const parentRoute =
+      home == null ? null : /** @type {string} */ (routeOf.get(home.parentKey));
+    const added = addNode(
+      {
+        id: createDocId(input.providerId, 'namespace', input.doc.name),
+        route,
+        kind: 'namespace',
+        provider: input.provider,
+        providerId: input.providerId,
+        name: input.doc.name,
+        title: input.doc.title,
+        summary: input.doc.summary,
+        parent: parentRoute,
+        slot: home?.slot ?? null,
+        order: home?.order ?? null,
+        generated: false,
+        slots: Object.entries(input.doc.slots).map(([name, slot]) => ({
+          name,
+          title: slot.title,
+          children: [],
+        })),
+        source: input.source,
+      },
+      input,
+    );
+    // A withdrawn namespace has no route, so a namespace placed in it is
+    // withdrawn too, and a doc placed in it says so.
+    if (!added) routeOf.set(key, null);
+  }
+
+  // Docs: explicit placement, else one adoption rule, else no home.
+  const sortedDocs = [...docs].sort(
+    (a, b) =>
+      (a.rank ?? 0) - (b.rank ?? 0) ||
+      byText(a.provider, b.provider) ||
+      byText(a.kind, b.kind) ||
+      byText(a.name, b.name) ||
+      byText(a.source, b.source),
+  );
+  for (const doc of sortedDocs) {
+    /** @type {{parentRoute: string, slot: string, order: number | null} | null} */
+    let home = null;
+    if (doc.placement != null) {
+      const placed = checkPlacement(doc.placement, doc.kind, doc, declared);
+      if ('error' in placed) {
+        report('invalid_placement', doc, placed.error, 'placement');
+        continue;
+      }
+      const parentRoute = routeOf.get(placed.key);
+      if (parentRoute == null) {
+        report(
+          'invalid_placement',
+          doc,
+          `placement.parent "${doc.placement.parent}" names a namespace that has no route.`,
+          'placement',
+        );
+        continue;
+      }
+      home = {
+        parentRoute,
+        slot: placed.slot,
+        order: doc.placement.order ?? null,
+      };
+    } else if (doc.group != null) {
+      const matches = adoptionsFor(doc, declared, routeOf);
+      if (matches.length > 1) {
+        report(
+          'overlapping_adoption',
+          doc,
+          `${doc.provider}/${doc.kind}/${doc.name} is adopted by ${matches
+            .map(m => `"${m.namespace.doc.name}"`)
+            .join(' and ')}; exactly one namespace may adopt a doc.`,
+        );
+        continue;
+      }
+      if (matches.length === 1) {
+        const [{key, rule, namespace}] = matches;
+        const nsRoute = /** @type {string} */ (routeOf.get(key));
+        if (rule.groupBy === 'kind') {
+          const group = KIND_GROUPS[doc.kind] ?? {
+            segment: `${routeSegment(doc.kind)}s`,
+            title: doc.kind,
+            summary: `Every ${doc.kind} doc.`,
+          };
+          const groupRoute = `${nsRoute}/${group.segment}`;
+          if (!nodes.has(groupRoute)) {
+            const kinds = rule.source.kinds ?? [];
+            addNode(
+              {
+                id: null,
+                route: groupRoute,
+                kind: 'namespace',
+                provider: namespace.provider,
+                providerId: namespace.providerId,
+                name: group.segment,
+                title: group.title,
+                summary: group.summary,
+                parent: nsRoute,
+                slot: rule.into,
+                order: kinds.includes(/** @type {any} */ (doc.kind))
+                  ? kinds.indexOf(/** @type {any} */ (doc.kind))
+                  : null,
+                generated: true,
+                slots: [{name: 'items', title: group.title, children: []}],
+                source: namespace.source,
+              },
+              namespace,
+            );
+          }
+          const groupNode = nodes.get(groupRoute);
+          if (!groupNode?.generated) continue;
+          home = {parentRoute: groupRoute, slot: 'items', order: null};
+        } else {
+          home = {parentRoute: nsRoute, slot: rule.into, order: null};
+        }
+      }
+    }
+    if (home == null) continue;
+    const segment = routeSegment(doc.name);
+    if (segment === '') {
+      report(
+        'invalid_placement',
+        doc,
+        `${doc.provider}/${doc.kind}/${doc.name} has no route segment: its name holds no letters or digits.`,
+        'name',
+      );
+      continue;
+    }
+    addNode(
+      {
+        id: createDocId(doc.providerId, doc.kind, doc.name),
+        route: `${home.parentRoute}/${segment}`,
+        kind: doc.kind,
+        provider: doc.provider,
+        providerId: doc.providerId,
+        name: doc.name,
+        title: doc.title,
+        summary: doc.summary,
+        parent: home.parentRoute,
+        slot: home.slot,
+        order: home.order,
+        generated: false,
+        slots: [],
+        source: doc.source,
+        ...(doc.ref === undefined ? {} : {ref: doc.ref}),
+      },
+      doc,
+    );
+  }
+
+  // The generated Unorganized level (spec:AST-046 FR12): every flat topic sits
+  // here, in the order the topic list reads, so every doc has a home in the
+  // tree. A topic keeps its own name as its route.
+  if (topics.length > 0) {
+    const home = {
+      id: null,
+      route: UNORGANIZED,
+      kind: 'namespace',
+      provider: CLI_PROVIDER,
+      providerId: CLI_PROVIDER_ID,
+      name: UNORGANIZED,
+      title: 'Unorganized',
+      summary:
+        'Every topic that no section places yet. Each keeps its own name; open one by it.',
+      parent: null,
+      slot: null,
+      order: null,
+      generated: true,
+      slots: [{name: 'topics', title: 'Topics', children: []}],
+      source: 'generated',
+    };
+    if (addNode(home, {provider: CLI_PROVIDER, source: 'generated'})) {
+      topics.forEach((topic, i) => {
+        addNode(
+          {
+            id: createDocId(topic.providerId, 'generic', topic.name),
+            route: topic.name,
+            kind: 'generic',
+            provider: topic.provider,
+            providerId: topic.providerId,
+            name: topic.name,
+            title: topic.title,
+            summary: topic.summary,
+            parent: UNORGANIZED,
+            slot: 'topics',
+            order: i,
+            generated: false,
+            slots: [],
+            source: topic.source,
+            ref: {flatTopic: topic.name},
+          },
+          topic,
+        );
+      });
+    }
+  }
+
+  // Children, per slot, in reading order: order, then title, then id.
+  for (const node of nodes.values()) {
+    if (node.parent == null) continue;
+    const parent = nodes.get(node.parent);
+    parent?.slots
+      .find(slot => slot.name === node.slot)
+      ?.children.push(node.route);
+  }
+  for (const node of nodes.values()) {
+    for (const slot of node.slots) {
+      slot.children.sort((a, b) => {
+        const x = /** @type {TreeNode} */ (nodes.get(a));
+        const y = /** @type {TreeNode} */ (nodes.get(b));
+        return (
+          (x.order ?? Infinity) - (y.order ?? Infinity) ||
+          byText(x.title.toLowerCase(), y.title.toLowerCase()) ||
+          byText(x.id ?? x.route, y.id ?? y.route)
+        );
+      });
+    }
+  }
+
+  // A topic that answers, through `replaces`, to a route the CLI's own docs
+  // keep cannot have it: the CLI's doc opens there. Say so, against the topic.
+  for (const topic of topics) {
+    if (topic.provider === CLI_PROVIDER) continue;
+    for (const alias of topic.aliases ?? []) {
+      const holder = byFoldedRoute.get(alias.toLowerCase());
+      if (holder != null && holder.provider === CLI_PROVIDER) {
+        report(
+          'duplicate_route',
+          topic,
+          `The topic "${topic.name}" answers to "${alias}" through replaces, but the CLI's own docs keep that route, so \`astryx docs ${alias}\` opens theirs. Drop that replacement.`,
+        );
+      }
+    }
+  }
+
+  const sorted = new Map([...nodes.entries()].sort(([a], [b]) => byText(a, b)));
+  return {
+    nodes: sorted,
+    diagnostics: sortDiagnostics(diagnostics),
+    get: route => sorted.get(route),
+    getFolded: route => byFoldedRoute.get(String(route).toLowerCase()),
+    roots: () => [...sorted.values()].filter(node => node.parent == null),
+    ancestors: node => {
+      /** @type {TreeNode[]} */
+      const chain = [];
+      let parent = node.parent == null ? undefined : sorted.get(node.parent);
+      while (parent) {
+        chain.unshift(parent);
+        parent = parent.parent == null ? undefined : sorted.get(parent.parent);
+      }
+      return chain;
+    },
+  };
+}
+
+/**
+ * Check a placement against the namespace it names: the namespace exists in
+ * the doc's own package, the slot is one it declares, and the slot accepts the
+ * doc's kind.
+ * @param {DocPlacement} placement
+ * @param {string} kind
+ * @param {{provider: string}} at
+ * @param {Map<string, TreeNamespaceInput>} declared
+ * @returns {{key: string, slot: string} | {error: string}}
+ */
+function checkPlacement(placement, kind, at, declared) {
+  const target = resolveParent(placement.parent, at.provider, declared);
+  if ('error' in target) return target;
+  const parent = /** @type {TreeNamespaceInput} */ (declared.get(target.key));
+  const slotNames = Object.keys(parent.doc.slots);
+  const slot = placement.slot ?? (slotNames.length === 1 ? slotNames[0] : null);
+  if (slot == null) {
+    return {
+      error: `placement names no slot, and namespace "${parent.doc.name}" has ${slotNames.length} (${slotNames.join(', ')}). Name one with placement.slot.`,
+    };
+  }
+  const declaredSlot = parent.doc.slots[slot];
+  if (declaredSlot == null) {
+    return {
+      error: `placement.slot "${slot}" is not a slot of namespace "${parent.doc.name}"; it declares ${slotNames.join(', ')}.`,
+    };
+  }
+  if (!declaredSlot.accepts.kinds.includes(/** @type {any} */ (kind))) {
+    return {
+      error: `slot "${slot}" of namespace "${parent.doc.name}" does not accept ${kind} docs; it accepts ${declaredSlot.accepts.kinds.join(', ')}.`,
+    };
+  }
+  return {key: target.key, slot};
+}
+
+/**
+ * Every adoption rule in the doc's own package that matches its group and
+ * kind, from namespaces that have a route.
+ * @param {TreeDocInput} doc
+ * @param {Map<string, TreeNamespaceInput>} declared
+ * @param {Map<string, string | null>} routeOf
+ */
+function adoptionsFor(doc, declared, routeOf) {
+  /** @type {Array<{key: string, namespace: TreeNamespaceInput, rule: NonNullable<NamespaceDoc['adopts']>[number]}>} */
+  const matches = [];
+  for (const [key, namespace] of declared) {
+    if (namespace.provider !== doc.provider || routeOf.get(key) == null)
+      continue;
+    for (const rule of namespace.doc.adopts ?? []) {
+      if (rule.source.group !== doc.group) continue;
+      if (
+        rule.source.kinds &&
+        !rule.source.kinds.includes(/** @type {any} */ (doc.kind))
+      ) {
+        continue;
+      }
+      matches.push({key, namespace, rule});
+    }
+  }
+  return matches;
+}
+
+/**
+ * The files under {@link TREE_DOCS_DIR}, sorted.
+ * @param {string} [dir]
+ * @returns {string[]}
+ */
+export function treeDocFiles(dir = TREE_DOCS_DIR) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter(file => /^[\w-]+\.doc\.mjs$/u.test(file))
+    .sort(byText)
+    .map(file => path.join(dir, file));
+}
+
+/**
+ * The CLI's own tree inputs: the namespace docs and guides under
+ * assets/docs/tree, and, unless left out, every typed self-doc with its
+ * `namespace` group. A file that fails to load or parse is a diagnostic, never
+ * a thrown error.
+ * @param {{selfDocs?: boolean, dir?: string}} [options]
+ * @returns {Promise<{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], diagnostics: CompilerDiagnostic[]}>}
+ */
+export async function loadTreeInputs({
+  selfDocs = true,
+  dir = TREE_DOCS_DIR,
+} = {}) {
+  /** @type {TreeNamespaceInput[]} */
+  const namespaces = [];
+  /** @type {TreeDocInput[]} */
+  const docs = [];
+  /** @type {CompilerDiagnostic[]} */
+  const diagnostics = [];
+  for (const file of treeDocFiles(dir)) {
+    const source = packageSource(file);
+    const at = {provider: CLI_PROVIDER, source};
+    let doc;
+    try {
+      doc = await readDocView(file, {
+        root: 'tree',
+        provider: CLI_PROVIDER,
+        loader: 'native',
+        strict: true,
+      });
+    } catch (error) {
+      diagnostics.push(
+        diagnostic('invalid_doc', {
+          ...at,
+          message: error instanceof Error ? error.message : String(error),
+        }),
+      );
+      continue;
+    }
+    const stem = path.basename(file, '.doc.mjs');
+    if (doc?.name !== stem) {
+      diagnostics.push(
+        diagnostic('invalid_doc', {
+          ...at,
+          field: 'name',
+          message: `${path.basename(file)} declares name "${doc?.name}"; a docs tree file is named after its doc (${doc?.name}.doc.mjs).`,
+        }),
+      );
+      continue;
+    }
+    if (doc.type === 'namespace') {
+      namespaces.push({
+        provider: CLI_PROVIDER,
+        providerId: CLI_PROVIDER_ID,
+        source,
+        doc,
+      });
+    } else if (doc.type === 'generic') {
+      if (doc.placement == null) {
+        diagnostics.push(
+          diagnostic('invalid_placement', {
+            ...at,
+            field: 'placement',
+            message: `${path.basename(file)} has no placement. A guide in the docs tree names its parent namespace with placement.parent.`,
+          }),
+        );
+        continue;
+      }
+      docs.push({
+        provider: CLI_PROVIDER,
+        providerId: CLI_PROVIDER_ID,
+        source,
+        kind: 'generic',
+        name: doc.name,
+        title: doc.title,
+        summary: doc.description,
+        group: null,
+        placement: doc.placement,
+        ref: {topicFile: file},
+      });
+    } else {
+      diagnostics.push(
+        diagnostic('wrong_kind', {
+          ...at,
+          message: `${path.basename(file)} is stamped type ${JSON.stringify(doc?.type)}; the docs tree reads namespace and generic docs.`,
+        }),
+      );
+    }
+  }
+  if (selfDocs) {
+    const {loaded} = await loadCliSelfDocs();
+    for (const {source, doc} of loaded) {
+      docs.push({
+        provider: CLI_PROVIDER,
+        providerId: CLI_PROVIDER_ID,
+        source: `${CLI_PROVIDER}/${source}`,
+        kind: doc.type,
+        name: doc.name,
+        title: doc.displayName ?? doc.name,
+        summary: doc.summary ?? doc.description ?? '',
+        group: typeof doc.namespace === 'string' ? doc.namespace : null,
+        placement: doc.placement,
+        ref: {selfDoc: doc},
+      });
+    }
+  }
+  return {namespaces, docs, diagnostics};
+}
+
+/** @type {Map<string, Promise<DocsTree>>} */
+const built = new Map();
+
+/**
+ * The CLI's own docs tree, built once per process. With `selfDocs: false` it
+ * holds only the namespaces and guides, which is all a topic list needs.
+ * @param {{selfDocs?: boolean, fresh?: boolean}} [options]
+ * @returns {Promise<DocsTree>}
+ */
+export function loadDocsTree({selfDocs = true, fresh = false} = {}) {
+  const key = selfDocs ? 'full' : 'namespaces';
+  let tree = fresh ? undefined : built.get(key);
+  if (!tree) {
+    tree = loadTreeInputs({selfDocs}).then(inputs => {
+      const result = buildDocsTree(inputs);
+      return {
+        ...result,
+        diagnostics: sortDiagnostics([
+          ...inputs.diagnostics,
+          ...result.diagnostics,
+        ]),
+      };
+    });
+    built.set(key, tree);
+  }
+  return tree;
+}