Skip to content

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

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

/**
 * @file Reference-doc (topic) discovery — the CLI's own topics plus the ones
 * configured integrations contribute, resolved into one catalog.
 *
 * @input packages/cli/assets/docs/{topic}.doc.mjs (built in), and each loaded
 *   integration's resolved `docs` root ({topic}.doc.{ts,mjs,js}).
 * @output A {@link DocsCatalog}: every topic the project can read, keyed by
 *   name, carrying its owner package, its file, and any extension overlays —
 *   plus the alias a renamed replacement leaves behind.
 * @position foundation/discovery — the single seam every docs surface reads
 *   (api/docs, api/search, and the agent-docs block), so a topic contributed
 *   once shows up in all of them.
 *
 * An integration contributes a topic the way it contributes a component: a
 * root in its manifest, a file per artifact. What a doc says about its
 * relationship to an existing topic is authored on the doc itself, not in a
 * second registry that has to be kept in step with it:
 *
 *   (neither)         add a topic under its own name
 *   replaces: 'x'     take over topic x — core's, or another integration's
 *   extends:  'x'     merge onto topic x, section by section
 *
 * A topic whose name collides with an existing one and declares neither is an
 * `invalid_doc` issue rather than silent shadowing. Shadowing by name would
 * make a core rename swallow an integration's guide (or the reverse) with no
 * diagnostic anywhere, which is the failure mode integration discovery already
 * refuses for components provided by two packages.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {CLI_ROOT} from '../fs/paths.mjs';
import {listDir, listDirEntries} from '../fs/listing-cache.mjs';
import {importDocModule} from '../doc-compiler/import.mjs';
import {CLI_PROVIDER_ID} from '../identity/providers.mjs';
import {parseReadableDoc} from '../doc-compiler/parse-readable.mjs';
import {
  sectionKey,
  sectionKeyErrors,
  sourceTitle,
  withSourceTitle,
} from './docs-section-key.mjs';

export {withSourceTitle};

/** Where the CLI's own topics live. */
const BUILTIN_DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');

/**
 * Owner package recorded for the built-in topics. They ship inside the CLI
 * (assets/docs), not in @astryxdesign/core, so this is the CLI's own name —
 * unlike component discovery, whose built-ins belong to core.
 */
export const BUILTIN_DOCS_PACKAGE = CLI_PROVIDER_ID;

/**
 * A built-in topic file: `{topic}.doc.mjs`. Anchored at both ends so a
 * localization overlay (`{topic}.doc.zh.mjs`) is not read as a topic of its
 * own — it is loaded by the topic it overlays.
 */
const BUILTIN_TOPIC_FILE_RE = /^([\w-]+)\.doc\.mjs$/;

/** Conventional doc-file suffixes for an integration's topics. */
const INTEGRATION_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];

/** A topic name is a CLI argument and a URL segment; keep it to both. */
const TOPIC_NAME_RE = /^[\w-]+$/;

/**
 * Whether a `replaces` or `extends` names a route of the docs tree rather than
 * a flat topic: a topic name never holds a `/`, and a guide the tree places is
 * always read by a route that does.
 * @param {unknown} target
 * @returns {target is string}
 */
export function isGuideRoute(target) {
  return typeof target === 'string' && target.includes('/');
}

/**
 * What the integrations do to one guide the docs tree places, in configured
 * order: a replacement, and the extensions merged onto whatever is there.
 * @typedef {object} GuideOverlay
 * @property {DocsTopicRecord | null} replacement the doc readers get at the
 *   route instead of the guide; the last package configured wins
 * @property {Array<{package: string, path: string, providerId?: string}>} extensions
 *   extensions authored after the replacement, if any, in configured order
 * @property {string} [replacedPackage] the package of the replacement this one
 *   took over from, when the guide was replaced twice
 */

/**
 * @typedef {object} DocsTopicRecord A doc file discovered under a docs root.
 * @property {string} name
 * @property {string} package owner package
 * @property {string} [providerId] the owner's ProviderId, when it differs from
 *   the package name
 * @property {string} path absolute path to the doc file
 * @property {string} [title]
 * @property {string} [description]
 * @property {string|null} [category]
 * @property {string} [replaces] topic this doc takes the place of
 * @property {string} [extendsTopic] topic this doc merges onto (`extends`)
 */

/**
 * @typedef {object} DocsTopicEntry A resolved topic in the catalog.
 * @property {string} name
 * @property {string} package owner package
 * @property {string} [providerId] the owner's ProviderId; the package name when
 *   absent. Links in the topic resolve against it.
 * @property {string} path absolute path to the doc file
 * @property {string} [title]
 * @property {string} [description]
 * @property {string|null} [category]
 * @property {string} [replaces] the topic this one took the place of
 * @property {string} [replacedPackage] the package whose topic or guide this
 *   one took the place of
 * @property {Array<{package: string, path: string, providerId?: string}>} extensions
 *   overlays to merge onto the base doc, in the order their integrations were
 *   configured; each section an extension adds resolves its links against the
 *   extension's provider id (its package name when absent)
 * @property {string} [parent] the route of the namespace a tree guide sits in
 * @property {string} [route] a tree guide's route
 * @property {boolean} [tree] a guide that only the docs tree reads, by its
 *   route; never a flat topic
 */

