Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
75.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Shared doc-loading and topic-resolution helpers for the docs leaves.
 *
 * @input The project's doc catalog — the CLI's own
 *   packages/cli/assets/docs/{topic}.doc.mjs plus every topic the configured
 *   integrations contribute — and, when a --dense/--zh overlay is requested,
 *   the sibling {topic}.doc.dense.mjs / {topic}.doc.zh.mjs.
 * @output Catalog access, the compiler input for a topic, and the compiled
 *   node for it: lowered (overlaid, extensions merged, keys stamped) or linked
 *   (token references resolved too), memoized per catalog.
 * @position Sits beside docs.mjs (api/docs/). Hands topics to
 *   foundation/doc-compiler (which loads their files) and memoizes the nodes
 *   per catalog, so no leaf, doctor check or search loads, merges, or resolves
 *   docs on its own. Discovery itself lives in
 *   foundation/discovery/docs-discovery, which the catalog comes from.
 */

import * as path from 'node:path';
import {Project} from '../../foundation/config/project.mjs';
import {
  DocsCatalog,
  isGuideRoute,
  mergeTopicReport,
} from '../../foundation/discovery/docs-discovery.mjs';
import {checkDocTypes} from '../../foundation/discovery/doc-types.mjs';
import {integrationDocFiles} from '../../foundation/discovery/integration-doc-files.mjs';
import {
  linkReferenceTopic,
  lowerReferenceTopic,
} from '../../foundation/doc-compiler/compile.mjs';
import {
  deepFreeze,
  loadTopicFile,
  loadTopicInput,
  OVERLAY_LANGUAGES,
  overlayLanguages,
} from '../../foundation/doc-compiler/read.mjs';
import {
  buildDocsTree,
  isExperimentalTreeNode,
  loadTreeInputs,
} from '../../foundation/doc-compiler/tree.mjs';
import {sortDiagnostics} from '../../foundation/doc-compiler/diagnostics.mjs';
import {
  linkBlocks,
  linkFields,
  parseLinkTarget,
  renderTokens,
} from '../../foundation/doc-compiler/links.mjs';
import {
  createDocId,
  normalizeProviderId,
} from '../../foundation/identity/provider-identity.mjs';
import {
  cliDocIndex,
  cliDocSection,
} from '../../foundation/discovery/cli-self-docs.mjs';
import {
  AUTHORING_REFERENCE_ROUTE,
  EXPERIMENTAL_AUTHORING_ROUTE,
  isExperimentalSelfDoc,
  loadAuthoringSelfDocs,
  schemaFieldTable,
  selfDocSection,
} from '../../foundation/discovery/authoring-self-docs.mjs';
import {CLI_PROVIDER_ID} from '../../foundation/identity/providers.mjs';
import {
  CORE_PACKAGE,
  discoverOwnedComponents,
  discoverValidIntegrationComponents,
} from '../../foundation/discovery/component-discovery.mjs';
import {loadComponentDoc} from '../../foundation/discovery/component-loader.mjs';
import {
  discoverCoreTemplates,
  discoverIntegrationTemplatesForOne,
} from '../../foundation/discovery/template-adapter.mjs';
import {findCoreDir} from '../../foundation/fs/paths.mjs';
import {reusedWhileUnchanged} from '../../foundation/fs/read-record.mjs';
import {AstryxError} from '../error.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {orderRouteSuggestions} from '../../foundation/text/suggest-order.mjs';
import {formatCliCommand} from '../../foundation/env/package-manager.mjs';

export {OVERLAY_LANGUAGES, overlayLanguages};

/**
 * The project's topics: the built-in ones plus whatever the configured
 * integrations contribute.
 *
 * A docs read must not depend on a healthy project config. `astryx docs
 * tokens` answered without loading anything before integrations could
 * contribute topics, and it still answers when the config is unreadable — the
 * built-in topics are the floor, and the integration issues surface on the
 * commands that own them.
 *
 * @param {string} [cwd]
 * @returns {Promise<DocsCatalog>}
 */
export async function loadDocsCatalog(cwd = process.cwd()) {
  try {
    const project = await Project.load(cwd);
    return await project.docs();
  } catch {
    return DocsCatalog.fromBuiltins();
  }
}

/**
 * The overlay a read applies: none for the authored language.
 * @param {string | null | undefined} lang
 * @returns {string | null}
 */
function overlayLanguage(lang) {
  return lang && lang !== 'en' ? lang : null;
}

/** @type {WeakMap<DocsCatalog, Map<string, Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>>>} */
const loweredByCatalog = new WeakMap();

/**
 * One topic, lowered for `lang` with its links as written: overlaid,
 * extensions merged, keys stamped. Memoized per catalog, so a read that
 * references a topic twice loads it once. Every read of the catalog shares the
 * memoized node, so it is frozen; the lenses hand readers copies.
 * @param {DocsCatalog} catalog
 * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
 * @param {string | null} [lang]
 * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
 */
function lowerRawTopic(catalog, entry, lang = null) {
  const overlay = overlayLanguage(lang);
  let cache = loweredByCatalog.get(catalog);
  if (!cache) {
    cache = new Map();
    loweredByCatalog.set(catalog, cache);
  }
  const key = `${entry.name.toLowerCase()}\u0000${overlay ?? ''}`;
  let lowered = cache.get(key);
  if (!lowered) {
    lowered = loadTopicInput(entry, overlay).then(input =>
      deepFreeze(lowerReferenceTopic(input)),
    );
    cache.set(key, lowered);
  }
  return lowered;
}

/**
 * @typedef {import('../../foundation/doc-compiler/tree.mjs').DocsTree} DocsTree
 * @typedef {import('../../foundation/doc-compiler/tree.mjs').TreeNode} TreeNode
 * @typedef {import('../../foundation/doc-compiler/links.mjs').LinkProblem} LinkProblem
 * @typedef {import('../../foundation/doc-compiler/links.mjs').LinkResolver} LinkResolver
 * @typedef {import('../../foundation/doc-compiler/links.mjs').DocIncluder} DocIncluder
 * @typedef {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} DocsTopicEntry
 */

/** @type {WeakMap<DocsCatalog, Map<string, Promise<{node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode, problems: LinkProblem[]}>>>} */
const linkedByCatalog = new WeakMap();

/**
 * The CLI's own topics alone, for a check that runs without a project.
 * @returns {DocsCatalog}
 */
export function builtinCatalog() {
  return DocsCatalog.fromBuiltins();
}

/**
 * The provider id a topic's (or an extension's) links resolve against: its
 * owner's.
 * @param {{providerId?: string, package: string}} entry
 * @returns {string}
 */
function providerOf(entry) {
  return normalizeProviderId(entry.providerId ?? entry.package);
}

/**
 * The npm package that wrote each section of a lowered topic: the topic's own
 * package, or the package of the extension that contributed the section
 * (spec cli-surface INV28).
 * @param {DocsTopicEntry} entry
 * @param {{sectionProviders?: Record<string, string>}} node the lowered topic
 * @returns {(sectionId: string | undefined) => string}
 */
export function sectionPackageOf(entry, node) {
  /** @type {Map<string, string>} */
  const byProvider = new Map([[providerOf(entry), entry.package]]);
  for (const extension of entry.extensions ?? []) {
    byProvider.set(providerOf(extension), extension.package);
  }
  return sectionId => {
    const provider =
      sectionId == null ? undefined : node.sectionProviders?.[sectionId];
    return (
      (provider == null
        ? undefined
        : byProvider.get(normalizeProviderId(provider))) ?? entry.package
    );
  };
}

/**
 * One topic, lowered for `lang` with every link between docs resolved
 * (spec:AST-047 FR9): an inline `{@link <target>}` reads as the command that
 * opens its doc, and a `reference` block carries the doc it names and the
 * `content` it includes of it. Memoized per catalog and frozen, like the
 * lowered node.
 * @param {DocsCatalog} catalog
 * @param {DocsTopicEntry} entry
 * @param {string | null} [lang]
 * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
 */
export async function lowerTopic(catalog, entry, lang = null) {
  return (await linkTopic(catalog, entry, lang)).node;
}

/**
 * Each link in a topic that names no doc.
 * @param {DocsCatalog} catalog
 * @param {DocsTopicEntry} entry
 * @returns {Promise<LinkProblem[]>}
 */
export async function topicLinkProblems(catalog, entry) {
  return (await linkTopic(catalog, entry, null)).problems;
}

/**
 * @param {DocsCatalog} catalog
 * @param {DocsTopicEntry} entry
 * @param {string | null} lang
 */
