@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  AUTHORING_SELF_DOCS,
+  auditAuthoringSelfDocs,
+  buildAuthoringTopic,
+  discoverAuthoringSelfDocSources,
+} from './authoring-self-docs.mjs';
+import {
+  GRAPH_BLOCK_TYPES,
+  GRAPH_ONLY_FIELDS,
+  problemsInTopic,
+} from './docs-discovery.mjs';
+import {doc as graphFieldsDoc} from '../../authoring/doctypes/base/graph-fields.doc.mjs';
+import {doc as namespaceDoc} from '../../authoring/doctypes/namespace/namespace.doc.mjs';
+import {doc as referenceDoc} from '../../authoring/doctypes/reference/reference.doc.mjs';
+import {docs} from '../../api/docs/docs.mjs';
+
+const SLOW = 60_000;
+
+describe('authoring self-docs', () => {
+  it('lists every self-doc on disk exactly once', () => {
+    expect([...AUTHORING_SELF_DOCS].sort()).toEqual(
+      discoverAuthoringSelfDocSources(),
+    );
+    expect(new Set(AUTHORING_SELF_DOCS).size).toBe(AUTHORING_SELF_DOCS.length);
+  });
+
+  it('audits clean: every self-doc loads, is reachable, and fits one read', async () => {
+    expect(await auditAuthoringSelfDocs()).toEqual({
+      sections: AUTHORING_SELF_DOCS.length,
+      unreachable: [],
+      failed: [],
+      oversized: [],
+    });
+  });
+
+  it('builds a valid topic with one section per self-doc', async () => {
+    const topic = await buildAuthoringTopic();
+    expect(problemsInTopic(topic)).toEqual([]);
+    expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
+  });
+
+  it(
+    'is readable progressively through the docs API',
+    async () => {
+      const index = await docs('authoring', undefined, {index: true});
+      expect(index.type).toBe('docs.index');
+      expect(index.data.sections.map(s => s.id)).toContain('integration');
+      const section = await docs('authoring', 'integration');
+      expect(section.data.title).toBe('Astryx Integration');
+      expect(section.data.content.some(block => block.type === 'table')).toBe(
+        true,
+      );
+    },
+    SLOW,
+  );
+});
+
+describe('what the authoring docs say about the unbuilt docs graph', () => {
+  it('marks exactly the fields topic loading rejects as not read yet', () => {
+    const notReadYet = graphFieldsDoc.fields
+      .filter(field => /Not read yet/.test(field.description))
+      .map(field => field.name);
+    expect(notReadYet.sort()).toEqual([...GRAPH_ONLY_FIELDS].sort());
+    for (const field of graphFieldsDoc.fields) {
+      if (notReadYet.includes(field.name)) {
+        expect(field.description).toMatch(/fails to load/);
+      }
+    }
+    expect(graphFieldsDoc.description).toMatch(/not built yet/);
+  });
+
+  it('says a topic using a graph block fails to load', () => {
+    const content = referenceDoc.fields
+      .flatMap(field => [field, ...(field.fields ?? [])])
+      .find(field => field.name === 'sections[].content');
+    for (const type of GRAPH_BLOCK_TYPES) {
+      expect(content.description).toContain(type);
+    }
+    expect(content.description).toMatch(/fails to load/);
+  });
+
+  it('says namespace docs are not loaded yet', () => {
+    expect(namespaceDoc.description).toMatch(/Not loaded yet/);
+    expect(
+      problemsInTopic({
+        ...namespaceDoc.examples?.[0],
+        type: 'namespace',
+        name: 'x',
+      }),
+    ).toEqual([
+      '"x" is a namespace doc. Only the docs graph reads namespace docs, and it is not built yet; remove this file from the docs directory.',
+    ]);
+  });
+});
+
+describe('auditAuthoringSelfDocs', () => {
+  let root;
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-self-docs-'));
+    fs.mkdirSync(path.join(root, 'kept'));
+    fs.writeFileSync(
+      path.join(root, 'kept', 'kept.doc.mjs'),
+      "export const doc = {type: 'schema', name: 'kept', displayName: 'Kept', description: 'Listed.', fields: []};\n",
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, {recursive: true, force: true});
+  });
+
+  it('names a self-doc on disk that the list leaves out', async () => {
+    fs.writeFileSync(
+      path.join(root, 'kept', 'forgotten.doc.mjs'),
+      "export const doc = {name: 'forgotten', description: 'Not listed.'};\n",
+    );
+    const audit = await auditAuthoringSelfDocs({
+      root,
+      sources: ['kept/kept.doc.mjs'],
+    });
+    expect(audit.unreachable).toEqual(['kept/forgotten.doc.mjs']);
+  });
+
+  it('reports a self-doc that fails to load instead of throwing', async () => {
+    fs.writeFileSync(
+      path.join(root, 'kept', 'broken.doc.mjs'),
+      'export const doc = {;\n',
+    );
+    const audit = await auditAuthoringSelfDocs({
+      root,
+      sources: ['kept/kept.doc.mjs', 'kept/broken.doc.mjs'],
+    });
+    expect(audit.failed.map(entry => entry.source)).toEqual([
+      'kept/broken.doc.mjs',
+    ]);
+    expect(audit.sections).toBe(1);
+  });
+
+  it('names a section over the budget', async () => {
+    const audit = await auditAuthoringSelfDocs({
+      root,
+      sources: ['kept/kept.doc.mjs'],
+      budget: 10,
+    });
+    expect(audit.oversized).toEqual([
+      expect.objectContaining({key: 'kept', title: 'Kept'}),
+    ]);
+  });
+});

