@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.e26723d

package/clients/cli/commands/doctor-integration.test.mjs

@@ -21,6 +21,7 @@ import {discoverOwnedComponents} from '../../../foundation/discovery/component-d
 import {discoverBuiltinTopics} from '../../../foundation/discovery/docs-discovery.mjs';
 import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {registerDoctor} from './doctor.mjs';
+import {expectRecordsCarry} from '../../../test-utils/text-projection.mjs';
 
 let tmpDir;
 let previousCwd;
@@ -366,6 +367,10 @@ describe('doctor integration — command', () => {
       const printed = logCalls.join('\n');
       expect(printed).toContain('core_not_found');
       expect(printed).not.toContain('[ok]');
+      // No TypeScript out here either: the props comparison says it skipped.
+      expect(printed).toContain(
+        '[skip] Props not compared: TypeScript is not installed in this project',
+      );
       expect(process.exitCode).toBe(1);
     } finally {
       tmpDir = previousTmp;
@@ -396,6 +401,328 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('components prints each documented prop that differs from the code, and still exits 0', async () => {
+    writeComponentIntegration('AcmeBadge');
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeBadge.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeBadge', displayName: 'AcmeBadge', description: 'Fixture component.', props: [{name: 'label', type: 'string', description: 'Text.'}]};\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeBadge.tsx'),
+      'export function AcmeBadge(props: {label: string}) { return null; }\n',
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'components',
+    ]);
+
+    const output = logCalls.join('\n');
+    expect(output).toMatch(/^kind:\s+required_mismatch$/m);
+    expect(output).toContain(
+      '"label" is required in the code, but the doc does not mark it required.',
+    );
+    expect(output).toContain(
+      '1 prop(s) differ between the docs and the code in 1 of 1 component(s) compared (TypeScript',
+    );
+    expect(output).not.toContain('[ok] Documented prop');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('components compares a hidden doc and a family entry with no record, so their drift is never an [ok]', async () => {
+    writeComponentIntegration('AcmeMenu');
+    const dir = path.join(tmpDir, 'components');
+    fs.writeFileSync(
+      path.join(dir, 'AcmeMenu.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeMenuRoot', displayName: 'AcmeMenuRoot', description: 'Fixture component.', hiddenComponents: ['AcmeMenuItem'], components: [{name: 'AcmeMenuItem', displayName: 'AcmeMenuItem', description: 'Fixture item.', props: [{name: 'label', type: 'string', description: 'Text.'}]}]};\n`,
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeMenu.tsx'),
+      'export function AcmeMenuRoot() { return null; }\nexport function AcmeMenuItem(props: {value?: string}) { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeSecret.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeSecret', displayName: 'AcmeSecret', description: 'Fixture component.', hidden: true, props: [{name: 'tone', type: 'string', description: 'Tone.'}]};\n`,
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeSecret.tsx'),
+      'export function AcmeSecret(props: {size?: number}) { return null; }\n',
+    );
+    process.chdir(tmpDir);
+    const run = async (/** @type {string[]} */ flags) => {
+      logCalls.length = 0;
+      await createProgram().parseAsync([
+        'node',
+        'astryx',
+        ...flags,
+        'doctor',
+        'integration',
+        'components',
+      ]);
+      return logCalls.join('\n');
+    };
+
+    const report = JSON.parse(await run(['--json'])).data.propDrift;
+    const output = await run([]);
+
+    expect(
+      report.findings.map(f => `${f.component}.${f.prop} ${f.kind}`),
+    ).toEqual([
+      'AcmeMenuItem.label not_in_code',
+      'AcmeMenuItem.value not_in_doc',
+      'AcmeSecret.size not_in_doc',
+      'AcmeSecret.tone not_in_code',
+    ]);
+    expect(output).not.toContain('[ok] Documented prop');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('components lists props a mapped type builds from keys it cannot trace, and says the [ok] leaves them out', async () => {
+    writeComponentIntegration('AcmeChip');
+    const dir = path.join(tmpDir, 'components');
+    fs.writeFileSync(
+      path.join(dir, 'AcmeChip.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeChip', displayName: 'AcmeChip', description: 'Fixture.', props: [{name: 'label', type: 'string', description: 'Text.'}]};\n`,
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeChip.tsx'),
+      "export function AcmeChip(props: {label?: string} & {[K in `on${Capitalize<'open'>}`]?: () => void}) { return null; }\n",
+    );
+    process.chdir(tmpDir);
+    const run = async (/** @type {string[]} */ flags) => {
+      logCalls.length = 0;
+      await createProgram().parseAsync([
+        'node',
+        'astryx',
+        ...flags,
+        'doctor',
+        'integration',
+        'components',
+      ]);
+      return logCalls.join('\n');
+    };
+
+    const {propsNotChecked} = JSON.parse(await run(['--json'])).data.propDrift;
+    const output = await run([]);
+
+    expect(propsNotChecked).toEqual([
+      expect.objectContaining({component: 'AcmeChip', props: ['onOpen']}),
+    ]);
+    expect(output).toContain(
+      '[info] Props not checked for a doc entry in 1 component(s):',
+    );
+    expect(output).toContain(
+      'in 1 component(s), apart from the props not checked (TypeScript',
+    );
+  });
+
+  it('components compares the entries of a family doc whose own source is missing', async () => {
+    writeComponentIntegration('AcmeTabs');
+    const dir = path.join(tmpDir, 'components');
+    const entry = (/** @type {string} */ name, /** @type {string} */ prop) =>
+      `{name: '${name}', displayName: '${name}', description: 'Fixture.', props: [{name: '${prop}', type: 'string', description: 'Text.'}]}`;
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTabs.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeTabs', displayName: 'AcmeTabs', description: 'Fixture.', props: [], hiddenComponents: ['AcmeTabsPanel'], components: [${entry('AcmeTabsItem', 'label')}, ${entry('AcmeTabsPanel', 'ghost')}]};\n`,
+    );
+    fs.rmSync(path.join(dir, 'AcmeTabs.tsx'), {force: true});
+    // The package's entry exports the members, so discovery records the
+    // listed one, though the family's own file is missing.
+    for (const name of ['AcmeTabsItem', 'AcmeTabsPanel']) {
+      fs.writeFileSync(
+        path.join(dir, `${name}.tsx`),
+        `export function ${name}(props: {label?: string; open?: boolean}) { return null; }\n`,
+      );
+      fs.appendFileSync(
+        path.join(tmpDir, 'index.ts'),
+        `export {${name}} from './components/${name}';\n`,
+      );
+    }
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'components',
+    ]);
+    const report = JSON.parse(logCalls.join('\n')).data.propDrift;
+
+    expect(
+      report.findings.map(
+        (/** @type {any} */ f) => `${f.component}.${f.prop} ${f.kind}`,
+      ),
+    ).toEqual([
+      'AcmeTabsItem.open not_in_doc',
+      'AcmeTabsPanel.ghost not_in_code',
+      'AcmeTabsPanel.label not_in_doc',
+      'AcmeTabsPanel.open not_in_doc',
+    ]);
+    expect(report.unchecked).toEqual([
+      {
+        component: 'AcmeTabs',
+        doc: 'components/AcmeTabs.doc.mjs',
+        reason: 'no source file for AcmeTabs',
+      },
+    ]);
+  });
+
+  it('components counts two docs of one name as two components, and compares a .doc.ts beside a .doc.mjs', async () => {
+    writeComponentIntegration('AcmeTwin');
+    const dir = path.join(tmpDir, 'components');
+    const doc = (/** @type {string} */ name, /** @type {string} */ prop) =>
+      `export default {type: 'component', name: '${name}', displayName: '${name}', description: 'Fixture.', props: [{name: '${prop}', type: 'string', description: 'Text.'}]};\n`;
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTwin.doc.mjs'),
+      doc('AcmeTwin', 'tone'),
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTwin.doc.ts'),
+      doc('AcmeTwin', 'size'),
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTwin.tsx'),
+      'export function AcmeTwin(props: {label?: string}) { return null; }\n',
+    );
+    for (const folder of ['a', 'b']) {
+      fs.mkdirSync(path.join(dir, folder));
+      fs.writeFileSync(
+        path.join(dir, folder, 'AcmeX.doc.mjs'),
+        doc('AcmeX', folder),
+      );
+      fs.writeFileSync(
+        path.join(dir, folder, 'AcmeX.tsx'),
+        'export function AcmeX() { return null; }\n',
+      );
+    }
+    process.chdir(tmpDir);
+    const run = async (/** @type {string[]} */ flags) => {
+      logCalls.length = 0;
+      await createProgram().parseAsync([
+        'node',
+        'astryx',
+        ...flags,
+        'doctor',
+        'integration',
+        'components',
+      ]);
+      return logCalls.join('\n');
+    };
+
+    const report = JSON.parse(await run(['--json'])).data.propDrift;
+    const output = await run([]);
+
+    expect(
+      report.findings
+        .filter(f => f.kind === 'not_in_code')
+        .map(f => `${f.doc} ${f.prop}`)
+        .sort(),
+    ).toEqual([
+      'components/AcmeTwin.doc.mjs tone',
+      'components/AcmeTwin.doc.ts size',
+      'components/a/AcmeX.doc.mjs a',
+      'components/b/AcmeX.doc.mjs b',
+    ]);
+    expect(output).toMatch(/ in 4 of 4 component\(s\) compared /);
+  });
+
+  it('components prints every field of the props comparison that JSON carries', async () => {
+    writeComponentIntegration('AcmeBadge');
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeBadge.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeBadge', displayName: 'AcmeBadge', description: 'Fixture component.', props: [${[
+        "{name: 'label', type: 'string', description: 'Text.'}",
+        "{name: 'elevation', type: 'number', description: 'Shadow.'}",
+      ].join(', ')}]};\n`,
+    );
+    // `key` is a prop a doc never needs, though the component declares it.
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeBadge.tsx'),
+      "export function AcmeBadge(props: {label: string; tone?: 'neutral' | 'info'; key?: string}) { return null; }\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeLonely.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeLonely', displayName: 'AcmeLonely', description: 'Fixture component.', props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeLonely.tsx'),
+      'export function Other() { return null; }\n',
+    );
+    process.chdir(tmpDir);
+    const run = async (/** @type {string[]} */ flags) => {
+      logCalls.length = 0;
+      await createProgram().parseAsync([
+        'node',
+        'astryx',
+        ...flags,
+        'doctor',
+        'integration',
+        'components',
+      ]);
+      return logCalls.join('\n');
+    };
+
+    const report = JSON.parse(await run(['--json'])).data.propDrift;
+    const output = await run([]);
+
+    expect(report.findings.map(f => `${f.prop} ${f.kind}`)).toEqual([
+      'elevation not_in_code',
+      'label required_mismatch',
+      'tone not_in_doc',
+    ]);
+    expectRecordsCarry(output, report.findings, ['component', 'prop', 'kind']);
+    expectRecordsCarry(output, report.unchecked, ['component', 'reason']);
+    expect(output).toContain(
+      `in 1 of ${report.components} component(s) compared (TypeScript ${report.typescript}).`,
+    );
+  });
+
+  it('components says documented props match when they do', async () => {
+    writeComponentIntegration('AcmeOnlyWidget');
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'components',
+    ]);
+
+    expect(logCalls.join('\n')).toMatch(
+      /\[ok\] Documented prop names and required flags match the code in 1 component\(s\) \(TypeScript \d/,
+    );
+  });
+
+  it('components prints no [ok] for props it could not compare', async () => {
+    writeComponentIntegration('AcmeLonely');
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeLonely.tsx'),
+      'export function Other() { return null; }\n',
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'components',
+    ]);
+
+    const output = logCalls.join('\n');
+    expect(output).toContain(
+      '[info] Props not compared for 1 documented component(s):',
+    );
+    expect(output).not.toContain('[ok] Documented prop');
+  });
+
   it('components exposes conflicts as structured JSON warnings', async () => {
     const coreDir = findCoreDir(tmpDir);
     expect(coreDir).not.toBeNull();
@@ -425,6 +752,71 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('docs resolves a link to a component or a template, its own or Core’s, and still flags one that names no doc', async () => {
+    const page = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(page).toBeDefined();
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components', templates: './templates', docs: './docs'};\n",
+    );
+    for (const dir of ['components', 'templates', 'docs']) {
+      fs.mkdirSync(path.join(tmpDir, dir), {recursive: true});
+    }
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeButton.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeButton.tsx'),
+      'export function AcmeButton() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-card.doc.mjs'),
+      "export default {type: 'block', name: 'Acme card', description: 'A card.'};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-card.tsx'),
+      'export default function Fixture() { return null; }\n',
+    );
+    const text =
+      'Start with {@link component:AcmeButton} or {@link block:acme-card}, ' +
+      'built on {@link @astryxdesign/core:component:Button} and ' +
+      `{@link @astryxdesign/core:page:${page?.dirName}}. Not {@link component:AcmeMissing}.`;
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'using-widgets.doc.mjs'),
+      `export default ${JSON.stringify({
+        type: 'generic',
+        name: 'using-widgets',
+        title: 'Using widgets',
+        description: 'Fixture topic.',
+        sections: [{title: 'Overview', content: [{type: 'prose', text}]}],
+      })};\n`,
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'docs',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    const unresolved = parsed.data.issues
+      .filter(issue => issue.code === 'invalid_doc_graph')
+      .map(issue => issue.message);
+    expect(unresolved).toHaveLength(1);
+    expect(unresolved[0]).toContain('"component:AcmeMissing" names no doc');
+  });
+
   it('docs reports an intentional replacement as info', async () => {
     const [coreTopic] = Object.keys(discoverBuiltinTopics());
     writeDocIntegration({name: 'acme-setup', replaces: coreTopic});

package/clients/cli/commands/doctor.mjs

@@ -173,6 +173,79 @@ function printTemplateConflicts(data) {
   emit(...output);
 }
 
+/**
+ * The documented-props comparison, with every field its JSON carries: a
+ * visible line when it was skipped, the findings (all warnings), the
+ * components it could not read, and how many were compared with which
+ * TypeScript, as an [ok] when nothing differs (never after a failed check).
+ * @param {import('../../../api/integration/authoring-checks.type.mjs').PropDriftReport | undefined} report
+ * @param {boolean} failed
+ */
+function propDriftBlocks(report, failed) {
+  if (!report) return [];
+  if (report.status === 'skipped') {
+    return [text(`[skip] Props not compared: ${report.reason}`)];
+  }
+  const blocks = [];
+  if (report.findings.length > 0) {
+    // Two docs of one name are two components.
+    const components = new Set(
+      report.findings.map(f => `${f.doc}\0${f.component}`),
+    ).size;
+    blocks.push(
+      records(report.findings, {
+        fields: [
+          'severity',
+          'component',
+          'prop',
+          'kind',
+          'message',
+          'doc',
+          'source',
+          'docType',
+          'codeType',
+          'docRequired',
+          'codeRequired',
+        ],
+        format: {severity: statusToken},
+      }),
+      text(
+        `${report.findings.length} prop(s) differ between the docs and the code in ${components} of ${report.components} component(s) compared (TypeScript ${report.typescript}). ` +
+          'These are warnings: update the doc, or the code if the doc is right.',
+      ),
+    );
+  }
+  if (report.unchecked.length > 0) {
+    blocks.push(
+      text(
+        `[info] Props not compared for ${report.unchecked.length} documented component(s):`,
+      ),
+      records(report.unchecked, {fields: ['component', 'doc', 'reason']}),
+    );
+  }
+  const notChecked = report.propsNotChecked ?? [];
+  if (notChecked.length > 0) {
+    blocks.push(
+      text(
+        `[info] Props not checked for a doc entry in ${notChecked.length} component(s):`,
+      ),
+      records(notChecked, {fields: ['component', 'doc', 'reason', 'props']}),
+    );
+  }
+  if (report.findings.length === 0) {
+    const apart =
+      notChecked.length > 0 ? ', apart from the props not checked' : '';
+    blocks.push(
+      text(
+        !failed && report.components > 0
+          ? `[ok] Documented prop names and required flags match the code in ${report.components} component(s)${apart} (TypeScript ${report.typescript}).`
+          : `[info] Props compared in ${report.components} component(s) (TypeScript ${report.typescript}).`,
+      ),
+    );
+  }
+  return blocks;
+}
+
 /**
  * @param {import('../../../api/integration/authoring-checks.type.mjs').IntegrationComponentConflictResponse['data']} data
  */
@@ -205,6 +278,7 @@ function printComponentConflicts(data) {
       ),
     );
   }
+  output.push(...propDriftBlocks(data.propDrift, failed));
   emit(...output);
 }
 

package/clients/cli/commands/theme-build.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set, written beside the family root theme file, which must be inside the working directory (ERR_PATH_TRAVERSAL). Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
@@ -41,7 +41,7 @@ export const doc = {
       flag: '-o, --out <path>',
       param: 'options.out',
       description:
-        'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
+        'Output CSS file path, relative or absolute; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). Every output must resolve inside the working directory, the defaults beside the source too (ERR_PATH_TRAVERSAL). Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',

package/clients/cli/lib/component-format.mjs

@@ -68,8 +68,12 @@ function formatPropsTable(props) {
   for (const p of props) {
     const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
+    // The text projection of the prop doc's `stability` field: an
+    // experimental prop is outside the stable compatibility promise.
+    const stability =
+      p.stability === 'experimental' ? ' **(experimental)**' : '';
     lines.push(
-      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req}${stability} |`,
     );
   }
   return lines.join('\n');