function linkTopic(catalog, entry, lang) {
  let cache = linkedByCatalog.get(catalog);
  if (!cache) {
    cache = new Map();
    linkedByCatalog.set(catalog, cache);
  }
  const key = `${entry.name.toLowerCase()}\u0000${overlayLanguage(lang) ?? ''}`;
  let linked = cache.get(key);
  if (!linked) {
    linked = (async () => {
      const raw = await lowerRawTopic(catalog, entry, lang);
      /** @type {Map<string, {resolve: LinkResolver, include: DocIncluder}>} */
      const linkers = new Map();
      /** @param {string} provider */
      const linkerFor = async provider => {
        let linker = linkers.get(provider);
        if (!linker) {
          linker = {
            resolve: await linkResolver(catalog, provider),
            include: await docIncluder(catalog, provider),
          };
          linkers.set(provider, linker);
        }
        return linker;
      };
      /** @type {LinkProblem[]} */
      const problems = [];
      const sections = [];
      // Each section resolves its links against the provider that wrote it:
      // an extension's sections against the extension's provider, never the
      // base topic's.
      for (const section of raw.doc.sections) {
        const provider = raw.sectionProviders?.[section.id];
        const {resolve, include} = await linkerFor(
          provider == null ? providerOf(entry) : normalizeProviderId(provider),
        );
        const linked = await linkBlocks(
          section.content,
          resolve,
          {section: section.id ?? section.title},
          include,
        );
        problems.push(...linked.problems);
        sections.push({...section, content: linked.content});
      }
      // The topic's own text outside its sections, its description and
      // summary, resolves against the topic's own provider.
      const {resolve} = await linkerFor(providerOf(entry));
      const fields = await linkFields(topicTextFields(raw.doc), resolve);
      problems.push(...fields.problems);
      return {
        node: deepFreeze({
          ...raw,
          doc: {...raw.doc, ...fields.doc, sections},
        }),
        problems,
      };
    })();
    cache.set(key, linked);
  }
  return linked;
}

/**
 * The text fields of a topic outside its sections: its description and
 * summary, those it has.
 * @param {any} doc
 * @returns {{description?: string, summary?: string}}
 */
function topicTextFields(doc) {
  /** @type {{description?: string, summary?: string}} */
  const fields = {};
  if (typeof doc?.description === 'string')
    fields.description = doc.description;
  if (typeof doc?.summary === 'string') fields.summary = doc.summary;
  return fields;
}

/**
 * One line of a doc's text, such as a topic's or a tree node's summary, with
 * every inline link resolved against the provider that wrote it (spec:AST-047
 * FR9). A link that names no doc prints as written; doctor names it.
 * @param {DocsCatalog} catalog
 * @param {string} providerId the provider id of the doc the text sits in
 * @param {string} text
 * @returns {Promise<string>}
 */
export async function linkDocText(catalog, providerId, text) {
  if (typeof text !== 'string') return text;
  if (!text.includes('{@link')) return renderTokens(text);
  let provider;
  try {
    provider = normalizeProviderId(providerId);
  } catch {
    return text;
  }
  const linked = await linkFields(
    {description: text},
    await linkResolver(catalog, provider),
  );
  return linked.doc.description ?? text;
}

/**
 * A component doc with every inline link in its text fields resolved
 * (spec:AST-047 FR9): its description, usage, best practices, and each prop's
 * and example's description. Code fields are shown as written. A Core
 * component's links resolve against the CLI's own docs provider; an
 * integration's against that integration's.
 * @template T
 * @param {DocsCatalog} catalog
 * @param {string} providerId the provider id the component's links resolve
 *   against
 * @param {T} doc
 * @returns {Promise<{doc: T, problems: LinkProblem[]}>}
 */
export async function linkComponentDoc(catalog, providerId, doc) {
  // Doc tokens render in the same pass as links (resolveInline).
  if (!JSON.stringify(doc ?? null).includes('{@')) {
    return {doc, problems: []};
  }
  return linkFields(
    doc,
    await linkResolver(catalog, normalizeProviderId(providerId)),
  );
}

/**
 * The provider id a component's doc links resolve against: the CLI's own for
 * a Core component, else its owner package's (or the provider id its manifest
 * declares).
 * @param {string} ownerPackage
 * @param {string} [providerId]
 * @returns {string}
 */
export function componentLinkProvider(ownerPackage, providerId) {
  return ownerPackage === CORE_PACKAGE
    ? CLI_PROVIDER_ID
    : normalizeProviderId(providerId ?? ownerPackage);
}

/** @type {WeakMap<DocsCatalog, Promise<DocsTree>>} */
const treesByCatalog = new WeakMap();

/**
 * The project's docs tree: the CLI's own docs plus the namespace docs and
 * placed guides the configured integrations ship (spec:AST-046), built once
 * per catalog. Without integration docs it is the CLI's tree, built once per
 * process.
 * @param {DocsCatalog} catalog
 * @param {{fresh?: boolean}} [options] `fresh`: reread the CLI's tree files
 * @returns {Promise<DocsTree>}
 */
export function projectTree(catalog, {fresh = false} = {}) {
  let tree = treesByCatalog.get(catalog);
  if (!tree || fresh) {
    tree = buildProjectTree(catalog, fresh);
    treesByCatalog.set(catalog, tree);
  }
  return tree;
}

/** The CLI's own tree files, loaded again after one of them changes. */
const cliTreeInputs = reusedWhileUnchanged(() => loadTreeInputs());

/**
 * Every flat topic in the catalog, as the tree's topic levels read it.
 * @param {DocsCatalog} catalog
 * @returns {Promise<import('../../foundation/doc-compiler/tree.mjs').TreeTopicInput[]>}
 */
async function flatTopicInputs(catalog) {
  /** @type {import('../../foundation/doc-compiler/tree.mjs').TreeTopicInput[]} */
  const topics = [];
  for (const entry of catalog.entries()) {
    const aliases = catalog.aliasesOf(entry);
    let {title, description, category} = entry;
    if (title == null || description == null || category === undefined) {
      try {
        const file = await loadTopicFile(entry.path, null);
        title ??= file.doc?.title;
        description ??= file.doc?.description;
        category ??= file.doc?.category;
      } catch {
        // A topic that does not load is reported where it is read.
      }
    }
    topics.push({
      provider: entry.package,
      providerId: entry.providerId ?? entry.package,
      name: entry.name,
      title: title ?? entry.name,
      // Rendered once, with the tree's other summaries (buildProjectTree).
      summary: description ?? '',
      category: category ?? null,
      source: `${entry.package}:${entry.name}`,
      ...(aliases.length > 0 ? {aliases} : {}),
    });
  }
  return topics;
}

/**
 * The CLI's tree, each configured integration's namespaces and guides, and
 * every flat topic in the generated level for its category.
 * @param {DocsCatalog} catalog
 * @param {boolean} fresh
 * @returns {Promise<DocsTree>}
 */
async function buildProjectTree(catalog, fresh) {
  const added = catalog.treeInputs;
  const cli = await cliTreeInputs({fresh});
  const result = buildDocsTree({
    namespaces: [...cli.namespaces, ...added.flatMap(each => each.namespaces)],
    docs: [...cli.docs, ...added.flatMap(each => each.guides)],
    topics: await flatTopicInputs(catalog),
  });
  // A guide the tree places that an integration replaces or extends by its
  // route, or by the route it had before it moved: reads apply what it does,
  // and a replacement lists under its own title and summary.
  // Each doc applies in configured order to the guide its route names, so a
  // doc naming a guide's old route and one naming its new route stack as if
  // both named the same one.
  for (const record of catalog.guideTargeters) {
    const node = placedGuideAt(
      result,
      /** @type {string} */ (record.replaces ?? record.extendsTopic),
    );
    if (!node) continue;
    /** @type {import('../../foundation/discovery/docs-discovery.mjs').GuideOverlay} */
    const overlay = node.guideOverlay ?? {replacement: null, extensions: []};
    if (record.replaces != null) {
      node.guideOverlay = {
        replacement: record,
        // Extensions were authored against the content that just went away.
        extensions: [],
        ...(overlay.replacement
          ? {replacedPackage: overlay.replacement.package}
          : {}),
      };
    } else {
      node.guideOverlay = {
        ...overlay,
        extensions: [
          ...overlay.extensions,
          {
            package: record.package,
            path: record.path,
            ...(record.providerId ? {providerId: record.providerId} : {}),
          },
        ],
      };
    }
  }
  for (const node of result.nodes.values()) {
    const replacement = node.guideOverlay?.replacement;
    if (replacement) {
      node.title = replacement.title ?? node.title;
      node.summary = replacement.description ?? node.summary;
    }
  }
  // A summary is a doc's text too: each link in it reads as the command that
  // opens its doc, wherever the tree's summaries print (spec:AST-047 FR9).
  for (const node of result.nodes.values()) {
    if (typeof node.summary === 'string' && node.summary.includes('{@')) {
      const replacement = node.guideOverlay?.replacement;
      node.summary = await linkSummary(
        catalog,
        result,
        replacement
          ? (replacement.providerId ?? replacement.package)
          : node.providerId,
        node.summary,
      );
    }
  }
  return {
    ...result,
    diagnostics: sortDiagnostics([...cli.diagnostics, ...result.diagnostics]),
  };
}