/**
 * Discover the CLI's own topics.
 * @returns {Record<string, string>} topic name → absolute doc path
 */
export function discoverBuiltinTopics() {
  /** @type {Record<string, string>} */
  const topics = Object.create(null);
  if (!fs.existsSync(BUILTIN_DOCS_DIR)) return topics;
  for (const file of listDir(BUILTIN_DOCS_DIR)) {
    const match = file.match(BUILTIN_TOPIC_FILE_RE);
    if (match) topics[match[1]] = path.join(BUILTIN_DOCS_DIR, file);
  }
  return topics;
}

/**
 * The CLI's own guide files: every flat topic and every doc in its docs tree,
 * without the dense, translated, and draft variants.
 *
 * @returns {string[]}
 */
export function builtinGuideFiles() {
  const files = Object.values(discoverBuiltinTopics());
  const tree = path.join(BUILTIN_DOCS_DIR, 'tree');
  if (fs.existsSync(tree)) {
    for (const file of listDir(tree).sort()) {
      if (BUILTIN_TOPIC_FILE_RE.test(file)) files.push(path.join(tree, file));
    }
  }
  return files;
}

/**
 * Load a topic doc from disk. A `.ts` doc is loaded through jiti, the rest
 * natively; both the historical `export const docs` and the stamped
 * `export default` forms are accepted, because core authors the first and the
 * integration guide documents the second.
 *
 * @param {string} file absolute path to a doc file
 * @returns {Promise<unknown>} the authored doc value
 */
export async function loadTopicModule(file) {
  const mod = await importDocModule(file);
  const doc = mod?.docs ?? mod?.default;
  if (doc == null) {
    throw new Error(
      `${path.basename(file)} exports no doc. A topic exports \`docs\` (or a default export).`,
    );
  }
  return doc;
}

/** Every block kind a section may hold, with the fields each one requires. */
const BLOCK_FIELDS = {
  prose: ['text'],
  heading: ['level', 'text'],
  code: ['lang', 'code'],
  table: ['headers', 'rows'],
  list: ['style', 'items'],
  'token-ref': ['topic', 'section'],
  // A read inlines it as the doc it names includes (spec:AST-047 FR9).
  reference: ['target'],
};

/**
 * Blocks that are valid authoring but require the compiled graph renderer: a
 * namespace doc's `blocks` hold them, a topic section does not.
 */
export const GRAPH_BLOCK_TYPES = new Set(['workflow', 'collection']);

/**
 * Doc fields only the docs tree reads. A flat topic that sets one fails to
 * load; a guide the tree places may set `placement` (spec:AST-046).
 */
export const GRAPH_ONLY_FIELDS = ['placement', 'aliases', 'audience'];

/**
 * Fields a block kind may carry but does not need. Kept per kind rather than
 * globally: only a code block renders a `label`, so allowing it everywhere
 * would wave through the misspellings this check exists to catch.
 */
/** @type {Record<string, string[]>} */
const OPTIONAL_BLOCK_FIELDS = {
  code: ['label'],
  reference: ['projection', 'presentation'],
};

/**
 * Fields whose value has to be one of a set, because the renderer indexes on
 * it. An unlisted heading level renders at the wrong depth and an unlisted
 * list style resolves to undefined, so the value is checked, not just its
 * presence.
 */
const BLOCK_FIELD_VALUES = {
  heading: {level: [3, 4, 5, 6]},
  list: {style: ['ordered', 'unordered', 'do', 'dont']},
  reference: {presentation: ['summary', 'compact', 'full']},
};

/** The parts of a doc a reference block's `projection` may select. */
const PROJECTION_FIELDS = ['fields', 'sections'];

/** Keys a section may carry. */
const SECTION_FIELDS = [
  'id',
  'title',
  'category',
  'content',
  'previewType',
  'before',
  'after',
];

/**
 * The fields an extension section places itself with: the key of the base
 * section it goes before or after. Read only by a merge, never by a reader.
 */
export const SECTION_POSITION_FIELDS = ['before', 'after'];

/**
 * Check the fields the docs surfaces actually read. `parseDoc` is the outer
 * gate, but the reference-doc schema is a passthrough over `{name, type}` —
 * a doc with no `sections`, or a prose block whose `text` is misspelled,
 * passes it and reaches a reader as a missing section or a blank gap. Those
 * are hard to trace back from the rendered output, so they are caught here,
 * where the file that needs fixing can be named.
 *
 * @param {any} doc a parsed doc
 * @param {{placement?: boolean}} [options] `placement`: the doc is a guide the
 *   docs tree places, so its `placement` field is read, not rejected
 * @returns {string[]} problems, each already pointed at a place in the doc
 */
