Skip to content

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

TypeScript

fix(cli): doc links to a component, page, or block resolve (#7668)

Joey2b221e0e707e
diff --git a/.changeset/doc-links-components-templates.md b/.changeset/doc-links-components-templates.md
new file mode 100644
index 0000000000..d67d26e1ba
--- /dev/null
+++ b/.changeset/doc-links-components-templates.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] A doc link to a component, page, or block (`{@link component:AcmeButton}`, `{@link @astryxdesign/core:component:Button}`, `{@link block:acme-card}`) now resolves, and reads as the command that opens it: `astryx component <Name>` or `astryx template <id> --type <page|block>`, with `--package` for anything not from Core. Before, every such link printed as written, and `astryx doctor` and `doctor integration docs` warned that it named no doc, for Core's components as for a package's own. A link that names no component or template still warns, and its hint now searches components or templates instead of topics. A resolved link's `route` is null for these kinds, which no `astryx docs` route opens.
+
+@josephfarina
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index 25a66b99ed..b11a7b24b9 100644
--- a/packages/cli/api/docs/_adapter.mjs
+++ b/packages/cli/api/docs/_adapter.mjs
@@ -53,6 +53,17 @@ import {
selfDocSection,
} from '../../foundation/discovery/authoring-self-docs.mjs';
import {CLI_PROVIDER_ID} from '../../foundation/identity/providers.mjs';
+import {
+ CORE_PACKAGE,
+ discoverOwnedComponents,
+ discoverValidIntegrationComponents,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {loadComponentDoc} from '../../foundation/discovery/component-loader.mjs';
+import {
+ discoverCoreTemplates,
+ discoverIntegrationTemplatesForOne,
+} from '../../foundation/discovery/template-adapter.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
import {AstryxError} from '../error.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
@@ -495,12 +506,205 @@ async function docFinder(catalog, fromProvider) {
};
}
}
+ if (CONTRIBUTED_KINDS.has(parsed.kind)) {
+ const link = await contributedDocLink(
+ catalog,
+ provider,
+ parsed.kind,
+ parsed.name,
+ );
+ if (link)
+ return {link: {target, ...link}, kind: parsed.kind, typed: null};
+ }
+ const searchType =
+ parsed.kind === 'component'
+ ? 'component'
+ : parsed.kind === 'page' || parsed.kind === 'block'
+ ? 'template'
+ : 'doc';
return {
- problem: `"${target}" names no doc. Find it with \`astryx search ${parsed.name} --type doc\`, then name it as \`[<provider>:]<kind>:<name>\`.`,
+ problem: `"${target}" names no doc. Find it with \`astryx search ${parsed.name} --type ${searchType}\`, then name it as \`[<provider>:]<kind>:<name>\`.`,
};
};
}
+/** The doc kinds no docs tree holds: components and templates. */
+const CONTRIBUTED_KINDS = new Set(['component', 'page', 'block']);
+
+/**
+ * The link to a component, page, or block doc (spec:AST-047 FR9). No docs tree
+ * holds these, so a link finds them among the component and template records
+ * the catalog carries, the ones `astryx component` and `astryx template` open,
+ * and reads as that command. A component is named by its export name, a
+ * template by its id; anything but Core's names its package.
+ * @param {DocsCatalog} catalog
+ * @param {string} provider normalized provider id
+ * @param {string} kind `component`, `page`, or `block`
+ * @param {string} name
+ * @returns {Promise<Omit<import('../../foundation/doc-compiler/links.mjs').DocLink, 'target'> | null>}
+ */
+async function contributedDocLink(catalog, provider, kind, name) {
+ const contributions = await catalog.contributions();
+ if (!contributions) return null;
+ const sameProvider = (/** @type {string} */ providerId) => {
+ try {
+ return normalizeProviderId(providerId) === provider;
+ } catch {
+ return false;
+ }
+ };
+ if (kind === 'component') {
+ const record = contributions.components.find(
+ component =>
+ component.name === name && sameProvider(component.providerId),
+ );
+ if (!record) return null;
+ /** @type {any} */
+ let doc = null;
+ try {
+ doc = record.docPath ? await loadComponentDoc(record.docPath) : null;
+ } catch {
+ // The component checks report a doc that does not load; the link
+ // still opens the component.
+ }
+ const entry =
+ doc?.name === name
+ ? doc
+ : doc?.components?.find(
+ (/** @type {any} */ each) => each.name === name,
+ );
+ // Bare, Core's name opens Core's component unless another package ships
+ // the same name or replaces it (spec:AST-035 FR11); then the link selects
+ // Core, as it always selects any other package.
+ const selectPackage =
+ record.package !== CORE_PACKAGE ||
+ contributions.components.some(
+ other =>
+ other.package !== CORE_PACKAGE &&
+ (other.name === name || other.replaces === name),
+ );
+ return {
+ id: createDocId(provider, 'component', name),
+ route: null,
+ title: entry?.displayName ?? name,
+ summary: entry?.description ?? doc?.description ?? '',
+ command: `astryx component ${name}${selectPackage ? ` --package ${record.package}` : ''}`,
+ };
+ }
+ const template = contributions.templates.find(
+ each =>
+ each.type === kind && each.id === name && sameProvider(each.providerId),
+ );
+ if (!template) return null;
+ // The same for a Core template: another package's template of its kind
+ // with its id, or one that replaces it, takes the bare id.
+ const selectPackage =
+ template.package !== CORE_PACKAGE ||
+ contributions.templates.some(
+ other =>
+ other.package !== CORE_PACKAGE &&
+ other.type === template.type &&
+ (other.id === name || other.replaces === name),
+ );
+ return {
+ id: createDocId(provider, template.type, name),
+ route: null,
+ title: template.displayName ?? template.name,
+ summary: template.description ?? '',
+ command: `astryx template ${name} --type ${template.type}${selectPackage ? ` --package ${template.package}` : ''}`,
+ };
+}
+
+/**
+ * The component and template docs one integration package's links can name:
+ * Core's and its own, as `doctor integration docs` checks it before any app
+ * configures it.
+ * @param {any} integration a loaded integration: its name, provider id, roots,
+ * and package directory
+ * @returns {Promise<import('../../foundation/discovery/docs-discovery.mjs').LinkableContributions>}
+ */
+async function packageContributions(integration) {
+ const own = integration.providerId ?? integration.name;
+ /** @type {import('../../foundation/discovery/docs-discovery.mjs').LinkableComponent[]} */
+ const components = [];
+ const coreDir = findCoreDir(integration.__packageDir ?? process.cwd());
+ if (coreDir) {
+ try {
+ for (const record of discoverOwnedComponents(coreDir, [])) {
+ components.push({
+ providerId: CORE_PACKAGE,
+ package: CORE_PACKAGE,
+ name: record.name,
+ docPath: record.docPath,
+ });
+ }
+ } catch {
+ // The components check reports a Core it cannot read.
+ }
+ }
+ if (integration.components) {
+ try {
+ const {components: records} =
+ await discoverValidIntegrationComponents(integration);
+ for (const record of records) {
+ components.push({
+ providerId: own,
+ package: integration.name,
+ name: record.name,
+ docPath: record.docPath,
+ // Declared: this package alone cannot tell whether an app applies
+ // it, so a link to the Core name it names selects Core.
+ ...(typeof record.replaces === 'string'
+ ? {replaces: record.replaces}
+ : {}),
+ });
+ }
+ } catch {
+ // `validate` reports components that do not load.
+ }
+ }
+ /** @type {import('../../foundation/discovery/docs-discovery.mjs').LinkableTemplate[]} */
+ const templates = [];
+ /** @param {any} template @param {string} providerId @param {string} pkg */
+ const addTemplate = (template, providerId, pkg) => {
+ if (template.type !== 'page' && template.type !== 'block') return;
+ templates.push({
+ providerId,
+ package: pkg,
+ type: template.type,
+ id: template.dirName,
+ name: template.name,
+ ...(template.displayName == null
+ ? {}
+ : {displayName: template.displayName}),
+ ...(template.description == null
+ ? {}
+ : {description: template.description}),
+ ...(typeof template.replaces === 'string'
+ ? {replaces: template.replaces}
+ : {}),
+ });
+ };
+ try {
+ for (const template of await discoverCoreTemplates()) {
+ addTemplate(template, CORE_PACKAGE, CORE_PACKAGE);
+ }
+ } catch {
+ // Core templates that do not load leave nothing to link to.
+ }
+ if (integration.templates) {
+ try {
+ const {templates: records} =
+ await discoverIntegrationTemplatesForOne(integration);
+ for (const template of records)
+ addTemplate(template, own, integration.name);
+ } catch {
+ // `validate` reports templates that do not load.
+ }
+ }
+ return {components, templates};
+}
+
/**
* How a doc's links find their targets (spec:AST-047 FR9), as
* {@link docFinder} finds them: each resolves to the link a read shows.
@@ -701,6 +905,7 @@ export async function docsLinkProblems(
*/
export async function packageDocsProblems(integration, discovered) {
const catalog = DocsCatalog.fromBuiltins();
+ catalog.setContributions(() => packageContributions(integration));
for (const record of discovered.records) catalog.add(record);
catalog.addTreeInputs({
namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
@@ -794,6 +999,7 @@ async function namespaceReferenceTarget(catalog, route, lang) {
*/
export async function packageReferenceProblems(integration, discovered) {
const catalog = DocsCatalog.fromBuiltins();
+ catalog.setContributions(() => packageContributions(integration));
for (const record of discovered.records) catalog.add(record);
catalog.addTreeInputs({
namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
diff --git a/packages/cli/api/docs/integrationDocs.test.mjs b/packages/cli/api/docs/integrationDocs.test.mjs
index 2bcca41714..cd44377a1d 100644
--- a/packages/cli/api/docs/integrationDocs.test.mjs
+++ b/packages/cli/api/docs/integrationDocs.test.mjs
@@ -22,6 +22,7 @@ import {docs} from './docs.mjs';
import {search} from '../search/search.mjs';
import {loadDocsCatalog} from './_adapter.mjs';
import {AstryxError} from '../error.mjs';
+import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
const SLOW = 30_000;
@@ -110,6 +111,129 @@ describe('integration-contributed topics', () => {
expect(section.data.title).toBe('Overview');
}, SLOW);
+ it('reads a link to a component or a template as the command that opens it', async () => {
+ scaffold({
+ 'using-widgets.doc.mjs': topic({
+ name: 'using-widgets',
+ title: 'Using widgets',
+ sections: [
+ {
+ title: 'Overview',
+ content: [
+ {
+ type: 'prose',
+ text: 'Start with {@link component:AcmeButton} or {@link block:acme-card}, built on {@link @astryxdesign/core:component:Button}.',
+ },
+ ],
+ },
+ ],
+ }),
+ });
+ const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+ fs.writeFileSync(
+ path.join(pkgDir, 'astryx.integration.mjs'),
+ "export default {components: './components', templates: './templates', docs: './docs'};\n",
+ );
+ fs.mkdirSync(path.join(pkgDir, 'components'));
+ fs.writeFileSync(
+ path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+ "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', props: []};\n",
+ );
+ fs.writeFileSync(
+ path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+ 'export function AcmeButton() { return null; }\n',
+ );
+ fs.mkdirSync(path.join(pkgDir, 'templates'));
+ fs.writeFileSync(
+ path.join(pkgDir, 'templates', 'acme-card.doc.mjs'),
+ "export default {type: 'block', name: 'Acme card', description: 'A card.'};\n",
+ );
+ fs.writeFileSync(
+ path.join(pkgDir, 'templates', 'acme-card.tsx'),
+ 'export default function Fixture() { return null; }\n',
+ );
+
+ const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+ const prose = JSON.stringify(detail.data.sections);
+ expect(prose).toContain('`astryx component AcmeButton --package @acme/widgets`');
+ expect(prose).toContain(
+ '`astryx template acme-card --type block --package @acme/widgets`',
+ );
+ expect(prose).toContain('`astryx component Button`');
+ expect(prose).not.toContain('{@link');
+ }, SLOW);
+
+ it('selects Core in a link only where the bare name would open something else', async () => {
+ const core = await discoverCoreTemplates();
+ const page = core.find(template => template.type === 'page')?.dirName;
+ const block = core.find(template => template.type === 'block')?.dirName;
+ scaffold({
+ 'using-widgets.doc.mjs': topic({
+ name: 'using-widgets',
+ title: 'Using widgets',
+ sections: [
+ {
+ title: 'Overview',
+ content: [
+ {
+ type: 'prose',
+ text:
+ 'Core: {@link @astryxdesign/core:component:Button}, {@link @astryxdesign/core:component:Badge}, ' +
+ `{@link @astryxdesign/core:page:${page}}, {@link @astryxdesign/core:block:${block}}.`,
+ },
+ ],
+ },
+ ],
+ }),
+ });
+ const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+ // The CLI range that turns component replacement on.
+ fs.writeFileSync(
+ path.join(pkgDir, 'package.json'),
+ JSON.stringify({
+ name: '@acme/widgets',
+ version: '1.0.0',
+ peerDependencies: {'@astryxdesign/cli': '>=0.6.7'},
+ peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
+ }),
+ );
+ fs.writeFileSync(
+ path.join(pkgDir, 'astryx.integration.mjs'),
+ "export default {components: './components', templates: './templates', docs: './docs'};\n",
+ );
+ fs.mkdirSync(path.join(pkgDir, 'components'));
+ // AcmeButton replaces Core's Button, so bare `Button` opens AcmeButton.
+ fs.writeFileSync(
+ path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+ "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', replaces: 'Button', props: []};\n",
+ );
+ fs.writeFileSync(
+ path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+ 'export function AcmeButton() { return null; }\n',
+ );
+ // A page template with a Core page's id makes the bare id ambiguous.
+ fs.mkdirSync(path.join(pkgDir, 'templates'));
+ fs.writeFileSync(
+ path.join(pkgDir, 'templates', `${page}.doc.mjs`),
+ "export default {type: 'page', name: 'Acme page', displayName: 'Acme page', description: 'A page.'};\n",
+ );
+ fs.writeFileSync(
+ path.join(pkgDir, 'templates', `${page}.tsx`),
+ 'export default function Fixture() { return null; }\n',
+ );
+
+ const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+ const prose = JSON.stringify(detail.data.sections);
+ expect(prose).toContain('`astryx component Button --package @astryxdesign/core`');
+ expect(prose).toContain('`astryx component Badge`');
+ expect(prose).toContain(
+ `\`astryx template ${page} --type page --package @astryxdesign/core\``,
+ );
+ expect(prose).toContain(`\`astryx template ${block} --type block\``);
+ }, SLOW);
+
it('is invisible to a project that does not configure the integration', async () => {
scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});
const listed = await docs(undefined, undefined, {cwd: tmpDir});
diff --git a/packages/cli/assets/docs/tree/links.doc.mjs b/packages/cli/assets/docs/tree/links.doc.mjs
index 816d4c71bb..6d97f6135e 100644
--- a/packages/cli/assets/docs/tree/links.doc.mjs
+++ b/packages/cli/assets/docs/tree/links.doc.mjs
@@ -36,8 +36,8 @@ export const docs = {
type: 'list',
style: 'unordered',
items: [
- 'The kind is `generic` for a topic or guide, `namespace` for a docs section, and `command` or `function` for a CLI command or API function.',
- 'A link to a component or a template does not resolve. Write its name in backticks instead, such as `AcmeCarousel`.',
+ 'The kind is `generic` for a topic or guide, `namespace` for a docs section, `command` or `function` for a CLI command or API function, `component` for a component, and `page` or `block` for a template.',
+ 'Name a component by its export name and a template by its id. Its link reads as the command that opens it, such as `astryx component AcmeCarousel --package @acme/widgets`.',
'Inside backticks or a code block, link syntax prints as written.',
],
},
diff --git a/packages/cli/clients/cli/commands/doctor-integration.test.mjs b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
index 0939f23d61..65ef2d4501 100644
--- a/packages/cli/clients/cli/commands/doctor-integration.test.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
@@ -752,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});
diff --git a/packages/cli/foundation/config/project.mjs b/packages/cli/foundation/config/project.mjs
index 5d29d31348..66aacd97d6 100644
--- a/packages/cli/foundation/config/project.mjs
+++ b/packages/cli/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) {
diff --git a/packages/cli/foundation/discovery/docs-discovery.mjs b/packages/cli/foundation/discovery/docs-discovery.mjs
index 597dd85542..f163d74248 100644
--- a/packages/cli/foundation/discovery/docs-discovery.mjs
+++ b/packages/cli/foundation/discovery/docs-discovery.mjs
@@ -633,6 +633,38 @@ function findMergeTarget(sections, 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.
*
@@ -644,6 +676,10 @@ function findMergeTarget(sections, section) {
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[]}>} */
@@ -687,6 +723,27 @@ export class DocsCatalog {
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
diff --git a/packages/cli/foundation/doc-compiler/links.mjs b/packages/cli/foundation/doc-compiler/links.mjs
index 22addb6f42..ead57fc8f8 100644
--- a/packages/cli/foundation/doc-compiler/links.mjs
+++ b/packages/cli/foundation/doc-compiler/links.mjs
@@ -47,10 +47,12 @@ const CODE_SPAN = /(`[^`]*`)/;
* @typedef {object} DocLink
* @property {string} target the target as written: `[<provider>:]<kind>:<name>`
* @property {string} id the doc's identity (a DocId)
- * @property {string} route what `astryx docs <route>` opens
+ * @property {string | null} route what `astryx docs <route>` opens; null for a
+ * component, page, or block doc, which no docs route opens
* @property {string} title
* @property {string} summary
- * @property {string} command the command that opens it, `astryx docs <route>`
+ * @property {string} command the command that opens it: `astryx docs <route>`,
+ * or `astryx component` or `astryx template` for a component, page, or block
*/
/**