/**
 * One summary with each inline link resolved to the command that opens its
 * doc, against the provider that wrote it. A link that names no doc prints as
 * written; doctor names it where it checks the doc's own fields.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {string} providerId
 * @param {string} summary
 * @returns {Promise<string>}
 */
async function linkSummary(catalog, tree, providerId, summary) {
  if (!summary.includes('{@link')) return renderTokens(summary);
  let provider;
  try {
    provider = normalizeProviderId(providerId);
  } catch {
    return summary;
  }
  const find = docFinderOver(catalog, tree, provider, false);
  const linked = await linkFields({summary}, async target => {
    const found = await find(target);
    return 'problem' in found ? found : found.link;
  });
  return linked.doc.summary;
}

/** @type {WeakMap<DocsTree, Map<string, TreeNode>>} */
const identitiesByTree = new WeakMap();

/** @param {string} provider @param {string} kind @param {string} name */
function identityKey(provider, kind, name) {
  return `${provider}\u0000${kind}\u0000${kind === 'generic' ? name.toLowerCase() : name}`;
}

/**
 * Every tree node with an identity, by provider id, kind, and name.
 * @param {DocsTree} tree
 */
function identitiesOf(tree) {
  let index = identitiesByTree.get(tree);
  if (!index) {
    index = new Map();
    for (const node of tree.nodes.values()) {
      if (node.id == null) continue;
      let provider = node.providerId;
      try {
        provider = normalizeProviderId(node.providerId);
      } catch {
        // Kept as given; a link names it the same way.
      }
      index.set(identityKey(provider, node.kind, node.name), node);
    }
    identitiesByTree.set(tree, index);
  }
  return index;
}

/**
 * The CLI's authoring docs, by kind and name. The field reference under
 * `astryx docs authoring` reads each as one section keyed by its name, so a
 * link to one opens that section. Loaded again after one of them changes,
 * like the CLI's tree files.
 */
const authoringDocs = reusedWhileUnchanged(() =>
  loadAuthoringSelfDocs().then(
    ({loaded}) =>
      new Map(loaded.map(({doc}) => [`${doc.type}\u0000${doc.name}`, doc])),
  ),
);

/**
 * The CLI authoring doc a link names. The `authoring` namespace is the CLI's
 * own, so no integration can take its route.
 * @param {string} kind
 * @param {string} name
 * @returns {Promise<any | null>}
 */
async function authoringDoc(kind, name) {
  return (await authoringDocs()).get(`${kind}\u0000${name}`) ?? null;
}

/**
 * A doc a link found: what a read shows of the link, and the typed doc behind
 * it when a reference block can include it.
 * @typedef {object} FoundDoc
 * @property {import('../../foundation/doc-compiler/links.mjs').DocLink} link
 * @property {string} kind the doc's kind
 * @property {{doc: any, providerId: string, tree: boolean} | null} typed a
 *   schema, command, function, or enum doc: a leaf of the docs tree (`tree`),
 *   or a section of `astryx docs authoring`; null for any other kind
 */

/**
 * How a doc's links find their targets (spec:AST-047 FR9): a doc in the
 * project's docs tree by its identity, a CLI authoring doc (a section of
 * `astryx docs authoring`), or a flat topic by its provider and name. A
 * target that matches none is a problem, never a guess.
 * @param {DocsCatalog} catalog
 * @param {string} fromProvider the provider id of the doc the links sit in
 * @returns {Promise<(target: string) => Promise<FoundDoc | {problem: string}>>}
 */
async function docFinder(catalog, fromProvider) {
  return docFinderOver(catalog, await projectTree(catalog), fromProvider);
}

/**
 * {@link docFinder} over a tree already built, so building the tree can
 * resolve the links in its own summaries.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {string} fromProvider
 * @param {boolean} [summaries] resolve the links in a found flat topic's
 *   summary; off while a summary is itself being resolved, so two summaries
 *   that link each other cannot loop
 * @returns {(target: string) => Promise<FoundDoc | {problem: string}>}
 */
function docFinderOver(catalog, tree, fromProvider, summaries = true) {
  const identities = identitiesOf(tree);
  return async target => {
    const parsed = parseLinkTarget(target);
    if ('error' in parsed)
      return {
        problem: bareLinkHint(
          parsed.error,
          target,
          catalog,
          identities,
          fromProvider,
        ),
      };
    let provider;
    try {
      provider = normalizeProviderId(parsed.provider ?? fromProvider);
    } catch {
      return {
        problem: `"${target}" names "${parsed.provider}", which is not a provider id: an npm package name, or the \`providerId\` its manifest declares`,
      };
    }
    const node = identities.get(
      identityKey(provider, parsed.kind, parsed.name),
    );
    if (node) {
      return {
        link: {
          target,
          id: /** @type {string} */ (node.id),
          route: node.route,
          title: node.title,
          summary: node.summary,
          command: `astryx docs ${node.route}`,
        },
        kind: node.kind,
        typed: node.ref?.selfDoc
          ? {doc: node.ref.selfDoc, providerId: node.providerId, tree: true}
          : null,
      };
    }
    const authored =
      provider === CLI_PROVIDER_ID
        ? await authoringDoc(parsed.kind, parsed.name)
        : null;
    if (authored) {
      // An experimental schema is a section of its experimental route, not
      // of the field reference (spec:AST-084 FR0).
      const experimental = isExperimentalSelfDoc(authored);
      const route = experimental
        ? EXPERIMENTAL_AUTHORING_ROUTE
        : AUTHORING_REFERENCE_ROUTE;
      return {
        link: {
          target,
          id: createDocId(provider, authored.type, authored.name),
          route,
          title: authored.displayName ?? authored.name,
          summary: renderTokens(authored.description ?? ''),
          command: `astryx docs ${experimental ? route : 'authoring'} ${authored.name}`,
        },
        kind: parsed.kind,
        typed: {doc: authored, providerId: CLI_PROVIDER_ID, tree: false},
      };
    }
    if (parsed.kind === 'generic') {
      const entry = catalog.resolve(parsed.name);
      if (
        entry &&
        !entry.tree &&
        (providerOf(entry) === provider ||
          catalog.aliasesOf(entry).includes(parsed.name.toLowerCase()) ||
          entry.replaces?.toLowerCase() === parsed.name.toLowerCase())
      ) {
        let title = entry.title ?? entry.name;
        let summary = entry.description ?? '';
        try {
          const raw = await lowerRawTopic(catalog, entry);
          title = raw.doc.title ?? title;
          summary = raw.doc.description ?? summary;
          if (summaries) {
            summary = await linkSummary(
              catalog,
              tree,
              providerOf(entry),
              summary,
            );
          }
        } catch {
          // The topic budget check reports a topic that does not load; the
          // link still opens it.
        }
        return {
          link: {
            target,
            id: createDocId(provider, 'generic', parsed.name),
            route: entry.name,
            title,
            summary,
            command: `astryx docs ${entry.name}`,
          },
          kind: 'generic',
          typed: null,
        };
      }
    }
    if (CONTRIBUTED_KINDS.has(parsed.kind)) {
      const link = await contributedDocLink(
        catalog,
        provider,
        parsed.kind,
        parsed.name,
      );
      if (link) {
        // The summary is the target doc's own text, so its links resolve
        // against the target's provider, never the linking doc's: a Core
        // component's against the CLI's docs, like its other fields.
        // contributedDocLink returns the authored text; it renders once here.
        if (summaries && link.summary.includes('{@')) {
          link.summary = await linkSummary(
            catalog,
            tree,
            provider === CORE_COMPONENT_PROVIDER ? CLI_PROVIDER_ID : provider,
            link.summary,
          );
        } else {
          link.summary = renderTokens(link.summary);
        }
        return {link: {target, ...link}, kind: parsed.kind, typed: null};
      }
    }
    const searchType =
      parsed.kind === 'component'
        ? 'component'
        : parsed.kind === 'page' || parsed.kind === 'block'
          ? 'template'
          : 'doc';
    return {
      problem: `"${target}" names no doc. Find it with \`astryx search ${parsed.name} --type ${searchType}\`, then name it as \`[<provider>:]<kind>:<name>\`.`,
    };
  };
}

/**
 * What a link written as a bare name (`{@link deploying}`) should say
 * instead: the exact target to write when a topic or tree doc has that
 * name, or that none does.
 * @param {string} error the parse error
 * @param {string} target the target as written
 * @param {DocsCatalog} catalog
 * @param {Map<string, any>} identities
 * @param {string} fromProvider
 * @returns {string}
 */