package/foundation/discovery/component-discovery.d.mts

@@ -175,4 +175,4 @@ export function discoverOwnedComponents(coreDir: string, loadedIntegrations?: Ar
     issuesUrl: string | undefined;
 }>;
 /** The owner package name for built-in (core) components. */
-export const CORE_PACKAGE: "@astryxdesign/core";
+export const CORE_PACKAGE: import("../../authoring/index.js").ProviderId;

package/foundation/discovery/component-discovery.mjs

@@ -7,11 +7,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {existsCaseExact} from '../fs/paths.mjs';
+import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
 
 const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);
 
 /** The owner package name for built-in (core) components. */
-export const CORE_PACKAGE = '@astryxdesign/core';
+export const CORE_PACKAGE = CORE_PROVIDER_ID;
 
 /** Conventional doc-file suffixes for integration components (same-stem). */
 const INTEGRATION_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];

package/foundation/discovery/docs-discovery.d.mts

@@ -72,9 +72,10 @@ export function discoverIntegrationDocs(integration: {
     errors: Error[];
 }>;
 /**
- * Merge an extension onto a base topic: a section whose title matches one in
- * the base replaces it, a section the base does not have is appended, and the
- * title/description are taken from the extension when it states them.
+ * 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 appended, and title/description
+ * are taken from the extension when it states them.
  *
  * Keyed by section TITLE rather than by position, the way the localization
  * overlays are — position keying grafts an overlay onto whichever section
@@ -86,12 +87,17 @@ export function discoverIntegrationDocs(integration: {
  * @returns {any} a new doc; neither input is mutated
  */
 export function mergeTopic(base: any, overlay: any): any;
+export { withSourceTitle };
 /**
  * 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: "@astryxdesign/cli";
+export const BUILTIN_DOCS_PACKAGE: import("../../authoring/index.js").ProviderId;
+/** Blocks that are valid authoring but require the compiled graph renderer. */
+export const GRAPH_BLOCK_TYPES: Set<string>;
+/** Doc fields only the docs graph reads; a topic that sets one fails to load. */
+export const GRAPH_ONLY_FIELDS: string[];
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -183,3 +189,4 @@ export type DocsTopicEntry = {
         path: string;
     }>;
 };
+import { withSourceTitle } from './docs-section-key.mjs';

package/foundation/discovery/docs-discovery.mjs

@@ -33,7 +33,16 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {CLI_ROOT} from '../fs/paths.mjs';
 import {importUserModule} from '../fs/module-loader.mjs';
+import {CLI_PROVIDER_ID} from '../identity/providers.mjs';
 import {parseDoc} from '../../authoring/doctypes/parse.mjs';
