@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/foundation/doc-compiler/inputs.test.mjs

@@ -0,0 +1,299 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every authored descriptor becomes exactly one compiler input.
+ *
+ * The repo check is the completeness oracle for what Core and the CLI ship:
+ * every `.doc.mjs` under a descriptor root is read once, and nothing else is.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {Project} from '../config/project.mjs';
+import {CLI_ROOT} from '../fs/paths.mjs';
+import {collectDocInputs, packageSource} from './inputs.mjs';
+
+const REPO_ROOT = path.resolve(CLI_ROOT, '..', '..');
+const SKIP = new Set(['__tests__', '__fixtures__', 'fixtures', 'node_modules']);
+
+/**
+ * Every `.doc.mjs` under a directory, by real path.
+ * @param {string} dir
+ * @param {Set<string>} into
+ */
+function docFiles(dir, into) {
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP.has(entry.name)) docFiles(full, into);
+    } else if (entry.name.endsWith('.doc.mjs')) {
+      into.add(fs.realpathSync(full));
+    }
+  }
+  return into;
+}
+
+let tmpDir;
+
+beforeEach(() => {
+  // Inside the repo, so the project finds this checkout's Core.
+  tmpDir = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-doc-inputs-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', version: '1.0.0'}),
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('collectDocInputs over what this repo ships', () => {
+  it('reads every descriptor Core and the CLI ship exactly once', async () => {
+    const {inputs, problems} = await collectDocInputs(
+      await Project.load(tmpDir),
+    );
+    expect(problems).toEqual([]);
+
+    // What ships comes from the packages themselves, not from the module under
+    // test: Core's source, and every directory the CLI's package.json ships.
+    const shipped = new Set();
+    docFiles(path.join(REPO_ROOT, 'packages', 'core', 'src'), shipped);
+    const {files} = JSON.parse(
+      fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf-8'),
+    );
+    for (const entry of files) {
+      const full = path.join(CLI_ROOT, entry);
+      if (fs.statSync(full).isDirectory()) docFiles(full, shipped);
+    }
+    const read = inputs.map(input => input.file);
+    const rel = (/** @type {string} */ file) => path.relative(REPO_ROOT, file);
+    expect(read.filter(file => !shipped.has(file)).map(rel)).toEqual([]);
+    expect([...shipped].filter(file => !read.includes(file)).map(rel)).toEqual(
+      [],
+    );
+    expect(new Set(read).size).toBe(read.length);
+    expect(new Set(inputs.map(input => input.id)).size).toBe(inputs.length);
+  }, 120_000);
+
+  it('pins the core docs that `component <Name>` reads but the list leaves out', async () => {
+    const {inputs} = await collectDocInputs(await Project.load(tmpDir));
+    // Each is readable by name; listing them would change `component --list`,
+    // so a new entry here is a decision, not a silent drift.
+    expect(
+      inputs
+        .filter(input => input.listed === false)
+        .map(input => input.name)
+        .sort(),
+    ).toEqual([
+      'Chat',
+      'ChatComposerTokenElement',
+      'Code',
+      'ContextMenuItem',
+      'Heading',
+      'Indicator',
+      'Layer',
+      'NavMenu',
+      'Resizable',
+      'SyntaxTheme',
+    ]);
+  });
+
+  it('keys templates by type and directory, not by their display title', async () => {
+    const {inputs} = await collectDocInputs(await Project.load(tmpDir));
+    const byName = new Map(
+      inputs
+        .filter(input => input.root === 'templates')
+        .map(input => [input.name, input]),
+    );
+    // A showcase shares its title with the block it shows; both stay inputs.
+    expect(byName.get('block/BannerStatuses')?.source).toBe(
+      '@astryxdesign/cli/assets/templates/blocks/components/Banner/BannerStatuses.doc.mjs',
+    );
+    expect(byName.get('block/BannerShowcase')?.source).toBe(
+      '@astryxdesign/cli/assets/templates/blocks/components/Banner/BannerShowcase.doc.mjs',
+    );
+  });
+});
+
+describe('collectDocInputs over an integration', () => {
+  /**
+   * @param {string} rel
+   * @param {string} text
+   */
+  function write(rel, text) {
+    const file = path.join(tmpDir, 'node_modules', '@acme', 'kit', rel);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(file, text);
+  }
+
+  it('lists each descriptor once, owned by the package, with where it ships', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        name: 'consumer',
+        version: '1.0.0',
+        dependencies: {'@acme/kit': '^1.0.0'},
+      }),
+    );
+    write(
+      'package.json',
+      JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+    );
+    write(
+      'astryx.integration.mjs',
+      "export default {components: './components', templates: './templates', docs: './docs', themes: './themes'};\n",
+    );
+    write(
+      'components/AcmeCard.tsx',
+      'export function AcmeCard() { return null; }\n',
+    );
+    write(
+      'components/AcmeCard.doc.mjs',
+      "export default {type: 'component', name: 'AcmeCard', displayName: 'Acme Card', usage: {description: 'A card.'}, props: []};\n",
+    );
+    write(
+      'templates/hero.tsx',
+      'export default function Hero() { return null; }\n',
+    );
+    write(
+      'templates/hero.doc.mjs',
+      "export default {type: 'block', name: 'Hero block', description: 'A hero.'};\n",
+    );
+    const topic = (/** @type {object} */ fields) =>
+      `export default ${JSON.stringify({
+        type: 'generic',
+        title: 'Acme',
+        description: 'Acme notes.',
+        sections: [{title: 'Acme', content: [{type: 'prose', text: 'Hi.'}]}],
+        ...fields,
+      })};\n`;
+    write('docs/acme-guide.doc.mjs', topic({name: 'acme-guide'}));
+    write(
+      'docs/theme-notes.doc.mjs',
+      topic({name: 'theme-notes', extends: 'theme'}),
+    );
+    write('themes/ocean/oceanTheme.ts', 'export const oceanTheme = {};\n');
+    write(
+      'themes/ocean/oceanTheme.doc.mjs',
+      "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Blue.', maintained: true};\n",
+    );
+
+    const project = await Project.load(tmpDir);
+    expect(await project.issues()).toEqual([]);
+    const {inputs, problems} = await collectDocInputs(project);
+    expect(problems).toEqual([]);
+    expect(
+      inputs
+        .filter(input => input.owner === '@acme/kit')
+        .map(({id, source, role}) => ({id, source, role})),
+    ).toEqual([
+      {
+        id: '@acme/kit:components:AcmeCard',
+        source: '@acme/kit/components/AcmeCard.doc.mjs',
+        role: undefined,
+      },
+      {
+        id: '@acme/kit:templates:block/hero',
+        source: '@acme/kit/templates/hero.doc.mjs',
+        role: undefined,
+      },
+      {
+        id: '@acme/kit:themes:ocean',
+        source: '@acme/kit/themes/ocean/oceanTheme.doc.mjs',
+        role: undefined,
+      },
+      {
+        id: '@acme/kit:docs:theme+theme-notes',
+        source: '@acme/kit/docs/theme-notes.doc.mjs',
+        role: 'extension',
+      },
+      {
+        id: '@acme/kit:docs:acme-guide',
+        source: '@acme/kit/docs/acme-guide.doc.mjs',
+        role: 'base',
+      },
+    ]);
+  });
+});
+
+describe('collectDocInputs problems', () => {
+  /** @param {object} overrides */
+  const project = overrides =>
+    /** @type {any} */ ({
+      cwd: os.tmpdir(),
+      components: async () => [],
+      templates: async () => [],
+      themes: async () => [],
+      docs: async () => ({entries: () => []}),
+      ...overrides,
+    });
+
+  it('reports a file two roots both claim, and reads it once', async () => {
+    const file = path.join(tmpDir, 'Shared.doc.mjs');
+    fs.writeFileSync(file, 'export default {};\n');
+    const {inputs, problems} = await collectDocInputs(
+      project({
+        components: async () => [
+          {name: 'Shared', package: '@acme/kit', docPath: file},
+        ],
+        templates: async () => [
+          {
+            type: 'block',
+            dirName: 'shared',
+            package: '@acme/kit',
+            docPath: file,
+          },
+        ],
+      }),
+    );
+    expect(
+      inputs.filter(input => input.file === fs.realpathSync(file)),
+    ).toHaveLength(1);
+    expect(problems).toEqual([
+      {
+        code: 'duplicate_file',
+        provider: '@acme/kit',
+        source: expect.stringMatching(/\/Shared\.doc\.mjs$/),
+        message: expect.stringContaining(
+          'is read as templates "block/shared" and as components "Shared"',
+        ),
+      },
+    ]);
+  });
+
+  it('reports two files under one input id', async () => {
+    const one = path.join(tmpDir, 'a', 'Card.doc.mjs');
+    const two = path.join(tmpDir, 'b', 'Card.doc.mjs');
+    for (const file of [one, two]) {
+      fs.mkdirSync(path.dirname(file), {recursive: true});
+      fs.writeFileSync(file, 'export default {};\n');
+    }
+    const {problems} = await collectDocInputs(
+      project({
+        components: async () => [
+          {name: 'Card', package: '@acme/kit', docPath: one},
+          {name: 'Card', package: '@acme/kit', docPath: two},
+        ],
+      }),
+    );
+    expect(problems).toEqual([
+      {
+        code: 'duplicate_id',
+        provider: '@acme/kit',
+        source: expect.stringMatching(/\/Card\.doc\.mjs$/),
+        message: expect.stringContaining('both read as components "Card"'),
+      },
+    ]);
+  });
+});
+
+describe('packageSource', () => {
+  it('names the package a file ships in and its path inside it', () => {
+    expect(
+      packageSource(path.join(CLI_ROOT, 'api', 'docs', 'docs.doc.mjs')),
+    ).toBe('@astryxdesign/cli/api/docs/docs.doc.mjs');
+  });
+});