export function problemsInTopic(doc, {placement = false} = {}) {
  // A namespace doc is valid authoring that only the docs tree reads. Said
  // plainly, instead of as the topic fields it does not have.
  if (doc?.type === 'namespace') {
    return [
      `"${doc.name}" is a namespace doc, which the docs tree reads, not the topic list. The CLI keeps its own in assets/docs/tree; an integration ships its namespace docs in its docs directory.`,
    ];
  }
  /** @type {string[]} */
  const problems = [];
  for (const field of ['name', 'title', 'description']) {
    if (typeof doc?.[field] !== 'string' || doc[field] === '') {
      problems.push(`${field}: expected a non-empty string`);
    }
  }
  if (typeof doc?.name === 'string' && !TOPIC_NAME_RE.test(doc.name)) {
    problems.push(
      `name: "${doc.name}" is not URL-safe. A topic name is its CLI argument and its docsite path, so it may hold only letters, digits, "_" and "-".`,
    );
  }
  for (const field of GRAPH_ONLY_FIELDS) {
    // A guide the docs tree places carries `placement`; the tree reads it.
    if (field === 'placement' && placement) continue;
    if (doc?.[field] != null) {
      problems.push(
        `${field}: requires the compiled graph reader and is not supported by legacy topic readers`,
      );
    }
  }
  if (!Array.isArray(doc?.sections) || doc.sections.length === 0) {
    problems.push('sections: expected at least one section');
    return problems;
  }

  doc.sections.forEach(
    (/** @type {any} */ section, /** @type {number} */ s) => {
      const at = `sections[${s}]`;
      if (typeof section?.title !== 'string' || section.title === '') {
        problems.push(`${at}.title: expected a non-empty string`);
      }
      for (const key of Object.keys(section ?? {})) {
        if (!SECTION_FIELDS.includes(key)) {
          problems.push(`${at}.${key}: not a field of a section`);
        }
      }
      for (const field of SECTION_POSITION_FIELDS) {
        const value = section?.[field];
        if (value != null && (typeof value !== 'string' || value === '')) {
          problems.push(
            `${at}.${field}: expected the key of a section, as \`--index\` shows it`,
          );
        }
      }
      if (section?.before != null && section?.after != null) {
        problems.push(
          `${at}: sets both \`before\` and \`after\`; a section goes in one place`,
        );
      }
      if (!Array.isArray(section?.content)) {
        problems.push(`${at}.content: expected an array of blocks`);
        return;
      }
      section.content.forEach(
        (/** @type {any} */ block, /** @type {number} */ b) => {
          const blockAt = `${at}.content[${b}]`;
          const fields = /** @type {Record<string, string[]>} */ (BLOCK_FIELDS)[
            block?.type
          ];
          if (fields == null) {
            if (GRAPH_BLOCK_TYPES.has(block?.type)) {
              problems.push(
                `${blockAt}.type: ${JSON.stringify(block.type)} requires the compiled graph renderer and is not supported by legacy topic readers`,
              );
            } else {
              problems.push(
                `${blockAt}.type: ${JSON.stringify(block?.type)} is not one of ${Object.keys(BLOCK_FIELDS).join(', ')}`,
              );
            }
            return;
          }
          for (const field of fields) {
            const value = block[field];
            // Empty counts as missing, the way it does for the doc's own title: a
            // block whose text is '' passes every other check and renders as a gap.
            if (value == null) {
              problems.push(
                `${blockAt}.${field}: required for a ${block.type} block`,
              );
            } else if (typeof value === 'string' && value.trim() === '') {
              problems.push(`${blockAt}.${field}: expected a non-empty string`);
            } else if (Array.isArray(value) && value.length === 0) {
              problems.push(`${blockAt}.${field}: expected a non-empty array`);
            }
          }
          const allowedValues =
            /** @type {Record<string, Record<string, unknown[]>>} */ (
              BLOCK_FIELD_VALUES
            )[block.type] ?? {};
          for (const [field, values] of Object.entries(allowedValues)) {
            const value = block[field];
            if (value != null && !values.includes(value)) {
              problems.push(
                `${blockAt}.${field}: ${JSON.stringify(value)} is not one of ${values.join(', ')}`,
              );
            }
          }
          // A table's cells are read by column index, so a short row renders blank
          // cells and a long one drops its tail — both silently.
          if (
            block.type === 'table' &&
            Array.isArray(block.headers) &&
            Array.isArray(block.rows)
          ) {
            block.rows.forEach(
              (/** @type {any} */ row, /** @type {number} */ r) => {
                if (!Array.isArray(row)) {
                  problems.push(
                    `${blockAt}.rows[${r}]: expected an array of cells`,
                  );
                } else if (row.length !== block.headers.length) {
                  problems.push(
                    `${blockAt}.rows[${r}]: has ${row.length} cells but the table has ${block.headers.length} headers`,
                  );
                }
              },
            );
          }
          // An unknown key is almost always a misspelled required one, and it
          // would otherwise reach a reader as a block that renders nothing.
          const allowed = [
            'type',
            ...fields,
            ...(OPTIONAL_BLOCK_FIELDS[block.type] ?? []),
          ];
          for (const key of Object.keys(block)) {
            if (!allowed.includes(key)) {
              problems.push(
                `${blockAt}.${key}: not a field of a ${block.type} block`,
              );
            }
          }
          // A projection names the parts of the doc to include, so each part
          // it names is a non-empty list of names.
          if (block.type === 'reference' && block.projection != null) {
            const projection = block.projection;
            if (typeof projection !== 'object' || Array.isArray(projection)) {
              problems.push(
                `${blockAt}.projection: expected {fields?, sections?}, naming the parts of the doc to include`,
              );
            } else {
              for (const [key, names] of Object.entries(projection)) {
                if (!PROJECTION_FIELDS.includes(key)) {
                  problems.push(
                    `${blockAt}.projection.${key}: not a field of a projection`,
                  );
                } else if (
                  !Array.isArray(names) ||
                  names.length === 0 ||
                  names.some(
                    name => typeof name !== 'string' || name.trim() === '',
                  )
                ) {
                  problems.push(
                    `${blockAt}.projection.${key}: expected a non-empty array of names`,
                  );
                }
              }
            }
          }
        },
      );
    },
  );
  // Explicit authored IDs are a new opt-in contract and remain strict. Topics
  // that relied on 0.6.x title-only sections keep loading; the compiler assigns
  // deterministic fallback/suffixed keys for the additive index API.
  problems.push(...sectionKeyErrors(doc.sections));
  return problems;
}