+import {
+  sectionKey,
+  sectionKeyProblems,
+  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');
@@ -43,7 +52,7 @@ const BUILTIN_DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');
  * (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 = '@astryxdesign/cli';
+export const BUILTIN_DOCS_PACKAGE = CLI_PROVIDER_ID;
 
 /**
  * A built-in topic file: `{topic}.doc.mjs`. Anchored at both ends so a
@@ -128,12 +137,25 @@ const BLOCK_FIELDS = {
   'token-ref': ['topic', 'section'],
 };
 
+/** Blocks that are valid authoring but require the compiled graph renderer. */
+export const GRAPH_BLOCK_TYPES = new Set([
+  'workflow',
+  'collection',
+  'reference',
+]);
+
+/** Doc fields only the docs graph reads; a topic that sets one fails to load. */
+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.
  */
-const OPTIONAL_BLOCK_FIELDS = {code: ['label']};
+/** @type {Record<string, string[]>} */
+const OPTIONAL_BLOCK_FIELDS = {
+  code: ['label'],
+};
 
 /**
  * Fields whose value has to be one of a set, because the renderer indexes on
@@ -147,7 +169,7 @@ const BLOCK_FIELD_VALUES = {
 };
 
 /** Keys a section may carry. */
-const SECTION_FIELDS = ['title', 'category', 'content', 'previewType'];
+const SECTION_FIELDS = ['id', 'title', 'category', 'content', 'previewType'];
 
 /**
  * Check the fields the docs surfaces actually read. `parseDoc` is the outer
@@ -161,6 +183,13 @@ const SECTION_FIELDS = ['title', 'category', 'content', 'previewType'];
  * @returns {string[]} problems, each already pointed at a place in the doc
  */
 export function problemsInTopic(doc) {
+  // A namespace doc is valid authoring that only the docs graph reads. Said
+  // plainly, instead of as the topic fields it does not have.
+  if (doc?.type === 'namespace') {
+    return [
+      `"${doc.name}" is a namespace doc. Only the docs graph reads namespace docs, and it is not built yet; remove this file from the docs directory.`,
+    ];
+  }
   /** @type {string[]} */
   const problems = [];
   for (const field of ['name', 'title', 'description']) {
@@ -173,83 +202,119 @@ export function problemsInTopic(doc) {
       `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) {
+    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`);
+  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`);
       }
-    }
-    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) {
-        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`);
+      for (const key of Object.keys(section ?? {})) {
+        if (!SECTION_FIELDS.includes(key)) {
+          problems.push(`${at}.${key}: not a field of a section`);
         }
       }
-      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(', ')}`,
-          );
-        }
+      if (!Array.isArray(section?.content)) {
+        problems.push(`${at}.content: expected an array of blocks`);
+        return;
       }
-      // 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`,
+      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,
-        ...(/** @type {Record<string, string[]>} */ (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`);
-        }
-      }
-    });
-  });
+          // 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`,
+              );
+            }
+          }
+        },
+      );
+    },
+  );
+  // Readers address a section by its key, so two sections sharing one would
+  // make one of them unreachable.
+  problems.push(...sectionKeyProblems(doc.sections));
   return problems;
 }
 
@@ -283,7 +348,9 @@ export async function discoverIntegrationDocs(integration) {
       const full = path.join(dirPath, entry.name);
       if (entry.isDirectory()) {
         scanDir(full);
-      } else if (INTEGRATION_DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+      } else if (
+        INTEGRATION_DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))
+      ) {
         files.push(full);
       }
     }