function bareLinkHint(error, target, catalog, identities, fromProvider) {
  const name = typeof target === 'string' ? target.trim() : '';
  if (!name || name.includes(':') || /\s/.test(name)) return error;
  /** @param {string} provider */
  const normal = provider => {
    try {
      return normalizeProviderId(provider);
    } catch {
      return provider;
    }
  };
  const from = normal(fromProvider);
  /** @param {string} provider @param {string} kind @param {string} named */
  const written = (provider, kind, named) =>
    `{@link ${normal(provider) === from ? '' : `${provider}:`}${kind}:${named}}`;
  const entry = catalog.resolve(name);
  if (entry) {
    return `${error}. "${name}" is a topic: write \`${written(entry.providerId ?? entry.package, 'generic', entry.name)}\`.`;
  }
  const node = [...identities.values()].find(
    each => String(each.name).toLowerCase() === name.toLowerCase(),
  );
  if (node) {
    return `${error}. "${name}" is a ${node.kind === 'generic' ? 'topic' : `${node.kind} doc`}: write \`${written(node.providerId, node.kind, node.name)}\`.`;
  }
  return `${error}, and no topic is named "${name}". Link a doc that exists, as \`{@link generic:<topic>}\` (\`astryx docs\` lists the topics), or remove the link.`;
}

/** The provider Core's components and templates belong to. */
const CORE_COMPONENT_PROVIDER = (() => {
  try {
    return normalizeProviderId(CORE_PACKAGE);
  } catch {
    return CORE_PACKAGE;
  }
})();

/** The doc kinds no docs tree holds: components and templates. */
const CONTRIBUTED_KINDS = new Set(['component', 'page', 'block']);

/**
 * The link to a component, page, or block doc (spec:AST-047 FR9). No docs tree
 * holds these, so a link finds them among the component and template records
 * the catalog carries, the ones `astryx component` and `astryx template` open,
 * and reads as that command. A component is named by its export name, a
 * template by its id; anything but Core's names its package.
 * @param {DocsCatalog} catalog
 * @param {string} provider normalized provider id
 * @param {string} kind `component`, `page`, or `block`
 * @param {string} name
 * @returns {Promise<Omit<import('../../foundation/doc-compiler/links.mjs').DocLink, 'target'> | null>}
 */
async function contributedDocLink(catalog, provider, kind, name) {
  const contributions = await catalog.contributions();
  if (!contributions) return null;
  const sameProvider = (/** @type {string} */ providerId) => {
    try {
      return normalizeProviderId(providerId) === provider;
    } catch {
      return false;
    }
  };
  if (kind === 'component') {
    const record = contributions.components.find(
      component =>
        component.name === name && sameProvider(component.providerId),
    );
    if (!record) return null;
    /** @type {any} */
    let doc = null;
    try {
      doc = record.docPath ? await loadComponentDoc(record.docPath) : null;
    } catch {
      // The component checks report a doc that does not load; the link
      // still opens the component.
    }
    const entry =
      doc?.name === name
        ? doc
        : doc?.components?.find(
            (/** @type {any} */ each) => each.name === name,
          );
    // Bare, Core's name opens Core's component unless another package ships
    // the same name or replaces it (spec:AST-035 FR11); then the link selects
    // Core, as it always selects any other package.
    const selectPackage =
      record.package !== CORE_PACKAGE ||
      contributions.components.some(
        other =>
          other.package !== CORE_PACKAGE &&
          (other.name === name || other.replaces === name),
      );
    return {
      id: createDocId(provider, 'component', name),
      route: null,
      title: entry?.displayName ?? name,
      summary: entry?.description ?? doc?.description ?? '',
      command: `astryx component ${name}${selectPackage ? ` --package ${record.package}` : ''}`,
    };
  }
  const template = contributions.templates.find(
    each =>
      each.type === kind && each.id === name && sameProvider(each.providerId),
  );
  if (!template) return null;
  // The same for a Core template: another package's template of its kind
  // with its id, or one that replaces it, takes the bare id.
  const selectPackage =
    template.package !== CORE_PACKAGE ||
    contributions.templates.some(
      other =>
        other.package !== CORE_PACKAGE &&
        other.type === template.type &&
        (other.id === name || other.replaces === name),
    );
  return {
    id: createDocId(provider, template.type, name),
    route: null,
    title: template.displayName ?? template.name,
    summary: template.description ?? '',
    command: `astryx template ${name} --type ${template.type}${selectPackage ? ` --package ${template.package}` : ''}`,
  };
}

/**
 * The component and template docs one integration package's links can name:
 * Core's and its own, as `doctor integration docs` checks it before any app
 * configures it.
 * @param {any} integration a loaded integration: its name, provider id, roots,
 *   and package directory
 * @returns {Promise<import('../../foundation/discovery/docs-discovery.mjs').LinkableContributions>}
 */
async function packageContributions(integration) {
  const own = integration.providerId ?? integration.name;
  /** @type {import('../../foundation/discovery/docs-discovery.mjs').LinkableComponent[]} */
  const components = [];
  const coreDir = findCoreDir(integration.__packageDir ?? process.cwd());
  if (coreDir) {
    try {
      for (const record of discoverOwnedComponents(coreDir, [])) {
        components.push({
          providerId: CORE_PACKAGE,
          package: CORE_PACKAGE,
          name: record.name,
          docPath: record.docPath,
        });
      }
    } catch {
      // The components check reports a Core it cannot read.
    }
  }
  if (integration.components) {
    try {
      const {components: records} =
        await discoverValidIntegrationComponents(integration);
      for (const record of records) {
        components.push({
          providerId: own,
          package: integration.name,
          name: record.name,
          docPath: record.docPath,
          // Declared: this package alone cannot tell whether an app applies
          // it, so a link to the Core name it names selects Core.
          ...(typeof record.replaces === 'string'
            ? {replaces: record.replaces}
            : {}),
        });
      }
    } catch {
      // `validate` reports components that do not load.
    }
  }
  /** @type {import('../../foundation/discovery/docs-discovery.mjs').LinkableTemplate[]} */
  const templates = [];
  /** @param {any} template @param {string} providerId @param {string} pkg */
  const addTemplate = (template, providerId, pkg) => {
    if (template.type !== 'page' && template.type !== 'block') return;
    templates.push({
      providerId,
      package: pkg,
      type: template.type,
      id: template.dirName,
      name: template.name,
      ...(template.displayName == null
        ? {}
        : {displayName: template.displayName}),
      ...(template.description == null
        ? {}
        : {description: template.description}),
      ...(typeof template.replaces === 'string'
        ? {replaces: template.replaces}
        : {}),
    });
  };
  try {
    for (const template of await discoverCoreTemplates()) {
      addTemplate(template, CORE_PACKAGE, CORE_PACKAGE);
    }
  } catch {
    // Core templates that do not load leave nothing to link to.
  }
  if (integration.templates) {
    try {
      const {templates: records} =
        await discoverIntegrationTemplatesForOne(integration);
      for (const template of records)
        addTemplate(template, own, integration.name);
    } catch {
      // `validate` reports templates that do not load.
    }
  }
  return {components, templates};
}

/**
 * How a doc's links find their targets (spec:AST-047 FR9), as
 * {@link docFinder} finds them: each resolves to the link a read shows.
 * @param {DocsCatalog} catalog
 * @param {string} fromProvider the provider id of the doc the links sit in
 * @returns {Promise<LinkResolver>}
 */
export async function linkResolver(catalog, fromProvider) {
  const find = await docFinder(catalog, fromProvider);
  return async target => {
    const found = await find(target);
    return 'problem' in found ? found : found.link;
  };
}

/** How a problem names a doc kind that a reference block cannot include. */
const KIND_NAMES = /** @type {Record<string, string>} */ ({
  generic: 'topic',
  namespace: 'namespace',
});

/**
 * How a topic's reference blocks include the docs they name (spec:AST-047
 * FR9): a schema, command, function, or enum doc as `astryx docs` prints
 * it, narrowed by the block's projection and presentation, with the included
 * doc's own links resolved against its own provider. Any other doc shows its
 * title and summary. Each part a block names that it cannot include is a
 * problem, and a read marks where it is missing; a target that names no doc
 * is the resolver's problem.
 * @param {DocsCatalog} catalog
 * @param {string} fromProvider the provider id of the doc the blocks sit in
 * @returns {Promise<DocIncluder>}
 */
async function docIncluder(catalog, fromProvider) {
  const find = await docFinder(catalog, fromProvider);
  const tree = await projectTree(catalog);
  return async block => {
    const found = await find(block.target);
    if ('problem' in found) return {content: [], problems: []};
    return includedContent(catalog, tree, block, found);
  };
}

/**
 * What one reference block includes of the doc it found.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {any} block
 * @param {FoundDoc} found
 * @returns {Promise<{content: any[], problems: string[]}>}
 */