/**
 * The fields the docs tree reads from a namespace doc an integration ships.
 * @param {any} doc
 * @returns {string[]}
 */
export function problemsInNamespace(doc) {
  /** @type {string[]} */
  const problems = [];
  for (const field of ['name', 'title', 'summary']) {
    if (typeof doc?.[field] !== 'string' || doc[field] === '') {
      problems.push(`${field}: expected a non-empty string`);
    }
  }
  const slots = doc?.slots;
  if (
    slots == null ||
    typeof slots !== 'object' ||
    Object.keys(slots).length === 0
  ) {
    problems.push('slots: expected at least one slot');
    return problems;
  }
  for (const [name, slot] of Object.entries(slots)) {
    if (typeof slot?.title !== 'string' || slot.title === '') {
      problems.push(`slots.${name}.title: expected a non-empty string`);
    }
    if (
      !Array.isArray(slot?.accepts?.kinds) ||
      slot.accepts.kinds.length === 0
    ) {
      problems.push(`slots.${name}.accepts.kinds: expected at least one kind`);
    }
  }
  return problems;
}

/**
 * Whether `dir` is a folder to list. A declared root that is a file is
 * reported by the root check; discovery finds nothing in it.
 * @param {string} dir
 */
function isFolder(dir) {
  try {
    return fs.statSync(dir).isDirectory();
  } catch {
    return false;
  }
}

/**
 * Discover the topics contributed by a single loaded integration. Mirrors
 * `discoverIntegrationComponents`: walk the resolved root, take every
 * conventional doc file, and record what it declares. Unlike component
 * discovery this loads each doc, because a topic's name and its relationship
 * to an existing topic are fields inside the file.
 *
 * A namespace doc and a guide with `placement` go to the docs tree instead of
 * the topic list (spec:AST-046): they come back in `namespaces` and `guides`,
 * named by the integration's provider id.
 *
 * Errors are returned, not thrown: one unusable doc is reported as an issue
 * against its package while the rest of the CLI keeps working.
 *
 * @param {{name: string, docs?: string, providerId?: string}} integration a loaded integration
 * @returns {Promise<{records: DocsTopicRecord[], errors: Error[], namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>}
 */