@@ -298,7 +365,11 @@ export async function discoverIntegrationDocs(integration) {
     try {
       doc = parseDoc(await loadTopicModule(file), path.basename(file));
     } catch (err) {
-      errors.push(new Error(`${path.relative(docsDir, file)}: ${/** @type {any} */ (err).message}`));
+      errors.push(
+        new Error(
+          `${path.relative(docsDir, file)}: ${/** @type {any} */ (err).message}`,
+        ),
+      );
       continue;
     }
     const problems = problemsInTopic(doc);
@@ -315,7 +386,8 @@ export async function discoverIntegrationDocs(integration) {
     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 previous = seen.get(parsed.name);
+    const topicKey = parsed.name.toLowerCase();
+    const previous = seen.get(topicKey);
     if (previous) {
       errors.push(
         new Error(
@@ -324,7 +396,7 @@ export async function discoverIntegrationDocs(integration) {
       );
       continue;
     }
-    seen.set(parsed.name, path.relative(docsDir, file));
+    seen.set(topicKey, path.relative(docsDir, file));
     if (parsed.replaces != null && parsed.extends != null) {
       errors.push(
         new Error(
@@ -349,9 +421,10 @@ export async function discoverIntegrationDocs(integration) {
 }
 
 /**
- * Merge an extension onto a base topic: a section whose title matches one in
- * the base replaces it, a section the base does not have is appended, and the
- * title/description are taken from the extension when it states them.
+ * 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 appended, and title/description
+ * are taken from the extension when it states them.
  *
  * Keyed by section TITLE rather than by position, the way the localization
  * overlays are — position keying grafts an overlay onto whichever section
@@ -365,9 +438,18 @@ export async function discoverIntegrationDocs(integration) {
 export function mergeTopic(base, overlay) {
   const sections = [...(base.sections ?? [])];
   for (const section of overlay.sections ?? []) {
-    const at = sections.findIndex((/** @type {any} */ s) => s.title === section.title);
-    if (at === -1) sections.push(section);
-    else sections[at] = section;
+    const at = findMergeTarget(sections, section);
+    if (at === -1) {
+      sections.push(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.
+      const replaced = sections[at];
+      sections[at] =
+        section.id == null && replaced.id != null
+          ? withSourceTitle({...section, id: replaced.id}, sourceTitle(section))
+          : section;
+    }
   }
   return {
     ...base,
@@ -377,6 +459,41 @@ export function mergeTopic(base, overlay) {
   };
 }
 
+/**
+ * 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,
+  );
+  return sameTitle === -1 ? byKey() : sameTitle;
+}
+
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -399,7 +516,7 @@ export class DocsCatalog {
   static fromBuiltins(builtins = discoverBuiltinTopics()) {
     const catalog = new DocsCatalog();
     for (const [name, file] of Object.entries(builtins)) {
-      catalog.#topics.set(name, {
+      catalog.#topics.set(name.toLowerCase(), {
         name,
         package: BUILTIN_DOCS_PACKAGE,
         path: file,
@@ -455,7 +572,9 @@ export class DocsCatalog {
       // 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;
-      this.#replaceAt(replaced, {
+      const replacedKey = replaced.toLowerCase();
+      const replacementKey = record.name.toLowerCase();
+      this.#replaceAt(replacedKey, {
         name: record.name,
         package: record.package,
         path: record.path,
@@ -466,17 +585,18 @@ export class DocsCatalog {
         // Extensions were authored against the content that just went away.
         extensions: [],
       });
-      if (record.name !== replaced) {
-        this.#aliases.set(replaced, record.name);
+      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 === replaced) this.#aliases.set(from, record.name);
+          if (to === replacedKey) this.#aliases.set(from, replacementKey);
         }
       }
       return warning;
     }
 
-    const existing = this.#topics.get(record.name);
+    const topicKey = record.name.toLowerCase();
+    const existing = this.#topics.get(topicKey);
     if (existing) {
       return {
         code: 'invalid_doc',
@@ -484,7 +604,7 @@ export class DocsCatalog {
         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(record.name, {
+    this.#topics.set(topicKey, {
       name: record.name,
       package: record.package,
       path: record.path,
@@ -519,7 +639,7 @@ export class DocsCatalog {
 
   /** @returns {string[]} every topic name, in read order */
   names() {
-    return [...this.#topics.keys()];
+    return [...this.#topics.values()].map(entry => entry.name);
   }
 
   /** @returns {DocsTopicEntry[]} every topic, in read order */
@@ -536,7 +656,7 @@ export class DocsCatalog {
     /** @type {Map<string, DocsTopicEntry>} */
     const next = new Map();
     for (const [key, value] of this.#topics) {
-      if (key === name) next.set(entry.name, entry);
+      if (key === name.toLowerCase()) next.set(entry.name.toLowerCase(), entry);
       else next.set(key, value);
     }
     this.#topics = next;