package/foundation/doc-compiler/ir.d.mts

@@ -7,3 +7,16 @@
  * @returns {import('./compile.mjs').CompiledReferenceNode}
  */
 export function parseCompiledReferenceNode(value: unknown): import("./compile.mjs").CompiledReferenceNode;
+/**
+ * Validate a compiled node of any kind.
+ * @param {unknown} value
+ * @returns {import('./compile.mjs').CompiledDocNode | import('./compile.mjs').CompiledReferenceNode}
+ */
+export function parseCompiledDocNode(value: unknown): import("./compile.mjs").CompiledDocNode | import("./compile.mjs").CompiledReferenceNode;
+/**
+ * Validate a compiled docs bundle: every node, every diagnostic, and one node
+ * per id.
+ * @param {unknown} value
+ * @returns {import('./bundle.mjs').CompiledDocsBundle}
+ */
+export function parseCompiledDocsBundle(value: unknown): import("./bundle.mjs").CompiledDocsBundle;

package/foundation/doc-compiler/ir.mjs

@@ -1,13 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file The compiled-node contract and its sealed parser.
+ * @file The compiled-doc contract and its sealed parsers.
  *
- * @input Any value that claims to be a compiled reference node — typically one
- *   read back from JSON.
+ * @input Any value that claims to be a compiled node or a compiled docs bundle
+ *   — typically one read back from JSON.
  * @output The same value once it validates; a thrown Error naming the problems