export async function discoverIntegrationDocs(integration) {
  const docsDir = integration?.docs;
  /** @type {DocsTopicRecord[]} */
  const records = [];
  /** @type {Error[]} */
  const errors = [];
  /** @type {import('../doc-compiler/tree.mjs').TreeNamespaceInput[]} */
  const namespaces = [];
  /** @type {import('../doc-compiler/tree.mjs').TreeDocInput[]} */
  const guides = [];
  if (!docsDir || !isFolder(docsDir)) {
    return {records, errors, namespaces, guides};
  }
  const providerId = integration.providerId ?? integration.name;

  /** @type {string[]} */
  const files = [];
  /** @param {string} dirPath */
  function scanDir(dirPath) {
    for (const entry of listDirEntries(dirPath)) {
      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
      const full = path.join(dirPath, entry.name);
      if (entry.isDirectory()) {
        scanDir(full);
      } else if (
        INTEGRATION_DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))
      ) {
        files.push(full);
      }
    }
  }
  scanDir(docsDir);
  files.sort();

  /** @type {Map<string, string>} */
  const seen = new Map();
  for (const file of files) {
    let doc;
    try {
      doc = parseReadableDoc(await loadTopicModule(file), path.basename(file));
    } catch (err) {
      errors.push(
        new Error(
          `${path.relative(docsDir, file)}: ${/** @type {any} */ (err).message}`,
        ),
      );
      continue;
    }
    const relative = path.relative(docsDir, file);
    const source = `${integration.name}/${relative.split(path.sep).join('/')}`;
    if (/** @type {any} */ (doc)?.type === 'namespace') {
      const problems = problemsInNamespace(doc);
      if (problems.length > 0) {
        errors.push(
          new Error(
            `${relative} is not a usable namespace doc:\n${problems
              .map(problem => `  ${problem}`)
              .join('\n')}`,
          ),
        );
        continue;
      }
      namespaces.push({
        provider: integration.name,
        providerId,
        source,
        doc: /** @type {any} */ (doc),
      });
      continue;
    }
    const placed = /** @type {any} */ (doc)?.placement != null;
    const problems = problemsInTopic(doc, {placement: placed});
    if (problems.length > 0) {
      errors.push(
        new Error(
          `${relative} is not a usable topic:\n${problems
            .map(problem => `  ${problem}`)
            .join('\n')}`,
        ),
      );
      continue;
    }
    const parsed = /** @type {any} */ (doc);
    // Two files claiming one name would collapse into a single entry, and the
    // one that lost would never be reachable. Named here, where both files are.
    const topicKey = parsed.name.toLowerCase();
    const previous = seen.get(topicKey);
    if (previous) {
      errors.push(
        new Error(
          `${path.relative(docsDir, file)} and ${previous} both define the topic "${parsed.name}". Each topic name is a URL and a CLI argument, so they have to be unique.`,
        ),
      );
      continue;
    }
    seen.set(topicKey, path.relative(docsDir, file));
    if (placed) {
      if (parsed.replaces != null || parsed.extends != null) {
        errors.push(
          new Error(
            `${relative} is placed in the docs tree and also declares \`${parsed.replaces != null ? 'replaces' : 'extends'}\`. A placed guide has its own route; only a flat topic takes over or extends another.`,
          ),
        );
        continue;
      }
      guides.push({
        provider: integration.name,
        providerId,
        source,
        kind: 'generic',
        name: parsed.name,
        title: parsed.title,
        // Rendered once, where the tree is built (api/docs/_adapter.mjs).
        summary: parsed.description,
        group: null,
        placement: parsed.placement,
        ref: {topicFile: file},
      });
      continue;
    }
    if (parsed.replaces != null && parsed.extends != null) {
      errors.push(
        new Error(
          `${path.relative(docsDir, file)} declares both \`replaces\` and \`extends\`. A topic either takes another's place or merges onto it.`,
        ),
      );
      continue;
    }
    records.push({
      name: parsed.name,
      package: integration.name,
      path: file,
      title: parsed.title,
      description: parsed.description,
      category: parsed.category ?? null,
      replaces: parsed.replaces,
      extendsTopic: parsed.extends,
      ...(providerId === integration.name ? {} : {providerId}),
    });
  }

  return {records, errors, namespaces, guides};
}

/**
 * Merge an extension onto a base topic: a section with a stable `id` replaces
 * the base section with the same `id`; legacy sections without IDs fall back to
 * title matching. A section with no match is added: before or after the
 * section whose key its `before` or `after` names, else at the end. The title
 * and description stay the base topic's: an extension adds to a topic, it never
 * renames it. A topic that `replaces` another is the one that renames.
 *
 * Keyed by section TITLE rather than by position, the way the localization
 * overlays are — position keying grafts an overlay onto whichever section
 * happens to share its index, so a partial or reordered overlay corrupts
 * everything after it (#2182).
 *
 * @param {any} base
 * @param {any} overlay
 * @returns {any} a new doc; neither input is mutated
 */
export function mergeTopic(base, overlay) {
  return mergeTopicReport(base, overlay).doc;
}

/**
 * {@link mergeTopic}, also naming each `before` or `after` that found no
 * section: that section was added at the end instead.
 *
 * @param {any} base
 * @param {any} overlay
 * @returns {{doc: any, unplaced: Array<{section: string, field: 'before' | 'after', key: string}>}}
 */