package/foundation/config/project.mjs

@@ -60,6 +60,7 @@ import {
   applyTemplateReplacements,
   effectiveTemplateDiscovery,
   discoverAllUnresolved as discoverTemplates,
+  discoverCoreTemplates,
   discoverIntegrationTemplatesForOne,
 } from '../discovery/template-adapter.mjs';
 import {
@@ -821,6 +822,85 @@ export class Project {
     });
   }
 
+  /**
+   * The components and templates this project reads, as links name them: by
+   * owner provider id, kind, and name (a template by its id).
+   * @returns {Promise<import('../discovery/docs-discovery.mjs').LinkableContributions>}
+   */
+  async #linkableContributions() {
+    /** @type {Map<string, string>} */
+    const providers = new Map([[CORE_PACKAGE, CORE_PACKAGE]]);
+    for (const integration of this.#loadedIntegrations) {
+      if (integration?.name) {
+        providers.set(
+          integration.name,
+          integration.providerId ?? integration.name,
+        );
+      }
+    }
+    const providerOf = (/** @type {string | undefined} */ pkg) =>
+      providers.get(pkg ?? CORE_PACKAGE) ?? pkg ?? CORE_PACKAGE;
+    // An active replacement answers to the Core name it replaces, so a link
+    // to that Core component has to select Core (spec:AST-035 FR11).
+    /** @type {Map<string, string>} */
+    const replacing = new Map();
+    if (this.#loadedIntegrations.length > 0) {
+      const {active} = await resolveComponentReplacements(
+        findCoreDir(this.#cwd),
+        this.#loadedIntegrations,
+      );
+      for (const each of active) {
+        replacing.set(`${each.package}\0${each.name}`, each.target);
+      }
+    }
+    const components = (await this.components()).map(record => {
+      const replaces = replacing.get(`${record.package}\0${record.name}`);
+      return {
+        providerId: providerOf(record.package),
+        package: record.package,
+        name: record.name,
+        docPath: record.docPath,
+        ...(replaces == null ? {} : {replaces}),
+      };
+    });
+    /** @param {any} template @param {string} pkg */
+    const linkable = (template, pkg) => ({
+      providerId: providerOf(pkg),
+      package: pkg,
+      type: template.type,
+      id: template.dirName,
+      name: template.name,
+      ...(template.displayName == null
+        ? {}
+        : {displayName: template.displayName}),
+      ...(template.description == null
+        ? {}
+        : {description: template.description}),
+      ...(typeof template.replaces === 'string'
+        ? {replaces: template.replaces}
+        : {}),
+    });
+    /** @param {any} template */
+    const isPageOrBlock = template =>
+      template.type === 'page' || template.type === 'block';
+    // Every Core template, a replaced one too, since `--package
+    // @astryxdesign/core` still opens it; everyone else's as unqualified
+    // lookups see them, an active replacement with the id it takes over.
+    const templates = [
+      ...(await discoverCoreTemplates())
+        .filter(isPageOrBlock)
+        .map(template => linkable(template, CORE_PACKAGE)),
+      .../** @type {any[]} */ (await this.templates())
+        .filter(
+          template =>
+            isPageOrBlock(template) &&
+            (template.package ?? CORE_PACKAGE) !== CORE_PACKAGE,
+        )
+        .map(template => linkable(template, template.package)),
+    ];
+    return {components, templates};
+  }
+
   /**
    * The CLI's own doc topics plus the ones the configured integrations
    * contribute, resolved into one catalog: additions, replacements (with the
@@ -838,6 +918,8 @@ export class Project {
   async docs() {
     return this.#memo('docs', async () => {
       const catalog = DocsCatalog.fromBuiltins();
+      // Links name component, page, and block docs too (spec:AST-047 FR9).
+      catalog.setContributions(() => this.#linkableContributions());
       let rank = 0;
 
       for (const integration of this.#loadedIntegrations) {

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

@@ -46,6 +46,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/template/integration-template.doc.mjs',
   'doctypes/theme/theme.doc.mjs',
 ];