async function includedContent(catalog, tree, block, found) {
  /** @type {string[]} */
  const problems = [];
  const {fields, sections} = block.projection ?? {};
  const presentation = block.presentation ?? 'full';
  if (sections != null) {
    problems.push(
      'projection.sections: a reference block does not include topic sections; reference a schema, command, function, or enum doc, and name the fields of a schema with projection.fields',
    );
  }
  const typed = found.typed;
  if (typed == null) {
    // A reference shows any other doc only by its title and summary.
    if (fields != null || (block.presentation ?? 'summary') !== 'summary') {
      problems.push(
        `"${block.target}" is a ${KIND_NAMES[found.kind] ?? `${found.kind} doc`}, which a reference block shows only by its title and summary; remove the projection and the presentation, or reference a schema, command, function, or enum doc`,
      );
    }
    return {content: [], problems};
  }
  if (presentation === 'summary') {
    if (fields != null) {
      problems.push(
        "projection.fields: a summary includes no fields; remove projection.fields or presentation: 'summary'",
      );
    }
    return {content: [], problems};
  }
  /** @type {any[]} */
  let content;
  if (fields != null && typed.doc.type === 'schema') {
    /** @type {Map<string, any>} */
    const byName = new Map(
      (typed.doc.fields ?? []).map((/** @type {any} */ field) => [
        field.name,
        field,
      ]),
    );
    const selected = [];
    /** @type {any[]} */
    const missing = [];
    for (const name of fields) {
      const field = byName.get(name);
      if (field) {
        selected.push(field);
        continue;
      }
      problems.push(
        `projection.fields: "${name}" is not a field of ${found.link.title} (${block.target}). Its fields: ${[...byName.keys()].join(', ')}`,
      );
      missing.push({
        type: 'prose',
        text: `[reference: field "${name}" not found in "${block.target}"]`,
      });
    }
    const table = schemaFieldTable(selected);
    content = [...(table ? [table] : []), ...missing];
  } else {
    if (fields != null) {
      problems.push(
        `projection.fields: names the fields of a schema doc, and "${block.target}" is a ${typed.doc.type} doc; remove it to include the whole doc`,
      );
    }
    content = typed.tree
      ? cliDocSection(typed.doc, typedDocIndex(tree)).content
      : selfDocSection(typed.doc).content;
  }
  if (presentation === 'compact') {
    content = content.filter(each => each?.type !== 'code');
  }
  // The included doc's own links resolve against its own provider. A link in
  // it that names no doc is that doc's problem, reported where it is written.
  const linked = await linkBlocks(
    content,
    await linkResolver(catalog, typed.providerId),
  );
  return {content: linked.content, problems};
}

/**
 * Every link in the project's docs that names no doc: in each topic, each
 * guide the tree places, and each typed doc.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {{owner?: string, references?: boolean}} [options] `owner`: only the
 *   docs this package owns. `references`: instead of the links, each reference
 *   block that cannot include what it names; a reader loses that content,
 *   where a link that names no doc still prints as written
 * @returns {Promise<string[]>}
 */
export async function docsLinkProblems(
  catalog,
  tree,
  {owner, references = false} = {},
) {
  /** @type {string[]} */
  const problems = [];
  /** @param {string} where @param {LinkProblem[]} found */
  const note = (where, found) => {
    for (const problem of found) {
      if ((problem.include === true) !== references) continue;
      problems.push(
        `${where}${problem.section ? ` \u00a7 ${problem.section}` : ''}${problem.field ? ` (${problem.field})` : ''}: ${problem.message}`,
      );
    }
  };
  for (const entry of catalog.entries()) {
    // A package owns a topic it wrote, and the sections it adds to another
    // package's topic.
    if (
      owner != null &&
      entry.package !== owner &&
      !entry.extensions.some(extension => extension.package === owner)
    ) {
      continue;
    }
    try {
      note(entry.name, await topicLinkProblems(catalog, entry));
    } catch {
      // The topic budget check reports a topic that does not load.
    }
  }
  for (const node of tree.nodes.values()) {
    // A package owns a guide it placed, and a guide it replaces or extends by
    // its route.
    if (
      owner != null &&
      node.provider !== owner &&
      node.guideOverlay?.replacement?.package !== owner &&
      !node.guideOverlay?.extensions.some(each => each.package === owner)
    ) {
      continue;
    }
    if (node.kind === 'generic' && node.ref?.topicFile) {
      try {
        note(node.route, await topicLinkProblems(catalog, guideEntry(node)));
      } catch {
        // As above.
      }
    } else if (node.ref?.selfDoc) {
      note(node.route, (await nodeContent(catalog, tree, node)).problems);
    }
  }
  return problems;
}

/**
 * The catalog one integration package's docs and links read, as doctor checks
 * it before any app configures it: the CLI's topics, Core's and the package's
 * components and templates, and the package's own docs.
 * @param {any} 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[]} | null} discovered
 * @returns {DocsCatalog}
 */
function packageCatalog(integration, discovered) {
  const catalog = DocsCatalog.fromBuiltins();
  catalog.setContributions(() => packageContributions(integration));
  if (discovered) {
    for (const record of discovered.records) catalog.add(record);
    catalog.addTreeInputs({
      namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
      guides: discovered.guides.map(input => ({...input, rank: 1})),
    });
  }
  return catalog;
}

/**
 * What \`astryx doctor integration components\` checks of the links in one
 * integration's own component docs (spec:AST-047 FR9): each link in a
 * description, usage, best practice, or prop's or example's description that
 * names no doc. It prints as written, so each is a warning.
 * @param {any} integration a loaded integration
 * @param {Parameters<typeof packageCatalog>[1]} discovered the package's own
 *   docs, which its components' links may name; null when it ships none
 * @returns {Promise<Array<{severity: 'warning', message: string}>>}
 */
export async function packageComponentLinkProblems(integration, discovered) {
  // A package with no provider id (its manifest's, else its name) links
  // nothing, as on the read path: its text reads as written, so there is
  // nothing to report.
  try {
    normalizeProviderId(integration.providerId ?? integration.name);
  } catch {
    return [];
  }
  const catalog = packageCatalog(integration, discovered);
  return (await componentLinkProblems(catalog, integration.name)).map(
    message => ({severity: /** @type {const} */ ('warning'), message}),
  );
}

/**
 * Each link in a package's own component docs that names no doc. A family doc
 * that documents several components is read once.
 * @param {DocsCatalog} catalog
 * @param {string} owner the package whose component docs are read
 * @returns {Promise<string[]>}
 */
async function componentLinkProblems(catalog, owner) {
  const contributions = await catalog.contributions();
  /** @type {string[]} */
  const problems = [];
  const seen = new Set();
  for (const record of contributions?.components ?? []) {
    if (record.package !== owner || !record.docPath) continue;
    if (seen.has(record.docPath)) continue;
    seen.add(record.docPath);
    /** @type {any} */
    let doc;
    try {
      doc = await loadComponentDoc(record.docPath);
    } catch {
      // The components check reports a doc that does not load.
      continue;
    }
    let provider;
    try {
      provider = componentLinkProvider(record.package, record.providerId);
    } catch {
      // An owner that is not a provider id links nothing (as on the read
      // path); its text reads as written.
      continue;
    }
    const linked = await linkComponentDoc(catalog, provider, doc);
    const name = typeof doc?.name === 'string' ? doc.name : record.name;
    for (const problem of linked.problems) {
      problems.push(
        `component ${name}${problem.field ? ` (${problem.field})` : ''}: ${problem.message}`,
      );
    }
  }
  return problems;
}

/**
 * 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). 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<Array<{severity: 'error' | 'warning', message: string}>>}
 */