export function mergeTopicReport(base, overlay) {
  const sections = [...(base.sections ?? [])];
  /** @type {Array<{section: string, field: 'before' | 'after', key: string}>} */
  const unplaced = [];

  for (const authored of overlay.sections ?? []) {
    const section = withoutPosition(authored);
    const at = findMergeTarget(sections, section);
    if (at === -1) {
      const field = authored.before != null ? 'before' : 'after';
      const key = authored[field];
      if (typeof key !== 'string') {
        sections.push(section);
        continue;
      }
      const anchor = sections.findIndex(
        candidate => sectionKey(candidate) === key || candidate.id === key,
      );
      if (anchor === -1) {
        unplaced.push({section: sectionKey(section), field, key});
        sections.push(section);
      } else if (field === 'before') {
        // Placed just before a section another was placed `after`, it joins
        // that section's group, so later sections placed there follow both.
        if (sections[anchor][PLACED_AFTER] != null) {
          Object.defineProperty(section, PLACED_AFTER, {
            value: sections[anchor][PLACED_AFTER],
            configurable: true,
          });
        }
        sections.splice(anchor, 0, section);
      } else {
        // Sections placed after one key keep their order, across every
        // extension merged onto the topic: each goes after every section
        // placed there before it, and after the sections placed after those.
        const group = new Set([key]);
        let at = anchor + 1;
        while (at < sections.length && group.has(sections[at][PLACED_AFTER])) {
          group.add(sectionKey(sections[at]));
          at += 1;
        }
        Object.defineProperty(section, PLACED_AFTER, {
          value: key,
          configurable: true,
        });
        sections.splice(at, 0, section);
      }
    } else {
      // A legacy extension that replaces a section which has since gained a
      // stable ID keeps that ID, so readers addressing it keep working. A
      // replacing section keeps the place of the one it replaces.
      const replaced = sections[at];
      const replacing =
        section.id == null && replaced.id != null
          ? withSourceTitle({...section, id: replaced.id}, sourceTitle(section))
          : section;
      // It also keeps the place an earlier `after` gave the one it replaces,
      // so sections placed after that key later still follow it.
      if (replaced[PLACED_AFTER] != null) {
        const placed =
          replacing === section ? withoutPosition({...section}) : replacing;
        for (const symbol of Object.getOwnPropertySymbols(section)) {
          if (!(symbol in placed)) {
            Object.defineProperty(
              placed,
              symbol,
              /** @type {PropertyDescriptor} */ (
                Object.getOwnPropertyDescriptor(section, symbol)
              ),
            );
          }
        }
        Object.defineProperty(placed, PLACED_AFTER, {
          value: replaced[PLACED_AFTER],
          configurable: true,
        });
        sections[at] = placed;
      } else {
        sections[at] = replacing;
      }
    }
  }
  return {doc: {...base, sections}, unplaced};
}

/** The key a merged section was placed `after`, so later ones follow it. */
const PLACED_AFTER = Symbol('astryx.docs.placedAfter');

/**
 * A section without the fields that place it; readers never see them.
 * @param {any} section
 * @returns {any}
 */
export function withoutPosition(section) {
  if (section?.before == null && section?.after == null) return section;
  const {before: _before, after: _after, ...rest} = section;
  // Copy every own symbol (the provider and authored-title marks) too.
  for (const symbol of Object.getOwnPropertySymbols(section)) {
    Object.defineProperty(
      rest,
      symbol,
      /** @type {PropertyDescriptor} */ (
        Object.getOwnPropertyDescriptor(section, symbol)
      ),
    );
  }
  return rest;
}

/**
 * The base section an extension section replaces. A stable ID matches first.
 * Otherwise the exact title matches when at least one side has no ID: the
 * migration window in which the base or the extension adopts stable IDs
 * before the other does. Two different authored IDs stay distinct even under
 * one title.
 *
 * @param {any[]} sections
 * @param {any} section
 * @returns {number}
 */
function findMergeTarget(sections, section) {
  const title = sourceTitle(section);
  const key = sectionKey(section);
  // A section is addressed by its key: an authored id, or the key its title
  // derives, which is the key the topic's index shows. Matching on it means an
  // extension never appends a second section under a key already in use.
  const byKey = () =>
    sections.findIndex(candidate => sectionKey(candidate) === key);
  const legacyTitleMatch = () =>
    sections.findIndex(
      candidate => candidate.id == null && sourceTitle(candidate) === title,
    );
  if (section.id != null) {
    const byId = byKey();
    return byId === -1 ? legacyTitleMatch() : byId;
  }
  const legacy = legacyTitleMatch();
  if (legacy !== -1) return legacy;
  const sameTitle = sections.findIndex(
    candidate => sourceTitle(candidate) === title,
  );
  if (sameTitle !== -1) return sameTitle;
  // A base section retitled later keeps its old key as its `id`, so an
  // extension that still names it by the old title finds it by that id. A
  // title variant of a section with no id stays a separate section.
  return sections.findIndex(candidate => candidate.id === key);
}

/**
 * A component a link can name: its owner's provider id, package, and name,
 * and the doc file that describes it.
 * @typedef {object} LinkableComponent
 * @property {string} providerId
 * @property {string} package
 * @property {string} name
 * @property {string | null} docPath
 * @property {string} [replaces] the Core component whose name it answers to
 *   in unqualified lookups (spec:AST-035 FR11)
 */

/**
 * A page or block template a link can name, by the id `astryx template` takes.
 * @typedef {object} LinkableTemplate
 * @property {string} providerId
 * @property {string} package
 * @property {'page' | 'block'} type
 * @property {string} id
 * @property {string} name
 * @property {string} [displayName]
 * @property {string} [description]
 * @property {string} [replaces] the Core template id it answers to in
 *   unqualified lookups
 */

/**
 * The component and template docs links can name (spec:AST-047 FR9). No docs
 * tree holds them, so a catalog carries the records the project reads.
 * @typedef {{components: LinkableComponent[], templates: LinkableTemplate[]}} LinkableContributions
 */

/**
 * Every topic a project can read, and the relationships between them.
 *
 * Insertion order is the read order: the built-in topics in discovery order,
 * then whatever the configured integrations add, in the order they are
 * configured. A replacement keeps the position of the topic it replaced, so
 * "the first topic" stays stable for a reader that opens it by default.
 */