- *   otherwise. An unsupported schema version fails with its own message before
- *   anything else is checked.
+ *   otherwise, carrying a compiler diagnostic (`unsupported_schema` or
+ *   `invalid_bundle`). An unsupported schema version fails with its own message
+ *   before anything else is checked.
  * @position The load boundary for compiled nodes that did not come straight
  *   from ./compile.mjs in this process. The value is returned as given, not
  *   rebuilt, so key order (which response JSON follows) survives. A node is
@@ -15,7 +16,8 @@
  */
 
 import {SECTION_KEY_RE} from '../discovery/docs-section-key.mjs';
-import {COMPILED_DOC_SCHEMA_VERSION} from './compile.mjs';
+import {COMPILED_DOC_KINDS, COMPILED_DOC_SCHEMA_VERSION} from './compile.mjs';
+import {diagnostic, diagnosticProblem} from './diagnostics.mjs';
 
 const NODE_FIELDS = new Set([
   'schemaVersion',
@@ -25,6 +27,7 @@ const NODE_FIELDS = new Set([
   'lang',
   'provenance',
   'sourceTitles',
+  'sectionProviders',
   'doc',
 ]);
 const RESOLVED_FIELDS = new Set([
@@ -65,15 +68,13 @@ const isPackageName = value =>
  */
 export function parseCompiledReferenceNode(value) {
   const node = /** @type {any} */ (value);
-  if (node?.schemaVersion !== COMPILED_DOC_SCHEMA_VERSION) {
-    throw new Error(
-      `Compiled doc schema version ${JSON.stringify(node?.schemaVersion)} is not supported; this CLI reads version ${COMPILED_DOC_SCHEMA_VERSION}. Compile the docs again with this CLI.`,
-    );
-  }
+  const skew = schemaVersionProblem(node);
+  if (skew) throw compiledDocError('unsupported_schema', skew);
   const problems = jsonProblems(node, 'node');
   if (problems.length === 0) problems.push(...structureProblems(node));
   if (problems.length > 0) {
-    throw new Error(
+    throw compiledDocError(
+      'invalid_bundle',
       `Invalid compiled doc node: ${problems.slice(0, MAX_PROBLEMS).join('; ')}`,
     );
   }
@@ -170,6 +171,12 @@ function structureProblems(node) {
       'provenance: expected {provider, replaces, extensions} naming packages, not paths',
     );
   }
+  const providers = isRecord(node.sectionProviders)
+    ? node.sectionProviders
+    : null;
+  if (!providers || !Object.values(providers).every(isText)) {
+    problems.push('sectionProviders: expected section key -> provider id');
+  }
   const titles = isRecord(node.sourceTitles) ? node.sourceTitles : null;
   if (!titles || !Object.values(titles).every(isText)) {
     problems.push('sourceTitles: expected section key -> authored title');
@@ -285,3 +292,180 @@ function resolutionProblem(resolved) {
       return `status: expected resolved, unknown-topic or unknown-section, got ${JSON.stringify(resolved.status)}`;
   }
 }
+
+const DOC_NODE_FIELDS = new Set([
+  'schemaVersion',
+  'kind',
+  'stage',
+  'id',
+  'lang',
+  'provenance',
+  'doc',
+]);
+const BUNDLE_FIELDS = new Set([
+  'schemaVersion',
+  'lang',
+  'nodes',
+  'diagnostics',
+]);
+
+/**
+ * A package-relative source, never a location on one machine.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+const isPackageSource = value =>
+  isPackageName(value) &&
+  !/(^|\/)\.\.(\/|$)/.test(/** @type {string} */ (value));
+
+/**
+ * An Error for a value that is not a compiled doc, carrying the diagnostic a
+ * reader reports.
+ * @param {'unsupported_schema' | 'invalid_bundle'} code
+ * @param {string} message
+ * @returns {Error & {diagnostic: import('./diagnostics.mjs').CompilerDiagnostic}}
+ */
+function compiledDocError(code, message) {
+  const error = /** @type {Error & {diagnostic: any}} */ (new Error(message));
+  error.diagnostic = diagnostic(code, {message});
+  return error;
+}
+
+/**
+ * @param {unknown} value
+ */
+function schemaVersionProblem(value) {
+  const version = /** @type {any} */ (value)?.schemaVersion;
+  return version === COMPILED_DOC_SCHEMA_VERSION
+    ? null
+    : `Compiled doc schema version ${JSON.stringify(version)} is not supported; this CLI reads version ${COMPILED_DOC_SCHEMA_VERSION}. Compile the docs again with this CLI.`;
+}
+
+/**
+ * Validate a compiled node of any kind.
+ * @param {unknown} value
+ * @returns {import('./compile.mjs').CompiledDocNode | import('./compile.mjs').CompiledReferenceNode}
+ */
+export function parseCompiledDocNode(value) {
+  const skew = schemaVersionProblem(value);
+  if (skew) throw compiledDocError('unsupported_schema', skew);
+  const problems = nodeProblems(value, 'node');
+  if (problems.length > 0) {
+    throw compiledDocError(
+      'invalid_bundle',
+      `Invalid compiled doc node: ${problems.slice(0, MAX_PROBLEMS).join('; ')}`,
+    );
+  }
+  return /** @type {any} */ (value);
+}
+
+/**
+ * Validate a compiled docs bundle: every node, every diagnostic, and one node
+ * per id.
+ * @param {unknown} value
+ * @returns {import('./bundle.mjs').CompiledDocsBundle}
+ */
+export function parseCompiledDocsBundle(value) {
+  const skew = schemaVersionProblem(value);
+  if (skew) throw compiledDocError('unsupported_schema', skew);
+  const bundle = /** @type {any} */ (value);
+  /** @type {string[]} */
+  const problems = jsonProblems(bundle, 'bundle');
+  if (problems.length === 0) {
+    const unknown = Object.keys(bundle).filter(key => !BUNDLE_FIELDS.has(key));
+    if (unknown.length > 0)
+      problems.push(`unknown fields: ${unknown.join(', ')}`);
+    if (bundle.lang !== null && !isText(bundle.lang)) {
+      problems.push('lang: expected a language or null');
+    }
+    if (!Array.isArray(bundle.nodes)) {
+      problems.push('nodes: expected an array');
+    } else {
+      const ids = new Set();
+      bundle.nodes.forEach(
+        (/** @type {unknown} */ node, /** @type {number} */ index) => {
+          for (const problem of nodeProblems(node, `nodes[${index}]`)) {
+            problems.push(problem);
+          }
+          const id = /** @type {any} */ (node)?.id;
+          if (ids.has(id))
+            problems.push(`nodes[${index}].id: "${id}" appears twice`);
+          ids.add(id);
+        },
+      );
+    }
+    if (!Array.isArray(bundle.diagnostics)) {
+      problems.push('diagnostics: expected an array');
+    } else {
+      bundle.diagnostics.forEach(
+        (/** @type {unknown} */ d, /** @type {number} */ index) => {
+          const problem = diagnosticProblem(d);
+          if (problem) problems.push(`diagnostics[${index}]: ${problem}`);
+        },
+      );
+    }
+  }
+  if (problems.length > 0) {
+    throw compiledDocError(
+      'invalid_bundle',
+      `Invalid compiled docs bundle: ${problems.slice(0, MAX_PROBLEMS).join('; ')}`,
+    );
+  }
+  return bundle;
+}
+
+/**
+ * Problems with one node of any kind, each prefixed with where it is.
+ * @param {unknown} value
+ * @param {string} at
+ * @returns {string[]}
+ */
+function nodeProblems(value, at) {
+  const node = /** @type {any} */ (value);
+  if (node?.schemaVersion !== COMPILED_DOC_SCHEMA_VERSION) {
+    return [`${at}.schemaVersion: expected ${COMPILED_DOC_SCHEMA_VERSION}`];
+  }
+  const json = jsonProblems(node, at);
+  if (json.length > 0) return json;
+  if (node.kind === 'reference') {
+    return structureProblems(node).map(problem => `${at}: ${problem}`);
+  }
+  /** @type {string[]} */
+  const problems = [];
+  const unknown = Object.keys(node).filter(key => !DOC_NODE_FIELDS.has(key));
+  if (unknown.length > 0)
+    problems.push(`${at}: unknown fields: ${unknown.join(', ')}`);
+  if (!COMPILED_DOC_KINDS.includes(node.kind)) {
+    problems.push(
+      `${at}.kind: ${JSON.stringify(node.kind)} is not a compiled doc kind`,
+    );
+  }
+  if (node.stage !== 'lowered')
+    problems.push(`${at}.stage: expected "lowered"`);
+  if (!isText(node.id)) problems.push(`${at}.id: expected an id`);
+  if (node.lang !== null && !isText(node.lang)) {
+    problems.push(`${at}.lang: expected a language or null`);
+  }
+  const provenance = node.provenance;
+  if (
+    !isRecord(provenance) ||
+    Object.keys(provenance).length !== 2 ||
+    !isPackageName(provenance.provider) ||
+    !isPackageSource(provenance.source)
+  ) {
+    problems.push(
+      `${at}.provenance: expected {provider, source} naming a package and a path inside it, not a machine path`,
+    );
+  }
+  if (!isRecord(node.doc) || !isText(node.doc.name)) {
+    problems.push(`${at}.doc: expected a doc with a name`);
+  } else if (
+    (node.kind === 'page' || node.kind === 'block' || node.kind === 'theme') &&
+    node.doc.type !== node.kind
+  ) {
+    problems.push(
+      `${at}.doc.type: a ${node.kind} node holds a ${node.kind} doc`,
+    );
+  }
+  return problems;
+}

package/foundation/doc-compiler/lenses.d.mts

@@ -18,14 +18,17 @@ export function readerSections(node: import("./compile.mjs").CompiledReferenceNo
 export function detailView(node: import("./compile.mjs").CompiledReferenceNode): any;
 /**
  * `docs.index`: what the topic is, and each section's key, title and summary.
+ * The index leaf adds the moves.
  * @param {import('./compile.mjs').CompiledReferenceNode} node
- * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ * @returns {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'>}
  */
-export function indexView(node: import("./compile.mjs").CompiledReferenceNode): import("../../api/docs/docs.type.mjs").DocsIndex;
+export function indexView(node: import("./compile.mjs").CompiledReferenceNode): Omit<import("../../api/docs/docs.type.mjs").DocsIndex, "links">;
 /**
- * `docs.detail.section`: one section with its token references inlined. A
- * referenced section's content takes the reference's place; the section takes
- * the preview type of the last reference that has one, unless it has its own.
+ * `docs.detail.section`: one section with its token references and reference
+ * blocks inlined, so a read returns only the stable block kinds. A referenced
+ * section's content takes the token reference's place; the section takes the
+ * preview type of the last reference that has one, unless it has its own. A
+ * reference block becomes the content it includes (see referenceView).
  * @param {import('./compile.mjs').CompiledReferenceNode} node
  * @param {any} section a linked section of `node`
  * @returns {any}

package/foundation/doc-compiler/lenses.mjs

@@ -62,17 +62,20 @@ export function detailView(node) {
 
 /**
  * `docs.index`: what the topic is, and each section's key, title and summary.
+ * The index leaf adds the moves.
  * @param {import('./compile.mjs').CompiledReferenceNode} node
- * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ * @returns {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'>}
  */
 export function indexView(node) {
   return buildDocsIndexData(node.doc);
 }
 
 /**
- * `docs.detail.section`: one section with its token references inlined. A
- * referenced section's content takes the reference's place; the section takes
- * the preview type of the last reference that has one, unless it has its own.
+ * `docs.detail.section`: one section with its token references and reference
+ * blocks inlined, so a read returns only the stable block kinds. A referenced
+ * section's content takes the token reference's place; the section takes the
+ * preview type of the last reference that has one, unless it has its own. A
+ * reference block becomes the content it includes (see referenceView).
  * @param {import('./compile.mjs').CompiledReferenceNode} node
  * @param {any} section a linked section of `node`
  * @returns {any}
@@ -83,6 +86,10 @@ export function sectionView(node, section) {
   /** @type {string | null} */
   let previewType = null;
   for (const block of section.content) {
+    if (block?.type === 'reference') {
+      content.push(...referenceView(node, block));
+      continue;
+    }
     if (block?.type !== 'token-ref') {
       content.push(structuredClone(block));
       continue;
@@ -125,3 +132,42 @@ export function sectionView(node, section) {
   view.content = content;
   return withSourceTitle(view, authoredTitle(node, section));
 }
+
+/**
+ * A reference block as a read shows it (spec:AST-047 FR9): the content it
+ * includes, then where that content comes from and the command that opens it.
+ * A reference that includes nothing (a summary, or a doc that is not included
+ * whole) shows the doc's title and summary; one whose doc is missing says so
+ * where its content would be, as a token reference does.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @param {any} block a linked reference block
+ * @returns {any[]}
+ */
+function referenceView(node, block) {
+  if (!('link' in block)) {
+    throw new Error(
+      `The reference to "${block.target}" in "${node.id}" was read before it was linked.`,
+    );
+  }
+  const link = block.link;
+  if (link == null) {
+    return [
+      {type: 'prose', text: `[reference: "${block.target}" names no doc]`},
+    ];
+  }
+  const included = (block.content ?? []).map((/** @type {any} */ each) =>
+    structuredClone(each),
+  );
+  if (included.length === 0) {
+    const summary = String(link.summary ?? '').trim();
+    const lead =
+      summary === ''
+        ? link.title
+        : `${link.title}: ${summary}${/[.!?]$/.test(summary) ? '' : '.'}`;
+    return [{type: 'prose', text: `${lead} Read it with \`${link.command}\`.`}];
+  }
+  return [
+    ...included,
+    {type: 'prose', text: `From ${link.title}: \`${link.command}\``},
+  ];
+}