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.mdnew file mode 100644index 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.++@josephfarinadiff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 pathdiff --git a/packages/cli/foundation/doc-compiler/links.mjs b/packages/cli/foundation/doc-compiler/links.mjsindex 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*//**