export class DocsCatalog {
  /** @type {Map<string, DocsTopicEntry>} */
  #topics = new Map();
  /** @type {(() => Promise<LinkableContributions>) | null} */
  #contributions = null;
  /** @type {Promise<LinkableContributions> | null} */
  #contributionsLoaded = null;
  /** @type {Map<string, string>} old topic name → the name that replaced it */
  #aliases = new Map();
  /** @type {Array<{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>} */
  #treeInputs = [];
  /** @type {Array<{package: string, message: string}>} */
  #issues = [];
  /** @type {Map<string, GuideOverlay>} lowercased route → what applies there */
  #guideOverlays = new Map();
  /** @type {DocsTopicRecord[]} every doc that targets a route, in order */
  #guideTargeters = [];

  /**
   * Record a doc that replaces or extends a guide the docs tree places, by
   * its route. Whether the route holds such a guide is known only once the
   * tree is built: {@link guideOverlay} applies the record there, and a route
   * that holds none applies nothing.
   * @param {DocsTopicRecord} record
   * @returns {import('../integrations/issue').AstryxIntegrationIssue | null}
   */
  #targetGuide(record) {
    const route = /** @type {string} */ (
      record.replaces ?? record.extendsTopic
    );
    const key = route.toLowerCase();
    const overlay = this.#guideOverlays.get(key) ?? {
      replacement: null,
      extensions: [],
    };
    if (record.replaces != null) {
      const earlier = overlay.replacement;
      if (earlier) {
        // As with a flat topic, the later-configured doc wins, and reads name
        // the replacement it took over from. Unlike a flat topic's, this is
        // no warning: a new failing finding joins only in a minor release
        // (architecture:cli-surface INV35); `integration validate` lists one
        // package's two replacements of a guide as a note.
        overlay.replacedPackage = earlier.package;
      }
      // Extensions were authored against the content that just went away.
      overlay.replacement = record;
      overlay.extensions = [];
    } else {
      overlay.extensions.push({
        package: record.package,
        path: record.path,
        ...(record.providerId ? {providerId: record.providerId} : {}),
      });
    }
    this.#guideOverlays.set(key, overlay);
    this.#guideTargeters.push(record);
    return null;
  }

  /**
   * What the integrations do to the guide the docs tree places at `route`, or
   * null when they leave it as it is.
   * @param {string} route
   * @returns {GuideOverlay | null}
   */
  guideOverlay(route) {
    return this.#guideOverlays.get(route.toLowerCase()) ?? null;
  }

  /**
   * Every doc that replaces or extends a guide by its route, in configured
   * order, so a check can name a route that holds no guide.
   * @returns {ReadonlyArray<DocsTopicRecord>}
   */
  get guideTargeters() {
    return this.#guideTargeters;
  }

  /**
   * Record a doc file a package ships that did not load. Its package's docs
   * are withdrawn; readers name the package so an author knows where to look.
   * @param {{package: string, message: string}} issue
   */
  addIssue(issue) {
    this.#issues.push(issue);
  }

  /**
   * The doc files that did not load, by package.
   * @returns {ReadonlyArray<{package: string, message: string}>}
   */
  get issues() {
    return this.#issues;
  }

  /**
   * Add the namespace docs and placed guides one integration ships to the
   * docs tree (spec:AST-046).
   * @param {{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}} inputs
   */
  addTreeInputs(inputs) {
    if (inputs.namespaces.length > 0 || inputs.guides.length > 0) {
      this.#treeInputs.push(inputs);
    }
  }

  /**
   * What the integrations add to the docs tree, in configured order.
   * @returns {ReadonlyArray<{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>}
   */
  get treeInputs() {
    return this.#treeInputs;
  }

  /**
   * Say where links find component, page, and block docs: the records
   * `astryx component` and `astryx template` read, loaded on first use.
   * @param {() => Promise<LinkableContributions>} load
   */
  setContributions(load) {
    this.#contributions = load;
    this.#contributionsLoaded = null;
  }

  /**
   * The component and template docs links can name, or null when nothing set
   * them, so no link to one resolves.
   * @returns {Promise<LinkableContributions | null>}
   */
  contributions() {
    if (!this.#contributions) return Promise.resolve(null);
    this.#contributionsLoaded ??= this.#contributions();
    return this.#contributionsLoaded;
  }

  /**
   * Seed a catalog with the CLI's own topics.
   * @param {Record<string, string>} [builtins] topic name → absolute path
   * @returns {DocsCatalog}
   */
  static fromBuiltins(builtins = discoverBuiltinTopics()) {
    const catalog = new DocsCatalog();
    for (const [name, file] of Object.entries(builtins)) {
      catalog.#topics.set(name.toLowerCase(), {
        name,
        package: BUILTIN_DOCS_PACKAGE,
        path: file,
        extensions: [],
      });
    }
    return catalog;
  }

  /**
   * Add one integration-contributed doc, honoring what it declares. Returns
   * the issue it caused, or null when it applied cleanly — the caller owns
   * routing (an `error` skips the contribution, a `warning` keeps it).
   *
   * @param {DocsTopicRecord} record
   * @returns {import('../integrations/issue').AstryxIntegrationIssue | null}
   */
  add(record) {
    if (record.extendsTopic != null) {
      const target = this.resolve(record.extendsTopic);
      if (!target && isGuideRoute(record.extendsTopic)) {
        return this.#targetGuide(record);
      }
      if (!target) {
        return {
          code: 'invalid_doc',
          severity: 'error',
          message: `"${record.name}" extends "${record.extendsTopic}", which is not a topic in this project.`,
        };
      }
      target.extensions.push({
        package: record.package,
        path: record.path,
        ...(record.providerId ? {providerId: record.providerId} : {}),
      });
      return null;
    }

    if (record.replaces != null) {
      const target = this.resolve(record.replaces);
      if (!target && isGuideRoute(record.replaces)) {
        return this.#targetGuide(record);
      }
      if (!target) {
        return {
          code: 'invalid_doc',
          severity: 'error',
          message: `"${record.name}" replaces "${record.replaces}", which is not a topic in this project.`,
        };
      }
      /** @type {import('../integrations/issue').AstryxIntegrationIssue | null} */
      let warning = null;
      if (target.package !== BUILTIN_DOCS_PACKAGE) {
        // Two integrations replacing one topic is a real configuration, not a
        // broken one: the later-configured package wins, the way the last
        // writer does everywhere else. Both are named so the loser is visible.
        warning = {
          code: 'duplicate_doc',
          severity: 'warning',
          message: `Topic "${record.replaces}" is replaced by both ${target.package} and ${record.package}. ${record.package} is configured later, so it wins.`,
        };
      }
      // The replacement takes the base topic's slot, so a reader that opens
      // the first topic (or the nth) sees the same one it did before.
      const replaced = target.name;
      const replacedKey = replaced.toLowerCase();
      const replacementKey = record.name.toLowerCase();
      this.#replaceAt(replacedKey, {
        name: record.name,
        package: record.package,
        path: record.path,
        title: record.title,
        description: record.description,
        category: record.category,
        replaces: replaced,
        // The package whose topic it took over: an earlier replacement's, when
        // the topic was already replaced.
        replacedPackage: target.package,
        ...(record.providerId ? {providerId: record.providerId} : {}),
        // Extensions were authored against the content that just went away.
        extensions: [],
      });
      if (replacementKey !== replacedKey) {
        this.#aliases.set(replacedKey, replacementKey);
        // A topic renamed twice keeps every name it has ever answered to.
        for (const [from, to] of this.#aliases) {
          if (to === replacedKey) this.#aliases.set(from, replacementKey);
        }
      }
      return warning;
    }

    const topicKey = record.name.toLowerCase();
    const existing = this.#topics.get(topicKey);
    if (existing) {
      return {
        code: 'invalid_doc',
        severity: 'error',
        message: `Topic "${record.name}" is already provided by ${existing.package}. Give it another name, or declare \`replaces: '${record.name}'\` to take its place.`,
      };
    }
    this.#topics.set(topicKey, {
      name: record.name,
      package: record.package,
      path: record.path,
      title: record.title,
      description: record.description,
      category: record.category,
      ...(record.providerId ? {providerId: record.providerId} : {}),
      extensions: [],
    });
    return null;
  }

  /**
   * Every other name a topic answers to, lowercased: the names of the topics
   * it replaced, directly or through a chain of replacements. `resolve` finds
   * the topic by each of them.
   * @param {DocsTopicEntry} entry
   * @returns {string[]}
   */
  aliasesOf(entry) {
    const key = entry.name.toLowerCase();
    return [...this.#aliases]
      .filter(([, to]) => to === key)
      .map(([from]) => from);
  }

  /**
   * Look a topic up by name, case-insensitively, following the alias a renamed
   * replacement left behind.
   * @param {unknown} name
   * @returns {DocsTopicEntry | undefined}
   */
  resolve(name) {
    if (typeof name !== 'string') return undefined;
    let key = name.toLowerCase();
    // An alias chain is at most as long as the number of replacements, and a
    // cycle can only come from a bug here; bound the walk either way.
    for (let hops = 0; hops <= this.#aliases.size; hops++) {
      const entry = this.#topics.get(key);
      if (entry) return entry;
      const next = this.#aliases.get(key);
      if (next == null) return undefined;
      key = next;
    }
    return undefined;
  }

  /** @returns {string[]} every topic name, in read order */
  names() {
    return [...this.#topics.values()].map(entry => entry.name);
  }

  /** @returns {DocsTopicEntry[]} every topic, in read order */
  entries() {
    return [...this.#topics.values()];
  }

  /**
   * Swap an entry in place, preserving its position in the read order.
   * @param {string} name
   * @param {DocsTopicEntry} entry
   */
  #replaceAt(name, entry) {
    /** @type {Map<string, DocsTopicEntry>} */
    const next = new Map();
    for (const [key, value] of this.#topics) {
      if (key === name.toLowerCase()) next.set(entry.name.toLowerCase(), entry);
      else next.set(key, value);
    }
    this.#topics = next;
  }
}