export async function packageDocsProblems(integration, discovered) {
  const catalog = packageCatalog(integration, discovered);
  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 => ({
      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;
}

/**
 * The guide the docs tree places at a route, compared without case, or at the
 * route it moved to; null when the route holds no placed guide.
 * @param {DocsTree} tree
 * @param {string} route
 * @returns {TreeNode | null}
 */
function placedGuideAt(tree, route) {
  const node =
    tree.get(route) ?? tree.getFolded(route) ?? movedRoute(route, tree);
  return node?.kind === 'generic' && node.ref?.topicFile ? node : null;
}

/**
 * The routes of every guide the tree places below a namespace, nearest first,
 * in reading order.
 * @param {DocsTree} tree
 * @param {TreeNode} namespace
 * @returns {string[]}
 */
function placedGuidesBelow(tree, namespace) {
  /** @type {string[]} */
  const routes = [];
  /** @type {TreeNode[]} */
  let level = [namespace];
  while (level.length > 0) {
    /** @type {TreeNode[]} */
    const next = [];
    for (const parent of level) {
      for (const slot of parent.slots) {
        for (const route of slot.children) {
          const child = tree.get(route);
          if (!child || child.parent !== parent.route) continue;
          if (child.kind === 'generic' && child.ref?.topicFile) {
            routes.push(child.route);
          }
          if (child.slots.length > 0) next.push(child);
        }
      }
    }
    level = next;
  }
  return routes;
}

/**
 * What one doc that replaces or extends another does, as a package's own
 * check sees it.
 * @typedef {object} DocTarget
 * @property {string} topic the doc's own name
 * @property {'replaces' | 'extends'} relationship
 * @property {string} target the topic name or route it names
 * @property {'topic' | 'guide' | 'namespace' | null} kind what the target
 *   is: a flat topic, a guide the docs tree places, a namespace (which neither
 *   takes), or null when it names nothing
 * @property {string | null} guide for a guide, the route it is placed at now,
 *   which an old route resolves to
 * @property {string[]} guidesBelow for a namespace, the routes of the guides
 *   placed below it, any of which the doc could name instead
 * @property {string | null} owner the package whose topic or guide it is
 * @property {Array<{section: string, field: 'before' | 'after', key: string}>} unplaced
 *   each section whose `before` or `after` names no section of the target, so
 *   it is added at the end instead
 */

/**
 * Each doc in one integration's docs that replaces or extends a topic, or a
 * guide the docs tree places by its route, read against the CLI's docs and the
 * package's own: what it names and whether that exists, and each section an
 * extension places with `before` or `after` that finds no section there.
 * @param {any} 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<DocTarget[]>}
 */
export async function packageDocTargets(integration, discovered) {
  const catalog = packageCatalog(integration, discovered);
  const tree = await projectTree(catalog);
  /** @type {DocTarget[]} */
  const targets = [];
  for (const record of discovered.records) {
    const relationship = record.replaces != null ? 'replaces' : 'extends';
    const target =
      relationship === 'replaces' ? record.replaces : record.extendsTopic;
    if (target == null) continue;
    /** @type {DocTarget['kind']} */
    let kind = null;
    /** @type {string | null} */
    let owner = null;
    /** @type {string | null} */
    let basePath = null;
    /** @type {ReadonlyArray<{path: string}>} every extension of the target, in configured order */
    let extensions = [];
    /** @type {string[]} */
    let guidesBelow = [];
    /** @type {string | null} */
    let guide = null;
    if (isGuideRoute(target)) {
      const node = placedGuideAt(tree, target);
      if (node) {
        kind = 'guide';
        guide = node.route;
        owner = node.provider;
        basePath = node.guideOverlay?.replacement?.path ?? node.ref.topicFile;
        extensions = node.guideOverlay?.extensions ?? [];
      }
    } else {
      // A replacement already holds the topic's place in the catalog, and
      // names the package it took it from.
      const entry = catalog.resolve(target);
      if (entry?.path === record.path) {
        kind = 'topic';
        owner = entry.replacedPackage ?? null;
      } else if (entry) {
        kind = 'topic';
        owner = entry.package;
        basePath = entry.path;
        extensions = entry.extensions;
      }
    }
    if (kind == null) {
      // A namespace holds no sections to take over or merge onto; the guides
      // below it do.
      const node =
        tree.get(target) ?? tree.getFolded(target) ?? movedRoute(target, tree);
      if (node?.kind === 'namespace') {
        kind = 'namespace';
        owner = node.provider;
        guidesBelow = placedGuidesBelow(tree, node);
      }
    }
    /** @type {DocTarget['unplaced']} */
    let unplaced = [];
    if (relationship === 'extends' && basePath != null) {
      // Merge every extension in configured order, as a read does, so a key
      // an earlier extension adds counts as a section of the target.
      let doc = (await loadTopicFile(basePath, null)).doc;
      for (const extension of extensions) {
        if (doc == null) break;
        const file = (await loadTopicFile(extension.path, null)).doc;
        if (file == null) continue;
        const merged = mergeTopicReport(doc, file);
        if (extension.path === record.path) {
          unplaced = merged.unplaced;
          break;
        }
        doc = merged.doc;
      }
    }
    targets.push({
      topic: record.name,
      relationship,
      target,
      kind,
      owner,
      guide,
      guidesBelow,
      unplaced,
    });
  }
  return targets;
}

/**
 * How a token reference finds its target: the topic it names in `catalog`,
 * lowered for the same language.
 * @param {DocsCatalog} catalog
 * @param {string | null} lang
 * @returns {(topic: string) => Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
 */
export function referenceTargets(catalog, lang) {
  return async topic => {
    const target = catalog.resolve(topic);
    if (target) return lowerTopic(catalog, target, lang);
    return namespaceReferenceTarget(catalog, topic, lang);
  };
}

/**
 * A docs-tree namespace as the target of a token reference: every guide placed
 * below it, lowered for `lang` and read in tree order as one topic. A flat
 * topic split into a namespace keeps answering the references its readers
 * wrote, so `{type: 'token-ref', topic: 'tokens', section: 'Color Tokens'}`
 * finds the guide that now holds that table. Null for any other route.
 * @param {DocsCatalog} catalog
 * @param {string} route
 * @param {string | null} lang
 * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
 */
async function namespaceReferenceTarget(catalog, route, lang) {
  const tree = await projectTree(catalog);
  const node = tree.get(route) ?? tree.getFolded(route);
  if (!node || node.kind !== 'namespace' || node.generated) return null;
  /** @type {any[]} */
  const sections = [];
  /** @type {Record<string, string>} */
  const sourceTitles = {};
  /** @param {TreeNode} parent */
  const walk = async parent => {
    for (const slot of parent.slots) {
      for (const childRoute of slot.children) {
        const child = tree.get(childRoute);
        if (!child || child.parent !== parent.route) continue;
        if (child.kind === 'namespace') {
          await walk(child);
        } else if (child.kind === 'generic' && child.ref?.topicFile) {
          const lowered = await lowerTopic(catalog, guideEntry(child), lang);
          sections.push(...lowered.doc.sections);
          for (const [key, title] of Object.entries(lowered.sourceTitles)) {
            sourceTitles[key] ??= title;
          }
        }
      }
    }
  };
  await walk(node);
  if (sections.length === 0) return null;
  return /** @type {any} */ ({
    id: node.route,
    doc: {sections},
    sourceTitles,
  });
}

/**
 * Each reference block in one integration's docs that cannot include what it
 * names (spec:AST-047 FR9): a target that names no doc, a field its schema
 * does not have, or a projection its doc cannot take. A reader would lose
 * that content, so `astryx doctor integration docs` fails on each.
 * @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[]>}
 */
export async function packageReferenceProblems(integration, discovered) {
  const catalog = DocsCatalog.fromBuiltins();
  catalog.setContributions(() => packageContributions(integration));
  for (const record of discovered.records) catalog.add(record);
  catalog.addTreeInputs({
    namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
    guides: discovered.guides.map(input => ({...input, rank: 1})),
  });
  return docsLinkProblems(catalog, await projectTree(catalog), {
    owner: integration.name,
    references: true,
  });
}

/**
 * One topic, compiled for `lang`: lowered, then every token reference linked.
 * @param {DocsCatalog} catalog
 * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
 * @param {string | null} [lang]
 * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
 */
export async function compileTopic(catalog, entry, lang = null) {
  return linkReferenceTopic(
    await lowerTopic(catalog, entry, lang),
    referenceTargets(catalog, lang),
  );
}

/**
 * A guide the docs tree places, as a topic entry the topic readers open by its
 * route. It is never a flat topic: `astryx docs <route>` is its only name.
 * What integrations do to it by its route applies: a replacement is read in
 * its place and names its own package, and each extension's sections merge
 * onto it, each naming the package that wrote it (INV28).
 * @param {import('../../foundation/doc-compiler/tree.mjs').TreeNode} node
 * @returns {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry}
 */
export function guideEntry(node) {
  const base = {
    name: node.route,
    route: node.route,
    package: node.provider,
    providerId: node.providerId,
    path: node.ref.topicFile,
    extensions: [],
    tree: /** @type {const} */ (true),
    parent: node.parent ?? undefined,
  };
  const overlay = node.guideOverlay;
  if (!overlay) return base;
  const replacement = overlay.replacement;
  return {
    ...base,
    ...(replacement
      ? {
          package: replacement.package,
          providerId: replacement.providerId ?? replacement.package,
          path: replacement.path,
          replaces: node.route,
          // The package whose guide it took over: an earlier replacement's,
          // when the guide was already replaced.
          replacedPackage: overlay.replacedPackage ?? node.provider,
        }
      : {}),
    extensions: [...overlay.extensions],
  };
}

/** @type {WeakMap<DocsTree, ReturnType<typeof cliDocIndex>>} */
const typedDocIndexes = new WeakMap();

/**
 * What a typed doc in the docs tree prints: its content, with every link to
 * another doc resolved (spec:AST-047 FR9). A namespace has no content. The
 * CLI's doc modules are discovery, so this lives in the adapter
 * (architecture:cli-surface INV21).
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {TreeNode} node
 * @returns {Promise<{content: any[], problems: LinkProblem[]}>}
 */
export async function nodeContent(catalog, tree, node) {
  if (!node.ref?.selfDoc) return {content: [], problems: []};
  const resolve = await linkResolver(catalog, node.providerId);
  return linkBlocks(
    cliDocSection(node.ref.selfDoc, typedDocIndex(tree)).content,
    resolve,
  );
}

/**
 * The index a typed doc's content reads its cross-links from: every typed doc
 * in the tree. Built once per tree.
 * @param {DocsTree} tree
 * @returns {ReturnType<typeof cliDocIndex>}
 */
function typedDocIndex(tree) {
  let index = typedDocIndexes.get(tree);
  if (!index) {
    index = cliDocIndex(
      [...tree.nodes.values()].flatMap(each =>
        each.ref?.selfDoc ? [each.ref.selfDoc] : [],
      ),
    );
    typedDocIndexes.set(tree, index);
  }
  return index;
}

/**
 * The command that opens the level a topic sits in when the tree cannot say:
 * a guide's parent namespace, or the topic list.
 * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
 * @returns {import('./docs.type.mjs').DocsCommand}
 */
export function topicUp(entry) {
  return entry.tree && entry.parent
    ? `astryx docs ${entry.parent}`
    : 'astryx docs';
}

/**
 * The moves from a node's place in the tree (spec:AST-047 FR2, FR4): up to its
 * parent (the topic list, at the top), and across to the nodes before and
 * after it in its parent's slot.
 * @param {DocsTree} tree
 * @param {TreeNode} node
 * @returns {import('./docs.type.mjs').DocsLinks}
 */
export function placeLinks(tree, node) {
  /** @type {import('./docs.type.mjs').DocsLinks} */
  const links = {
    up: node.parent == null ? 'astryx docs' : `astryx docs ${node.parent}`,
  };
  const parent = node.parent == null ? undefined : tree.get(node.parent);
  // A stable node moves only to stable neighbors, so its links read as they
  // do without experimental features (spec:AST-017 FR27, spec:AST-084 FR0),
  // and an experimental node only to experimental ones, so each next read
  // still names this one as its previous.
  const experimental = isExperimentalTreeNode(tree, node);
  const siblings = (
    parent?.slots.find(slot => slot.children.includes(node.route))?.children ??
    []
  ).filter(route => {
    const sibling = tree.get(route);
    return (
      sibling == null || isExperimentalTreeNode(tree, sibling) === experimental
    );
  });
  const at = siblings.indexOf(node.route);
  if (at > 0) links.previous = `astryx docs ${siblings[at - 1]}`;
  if (at !== -1 && at < siblings.length - 1) {
    links.next = `astryx docs ${siblings[at + 1]}`;
  }
  return links;
}

/**
 * The moves a topic read offers: from its place in the tree, where a guide
 * sits in its namespace and a flat topic in its topic level.
 * @param {DocsCatalog} catalog
 * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
 * @returns {Promise<import('./docs.type.mjs').DocsLinks>}
 */
export async function topicLinks(catalog, entry) {
  const tree = await projectTree(catalog);
  const node = tree.get(entry.tree ? (entry.route ?? entry.name) : entry.name);
  const placed =
    node &&
    (entry.tree ? node.kind === 'generic' : node.ref?.flatTopic === entry.name);
  return placed ? placeLinks(tree, node) : {up: topicUp(entry)};
}

/**
 * What a docs argument names: a topic (a flat one, or a guide the docs tree
 * places), a namespace or typed doc in the tree, or nothing, as nameOwner
 * decides.
 * @param {unknown} topic
 * @param {{cwd?: string}} [options]
 * @param {DocsCatalog} [loaded] internal: a catalog the read already loaded,
 *   so the read and every part of it share one snapshot of the project's docs
 *   (and its memoized lowering) instead of loading the project again for each
 *   part. It is a separate argument, never an option, so no caller of the
 *   public `docs()` can set it
 * @returns {Promise<
 *   | {kind: 'topic', catalog: DocsCatalog, entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry}
 *   | {kind: 'node', catalog: DocsCatalog, tree: import('../../foundation/doc-compiler/tree.mjs').DocsTree, node: import('../../foundation/doc-compiler/tree.mjs').TreeNode}
 *   | {kind: 'unknown', catalog: DocsCatalog}
 * >}
 */
export async function resolveDocsArgument(topic, {cwd} = {}, loaded) {
  const catalog = loaded ?? (await loadDocsCatalog(cwd));
  if (typeof topic !== 'string' || topic === '')
    return {kind: 'unknown', catalog};
  const tree = await projectTree(catalog);
  const owner = nameOwner(tree, catalog, topic);
  if (owner == null) return {kind: 'unknown', catalog};
  if (owner.kind === 'topic')
    return {kind: 'topic', catalog, entry: owner.entry};
  return treeArgument(catalog, tree, owner.node);
}

/**
 * Who answers to a name a reader types (spec:AST-046 FR5, FR11). The tree
 * decides first: the node at that route, compared without case, holds it. A
 * name with no node of its own is a topic's other name (its `replaces`
 * alias), and that topic answers, unless the tree gave the topic's own route
 * to another doc. Reads, the topic list, and search all ask this, so they
 * agree on every name.
 * @param {DocsTree} tree
 * @param {DocsCatalog} catalog
 * @param {string} name
 * @returns {{kind: 'topic', entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} | {kind: 'node', node: TreeNode} | null}
 */
export function nameOwner(tree, catalog, name) {
  const node = tree.get(name) ?? tree.getFolded?.(name);
  if (node != null) {
    if (node.ref?.flatTopic == null) return {kind: 'node', node};
    const entry = catalog.resolve(node.ref.flatTopic);
    return entry == null ? null : {kind: 'topic', entry};
  }
  const entry = catalog.resolve(name);
  if (entry != null) {
    const owner = routeOwner(tree, entry);
    return owner == null ? {kind: 'topic', entry} : {kind: 'node', node: owner};
  }
  return childOwner(tree, name);
}

/**
 * The child a reader names without its namespace, or with a route that leaves
 * out the prefix the child's own name repeats (spec:AST-046 FR5). A namespace
 * whose children repeat its name makes its own routes stutter: `tokens` holds
 * `tokens-color`, so the route is `tokens/tokens-color`, while the namespace
 * listing shows the bare `tokens-color`. Both spellings name one child, so
 * that child answers. Two or more children answering is ambiguous, and the
 * read falls through to the suggestion list, unchanged. An experimental doc
 * never answers to a bare name: its project reaches it only by a marked route
 * (spec:AST-017 FR27).
 * @param {DocsTree} tree
 * @param {string} name
 * @returns {{kind: 'node', node: TreeNode} | null}
 */
function childOwner(tree, name) {
  const wanted = name.toLowerCase();
  const slash = wanted.lastIndexOf('/');
  const parent = slash > 0 ? wanted.slice(0, slash) : null;
  const unstuttered =
    parent == null
      ? null
      : `${parent}/${parent.slice(parent.lastIndexOf('/') + 1)}-${wanted.slice(slash + 1)}`;
  const matches = [...tree.nodes.values()].filter(
    node =>
      node.ref?.flatTopic == null &&
      node.route.includes('/') &&
      // An experimental doc is reachable only by a route its project marked
      // as experimental (spec:AST-017 FR27): a bare name never opens one.
      !isExperimentalTreeNode(tree, node) &&
      (node.name?.toLowerCase() === wanted ||
        (unstuttered != null && node.route.toLowerCase() === unstuttered)),
  );
  return matches.length === 1 ? {kind: 'node', node: matches[0]} : null;
}

/**
 * `stability: 'experimental'` for a node whose doc is marked experimental, or
 * that sits under an experimental namespace (spec:AST-017 FR27), the way help
 * marks an experimental command; nothing for a stable one, so stable entries
 * read as they always have.
 * @param {DocsTree} tree
 * @param {TreeNode} node
 * @returns {{stability?: 'experimental'}}
 */
export function stabilityOf(tree, node) {
  return isExperimentalTreeNode(tree, node) ? {stability: 'experimental'} : {};
}

/**
 * The fields every child carries: what it is, and the route that opens it.
 * Shared, so a child reads the same whether a namespace read or the topic
 * list names it — including the package, which is the integration's for a
 * guide an integration replaced, not the package whose route it took.
 * @param {DocsTree} tree
 * @param {TreeNode} child
 * @returns {import('./docs.type.mjs').DocsNodeChild}
 */
export function childIdentity(tree, child) {
  return {
    route: child.route,
    name: child.route.slice(child.route.lastIndexOf('/') + 1),
    package: child.guideOverlay?.replacement?.package ?? child.provider,
    // A guide an integration's doc took the place of names whose it was.
    ...(child.guideOverlay?.replacement
      ? {
          replaces: child.route,
          replacedPackage: child.guideOverlay.replacedPackage ?? child.provider,
        }
      : {}),
    kind: child.kind,
    title: child.title,
    summary: child.summary,
    ...stabilityOf(tree, child),
  };
}

/**
 * Whether a topic answers to its own name: what the topic list and search
 * offer must open that topic.
 * @param {DocsTree} tree
 * @param {DocsCatalog} catalog
 * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
 * @returns {boolean}
 */
export function holdsOwnName(tree, catalog, entry) {
  const owner = nameOwner(tree, catalog, entry.name);
  return (
    owner?.kind === 'topic' &&
    owner.entry.name === entry.name &&
    owner.entry.package === entry.package
  );
}

/**
 * What a tree node opens as: a guide the tree places reads like a topic; a
 * namespace or a typed doc is a node.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {TreeNode} node
 * @returns {{kind: 'topic', catalog: DocsCatalog, entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} | {kind: 'node', catalog: DocsCatalog, tree: DocsTree, node: TreeNode}}
 */
function treeArgument(catalog, tree, node) {
  if (node.kind === 'generic') {
    return {kind: 'topic', catalog, entry: guideEntry(node)};
  }
  return {kind: 'node', catalog, tree, node};
}

/**
 * The doc that took a flat topic's route in the docs tree, when it is not
 * that topic (spec:AST-046 FR11): the CLI keeps its routes, such as `cli`
 * and `guides`, and a namespace keeps its route over a topic of the same
 * name. Null when the topic owns its route, or the tree has no node there.
 * @param {DocsTree} tree
 * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
 * @returns {TreeNode | null}
 */
export function routeOwner(tree, entry) {
  const node = tree.get(entry.name) ?? tree.getFolded?.(entry.name);
  if (node == null) return null;
  return node.ref?.flatTopic === entry.name && node.provider === entry.package
    ? null
    : node;
}

/**
 * Routes that moved, old prefix first: the integration guides moved from
 * `cli/integrations` (and, before that, the `cli-integrations` topic) into
 * `authoring`, the one home for integration authors.
 * Only the not-found error reads this, to name where a doc went; an old route
 * opens nothing.
 */
const MOVED_ROUTES = [
  ['cli/integrations', 'authoring'],
  ['cli-integrations', 'authoring'],
];

/**
 * The node an old route moved to, or null.
 * @param {unknown} topic
 * @param {DocsTree} tree
 * @returns {TreeNode | null}
 */
function movedRoute(topic, tree) {
  if (typeof topic !== 'string') return null;
  const wanted = topic.toLowerCase();
  for (const [from, to] of MOVED_ROUTES) {
    if (wanted !== from && !wanted.startsWith(`${from}/`)) continue;
    const node = tree.getFolded(`${to}${wanted.slice(from.length)}`);
    if (node) return node;
  }
  return null;
}

/**
 * The error for a docs argument that names nothing. For a route, it suggests
 * every child of the deepest namespace the route reaches, closest first.
 * Otherwise it suggests the docs the argument names in another spelling, or
 * failing that the topics and top-level namespaces, closest first and cut
 * where the matches get weaker (every one of them when none shares a word
 * with the argument).
 * @param {unknown} topic
 * @param {DocsCatalog} catalog
 * @returns {Promise<AstryxError>}
 */
export async function unknownTopicError(topic, catalog) {
  const tree = await projectTree(catalog);
  /** @type {Array<{name: string, reason: string}>} */
  let suggestions = [];
  // Route children stay whole (spec:AST-046); only the other lists are cut.
  let routeChildren = false;
  if (typeof topic === 'string' && topic.includes('/')) {
    const parts = topic.split('/');
    for (
      let depth = parts.length - 1;
      depth > 0 && suggestions.length === 0;
      depth--
    ) {
      const near = tree.get(parts.slice(0, depth).join('/'));
      if (near) {
        routeChildren = true;
        suggestions = near.slots.flatMap(slot =>
          slot.children.map(route => ({
            name: route,
            reason: tree.get(route)?.summary ?? '',
          })),
        );
      }
    }
  }
  if (suggestions.length === 0 && typeof topic === 'string') {
    // The docs whose own name it is (`doctor` is cli/commands/doctor), or whose
    // route it spells with hyphens (`cli-host-entry` is cli/host-entry).
    const wanted = topic.toLowerCase();
    suggestions = [...tree.nodes.values()]
      .filter(
        node =>
          !node.ref?.flatTopic &&
          (node.name.toLowerCase() === wanted ||
            node.route.replaceAll('/', '-').toLowerCase() === wanted),
      )
      .map(node => ({name: node.route, reason: node.summary}));
  }
  if (suggestions.length === 0) {
    suggestions = [
      ...tree
        .roots()
        .map(root => ({name: root.route, reason: 'docs namespace'})),
      ...catalog.names().map(name => ({name, reason: 'available topic'})),
    ];
  }
  if (typeof topic === 'string') {
    suggestions = orderRouteSuggestions(topic, suggestions, {
      closest: !routeChildren,
    });
  }
  // A route that moved names where it went, ahead of the usual suggestions
  // (spec:AST-046 FR9, FR6).
  const moved = movedRoute(topic, tree);
  if (moved) {
    return new AstryxError(
      `Unknown topic "${String(topic)}". It moved to "${moved.route}"${notLoaded(catalog)}`,
      [
        {name: moved.route, reason: moved.summary},
        ...suggestions.filter(entry => entry.name !== moved.route),
      ],
      ERROR_CODES.ERR_UNKNOWN_TOPIC,
    );
  }
  return new AstryxError(
    `Unknown topic "${String(topic)}"${notLoaded(catalog)}`,
    suggestions,
    ERROR_CODES.ERR_UNKNOWN_TOPIC,
  );
}

/**
 * A sentence naming the packages whose docs did not load, or nothing: a doc
 * that fails to load withdraws its package's docs, so a reader who cannot
 * find one learns where to look.
 * @param {DocsCatalog} catalog
 * @returns {string}
 */
export function notLoaded(catalog) {
  const packages = [...new Set(catalog.issues.map(issue => issue.package))];
  if (packages.length === 0) return '';
  return `. The docs of ${packages.join(', ')} did not load; run \`${formatCliCommand('doctor integration docs')}\` in that package to see why.`;
}

/**
 * Resolve a topic (a flat one, or a guide the docs tree places by its route)
 * and lower it for the topic readers.
 * @param {unknown} topic
 * @param {{lang?: string | null, zh?: boolean, dense?: boolean, cwd?: string}} [options]
 * @param {DocsCatalog} [loaded] internal, as {@link resolveDocsArgument}
 */
export async function resolveTopicDocs(topic, options = {}, loaded) {
  const {lang = null, zh = false, dense = false, cwd} = options;
  const effectiveLang = lang || (dense ? 'dense' : zh ? 'zh' : null);
  // A public API caller could pass a non-string topic; it lands on the same
  // stable code as an unknown name rather than a raw TypeError.
  const found = await resolveDocsArgument(topic, {cwd}, loaded);
  if (found.kind !== 'topic') {
    throw found.kind === 'node'
      ? new AstryxError(
          `"${found.node.route}" is a ${found.node.kind === 'namespace' ? 'namespace' : `${found.node.kind} doc`} in the docs tree, not a topic. Read it with \`${formatCliCommand(`docs ${found.node.route}`)}\`.`,
          undefined,
          ERROR_CODES.ERR_UNKNOWN_TOPIC,
        )
      : await unknownTopicError(topic, found.catalog);
  }
  const {catalog, entry} = found;
  const node = await lowerTopic(catalog, entry, effectiveLang);
  return {catalog, node, lang: effectiveLang, entry};
}

/**
 * Each doc one integration package ships, checked against the published
 * authoring type for its kind with the project's own TypeScript (spec:AST-039
 * FR13). Without TypeScript the report says nothing was checked.
 * @param {any} integration a loaded integration
 * @param {string} cwd
 * @returns {Promise<import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}>}
 */
export async function integrationDocTypes(integration, cwd) {
  const packageDir = /** @type {{__packageDir?: string}} */ (integration)
    .__packageDir;
  const {files, unread, fixtures} = await integrationDocFiles(integration);
  const checked = await checkDocTypes(files, {
    packageDir: packageDir ?? cwd,
    resolveFrom: [cwd, packageDir],
  });
  // Test fixtures no reader serves don't ship as docs: only counted.
  const report =
    checked.status === 'checked' && fixtures > 0
      ? {...checked, fixtures}
      : checked;
  if (report.status !== 'checked' || unread.length === 0) return report;
  // A root its reader cannot read serves no doc; say so rather than skip it.
  const rel = (/** @type {string} */ file) =>
    path
      .relative(packageDir ?? cwd, file)
      .split(path.sep)
      .join('/') || '.';
  return {
    ...report,
    unchecked: [
      ...report.unchecked,
      ...unread.map(entry => ({doc: rel(entry.path), reason: entry.reason})),
    ].sort((a, b) => a.doc.localeCompare(b.doc)),
  };
}