An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): let doc sections include canonical docs (#6768)
Joeyeedc8443f653
diff --git a/.changeset/docs-reference-blocks-in-guides.md b/.changeset/docs-reference-blocks-in-guides.mdnew file mode 100644index 0000000000..8b4f29421d--- /dev/null+++ b/.changeset/docs-reference-blocks-in-guides.md@@ -0,0 +1,9 @@+---+'@astryxdesign/cli': patch+---++[feat] A doc section can include another doc instead of copying it. Put a `reference` block in the section, such as `{type: 'reference', target: '@astryxdesign/cli:schema:integration', projection: {fields: ['components', 'docs']}}`, and `astryx docs` prints those two fields of the integration manifest from the schema's own doc, then the command that opens it.++A reference block includes a schema, command, function, or enum doc. `projection.fields` keeps only the named fields of a schema, and `presentation` is `full` (the default), `compact` (no code blocks), or `summary`. A reference to any other doc shows its title and summary. A read inlines the block, so `--json` still returns only the stable block kinds. `astryx doctor integration docs` fails when a block names a doc, field, or projection it cannot include, and a read marks what is missing. Links also find the CLI's authoring schemas now: `schema:integration` opens `astryx docs authoring integration`.++@josephfarinadiff --git a/docs/specs/AST-047-navigable-output/spec.md b/docs/specs/AST-047-navigable-output/spec.mdindex 0aafa017a4..20fd9d8c08 100644--- a/docs/specs/AST-047-navigable-output/spec.md+++ b/docs/specs/AST-047-navigable-output/spec.md@@ -86,9 +86,14 @@ This record owns the moves a read offers and how they appear in text and JSON.allows, and a name that matches docs of more than one allowed kind is anerror, never a silent pick. Inside a doc's text, a link MUST be written`{@link <target>}` and read as the command that opens its doc; a link that- names no doc MUST print as written. A topic's sections hold only the stable- content blocks, so `reference` and `workflow` blocks (GraphContentBlock)- belong to a namespace doc's `blocks`, which a later phase renders. A target without a+ names no doc MUST print as written. A topic's section MAY hold a `reference`+ block, which includes the doc it names instead of a copy: a read MUST inline+ it as that doc's content (a schema's content narrowed to the fields its+ projection names), then a line naming that doc and the command that opens+ it, so a read still returns only the stable content blocks. A target, field,+ or projection the block cannot include MUST fail the authoring check.+ `workflow` and `collection` blocks (GraphContentBlock) belong to a namespace+ doc's `blocks`, which a later phase renders. A target without aprovider names a doc of the provider that wrote the link: in a topic thatmerges sections from several providers, each section resolves against itsown. The CLI MUST resolvediff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex 03968e817c..57f6898553 100644--- a/packages/cli/api/docs/_adapter.mjs+++ b/packages/cli/api/docs/_adapter.mjs@@ -47,6 +47,12 @@ import {cliDocIndex,cliDocSection,} from '../../foundation/discovery/cli-self-docs.mjs';+import {+ loadAuthoringSelfDocs,+ schemaFieldTable,+ selfDocSection,+} from '../../foundation/discovery/authoring-self-docs.mjs';+import {CLI_PROVIDER_ID} from '../../foundation/identity/providers.mjs';import {AstryxError} from '../error.mjs';import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';@@ -119,6 +125,7 @@ function lowerRawTopic(catalog, entry, lang = null) {* @typedef {import('../../foundation/doc-compiler/tree.mjs').TreeNode} TreeNode* @typedef {import('../../foundation/doc-compiler/links.mjs').LinkProblem} LinkProblem* @typedef {import('../../foundation/doc-compiler/links.mjs').LinkResolver} LinkResolver+ * @typedef {import('../../foundation/doc-compiler/links.mjs').DocIncluder} DocIncluder* @typedef {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} DocsTopicEntry*/@@ -146,8 +153,9 @@ function providerOf(entry) {/*** One topic, lowered for `lang` with every link between docs resolved* (spec:AST-047 FR9): an inline `{@link <target>}` reads as the command that- * opens its doc, and a `reference` or `workflow` block carries the doc it- * names. Memoized per catalog and frozen, like the lowered node.+ * opens its doc, and a `reference` block carries the doc it names and the+ * `content` it includes of it. Memoized per catalog and frozen, like the+ * lowered node.* @param {DocsCatalog} catalog* @param {DocsTopicEntry} entry* @param {string | null} [lang]@@ -183,16 +191,19 @@ function linkTopic(catalog, entry, lang) {if (!linked) {linked = (async () => {const raw = await lowerRawTopic(catalog, entry, lang);- /** @type {Map<string, LinkResolver>} */- const resolvers = new Map();+ /** @type {Map<string, {resolve: LinkResolver, include: DocIncluder}>} */+ const linkers = new Map();/** @param {string} provider */- const resolverFor = async provider => {- let resolve = resolvers.get(provider);- if (!resolve) {- resolve = await linkResolver(catalog, provider);- resolvers.set(provider, resolve);+ const linkerFor = async provider => {+ let linker = linkers.get(provider);+ if (!linker) {+ linker = {+ resolve: await linkResolver(catalog, provider),+ include: await docIncluder(catalog, provider),+ };+ linkers.set(provider, linker);}- return resolve;+ return linker;};/** @type {LinkProblem[]} */const problems = [];@@ -202,12 +213,14 @@ function linkTopic(catalog, entry, lang) {// base topic's.for (const section of raw.doc.sections) {const provider = raw.sectionProviders?.[section.id];+ const {resolve, include} = await linkerFor(+ provider == null ? providerOf(entry) : normalizeProviderId(provider),+ );const linked = await linkBlocks(section.content,- await resolverFor(- provider == null ? providerOf(entry) : normalizeProviderId(provider),- ),+ resolve,{section: section.id ?? section.title},+ include,);problems.push(...linked.problems);sections.push({...section, content: linked.content});@@ -332,15 +345,52 @@ function identitiesOf(tree) {return index;}+/**+ * The CLI's authoring docs, by kind and name. `astryx docs authoring` reads+ * each as one section keyed by its name, so a link to one opens that section.+ * Loaded once per process, like the CLI's tree files.+ * @type {Promise<Map<string, any>> | undefined}+ */+let authoringDocs;++/**+ * The CLI authoring doc a link names, while `astryx docs authoring` is the+ * CLI's own topic.+ * @param {DocsCatalog} catalog+ * @param {string} kind+ * @param {string} name+ * @returns {Promise<any | null>}+ */+async function authoringDoc(catalog, kind, name) {+ if (catalog.resolve('authoring')?.package !== CLI_PROVIDER_ID) return null;+ authoringDocs ??= loadAuthoringSelfDocs().then(+ ({loaded}) =>+ new Map(loaded.map(({doc}) => [`${doc.type}\u0000${doc.name}`, doc])),+ );+ return (await authoringDocs).get(`${kind}\u0000${name}`) ?? null;+}++/**+ * A doc a link found: what a read shows of the link, and the typed doc behind+ * it when a reference block can include it.+ * @typedef {object} FoundDoc+ * @property {import('../../foundation/doc-compiler/links.mjs').DocLink} link+ * @property {string} kind the doc's kind+ * @property {{doc: any, providerId: string, tree: boolean} | null} typed a+ * schema, command, function, or enum doc: a leaf of the docs tree (`tree`),+ * or a section of `astryx docs authoring`; null for any other kind+ */+/*** How a doc's links find their targets (spec:AST-047 FR9): a doc in the- * project's docs tree by its identity, or a flat topic by its provider and- * name. A target that matches neither is a problem, never a guess.+ * project's docs tree by its identity, a CLI authoring doc (a section of+ * `astryx docs authoring`), or a flat topic by its provider and name. A+ * target that matches none is a problem, never a guess.* @param {DocsCatalog} catalog* @param {string} fromProvider the provider id of the doc the links sit in- * @returns {Promise<LinkResolver>}+ * @returns {Promise<(target: string) => Promise<FoundDoc | {problem: string}>>}*/-export async function linkResolver(catalog, fromProvider) {+async function docFinder(catalog, fromProvider) {const identities = identitiesOf(await projectTree(catalog));return async target => {const parsed = parseLinkTarget(target);@@ -356,12 +406,36 @@ export async function linkResolver(catalog, fromProvider) {const node = identities.get(identityKey(provider, parsed.kind, parsed.name));if (node) {return {- target,- id: /** @type {string} */ (node.id),- route: node.route,- title: node.title,- summary: node.summary,- command: `astryx docs ${node.route}`,+ link: {+ target,+ id: /** @type {string} */ (node.id),+ route: node.route,+ title: node.title,+ summary: node.summary,+ command: `astryx docs ${node.route}`,+ },+ kind: node.kind,+ typed: node.ref?.selfDoc+ ? {doc: node.ref.selfDoc, providerId: node.providerId, tree: true}+ : null,+ };+ }+ const authored =+ provider === CLI_PROVIDER_ID+ ? await authoringDoc(catalog, parsed.kind, parsed.name)+ : null;+ if (authored) {+ return {+ link: {+ target,+ id: createDocId(provider, authored.type, authored.name),+ route: 'authoring',+ title: authored.displayName ?? authored.name,+ summary: authored.description ?? '',+ command: `astryx docs authoring ${authored.name}`,+ },+ kind: parsed.kind,+ typed: {doc: authored, providerId: CLI_PROVIDER_ID, tree: false},};}if (parsed.kind === 'generic') {@@ -383,12 +457,16 @@ export async function linkResolver(catalog, fromProvider) {// link still opens it.}return {- target,- id: createDocId(provider, 'generic', parsed.name),- route: entry.name,- title,- summary,- command: `astryx docs ${entry.name}`,+ link: {+ target,+ id: createDocId(provider, 'generic', parsed.name),+ route: entry.name,+ title,+ summary,+ command: `astryx docs ${entry.name}`,+ },+ kind: 'generic',+ typed: null,};}}@@ -398,20 +476,158 @@ export async function linkResolver(catalog, fromProvider) {};}+/**+ * 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.+ * @param {DocsCatalog} catalog+ * @param {string} fromProvider the provider id of the doc the links sit in+ * @returns {Promise<LinkResolver>}+ */+export async function linkResolver(catalog, fromProvider) {+ const find = await docFinder(catalog, fromProvider);+ return async target => {+ const found = await find(target);+ return 'problem' in found ? found : found.link;+ };+}++/** How a problem names a doc kind that a reference block cannot include. */+const KIND_NAMES = /** @type {Record<string, string>} */ ({+ generic: 'topic',+ namespace: 'namespace',+});++/**+ * How a topic's reference blocks include the docs they name (spec:AST-047+ * FR9): a schema, command, function, or enum doc as `astryx docs` prints+ * it, narrowed by the block's projection and presentation, with the included+ * doc's own links resolved against its own provider. Any other doc shows its+ * title and summary. Each part a block names that it cannot include is a+ * problem, and a read marks where it is missing; a target that names no doc+ * is the resolver's problem.+ * @param {DocsCatalog} catalog+ * @param {string} fromProvider the provider id of the doc the blocks sit in+ * @returns {Promise<DocIncluder>}+ */+async function docIncluder(catalog, fromProvider) {+ const find = await docFinder(catalog, fromProvider);+ const tree = await projectTree(catalog);+ return async block => {+ const found = await find(block.target);+ if ('problem' in found) return {content: [], problems: []};+ return includedContent(catalog, tree, block, found);+ };+}++/**+ * What one reference block includes of the doc it found.+ * @param {DocsCatalog} catalog+ * @param {DocsTree} tree+ * @param {any} block+ * @param {FoundDoc} found+ * @returns {Promise<{content: any[], problems: string[]}>}+ */+async function includedContent(catalog, tree, block, found) {+ /** @type {string[]} */+ const problems = [];+ const {fields, sections} = block.projection ?? {};+ const presentation = block.presentation ?? 'full';+ if (sections != null) {+ problems.push(+ 'projection.sections: a reference block does not include topic sections; reference a schema, command, function, or enum doc, and name the fields of a schema with projection.fields',+ );+ }+ const typed = found.typed;+ if (typed == null) {+ // A reference shows any other doc only by its title and summary.+ if (fields != null || (block.presentation ?? 'summary') !== 'summary') {+ problems.push(+ `"${block.target}" is a ${KIND_NAMES[found.kind] ?? `${found.kind} doc`}, which a reference block shows only by its title and summary; remove the projection and the presentation, or reference a schema, command, function, or enum doc`,+ );+ }+ return {content: [], problems};+ }+ if (presentation === 'summary') {+ if (fields != null) {+ problems.push(+ "projection.fields: a summary includes no fields; remove projection.fields or presentation: 'summary'",+ );+ }+ return {content: [], problems};+ }+ /** @type {any[]} */+ let content;+ if (fields != null && typed.doc.type === 'schema') {+ /** @type {Map<string, any>} */+ const byName = new Map(+ (typed.doc.fields ?? []).map((/** @type {any} */ field) => [+ field.name,+ field,+ ]),+ );+ const selected = [];+ /** @type {any[]} */+ const missing = [];+ for (const name of fields) {+ const field = byName.get(name);+ if (field) {+ selected.push(field);+ continue;+ }+ problems.push(+ `projection.fields: "${name}" is not a field of ${found.link.title} (${block.target}). Its fields: ${[...byName.keys()].join(', ')}`,+ );+ missing.push({+ type: 'prose',+ text: `[reference: field "${name}" not found in "${block.target}"]`,+ });+ }+ const table = schemaFieldTable(selected);+ content = [...(table ? [table] : []), ...missing];+ } else {+ if (fields != null) {+ problems.push(+ `projection.fields: names the fields of a schema doc, and "${block.target}" is a ${typed.doc.type} doc; remove it to include the whole doc`,+ );+ }+ content = typed.tree+ ? cliDocSection(typed.doc, typedDocIndex(tree)).content+ : selfDocSection(typed.doc).content;+ }+ if (presentation === 'compact') {+ content = content.filter(each => each?.type !== 'code');+ }+ // The included doc's own links resolve against its own provider. A link in+ // it that names no doc is that doc's problem, reported where it is written.+ const linked = await linkBlocks(+ content,+ await linkResolver(catalog, typed.providerId),+ );+ return {content: linked.content, problems};+}+/*** Every link in the project's docs that names no doc: in each topic, each* guide the tree places, and each typed doc.* @param {DocsCatalog} catalog* @param {DocsTree} tree- * @param {{owner?: string}} [options] `owner`: only the docs this package owns+ * @param {{owner?: string, references?: boolean}} [options] `owner`: only the+ * docs this package owns. `references`: instead of the links, each reference+ * block that cannot include what it names; a reader loses that content,+ * where a link that names no doc still prints as written* @returns {Promise<string[]>}*/-export async function docsLinkProblems(catalog, tree, {owner} = {}) {+export async function docsLinkProblems(+ catalog,+ tree,+ {owner, references = false} = {},+) {/** @type {string[]} */const problems = [];/** @param {string} where @param {LinkProblem[]} found */const note = (where, found) => {for (const problem of found) {+ if ((problem.include === true) !== references) continue;problems.push(`${where}${problem.section ? ` \u00a7 ${problem.section}` : ''}: ${problem.message}`,);@@ -487,6 +703,28 @@ export function referenceTargets(catalog, lang) {};}+/**+ * Each reference block in one integration's docs that cannot include what it+ * names (spec:AST-047 FR9): a target that names no doc, a field its schema+ * does not have, or a projection its doc cannot take. A reader would lose+ * that content, so `astryx doctor integration docs` fails on each.+ * @param {{name: string}} integration+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered+ * @returns {Promise<string[]>}+ */+export async function packageReferenceProblems(integration, discovered) {+ const catalog = DocsCatalog.fromBuiltins();+ for (const record of discovered.records) catalog.add(record);+ catalog.addTreeInputs({+ namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),+ guides: discovered.guides.map(input => ({...input, rank: 1})),+ });+ return docsLinkProblems(catalog, await projectTree(catalog), {+ owner: integration.name,+ references: true,+ });+}+/*** One topic, compiled for `lang`: lowered, then every token reference linked.* @param {DocsCatalog} catalog@@ -535,6 +773,20 @@ const typedDocIndexes = new WeakMap();*/export async function nodeContent(catalog, tree, node) {if (!node.ref?.selfDoc) return {content: [], problems: []};+ const resolve = await linkResolver(catalog, node.providerId);+ return linkBlocks(+ cliDocSection(node.ref.selfDoc, typedDocIndex(tree)).content,+ resolve,+ );+}++/**+ * The index a typed doc's content reads its cross-links from: every typed doc+ * in the tree. Built once per tree.+ * @param {DocsTree} tree+ * @returns {ReturnType<typeof cliDocIndex>}+ */+function typedDocIndex(tree) {let index = typedDocIndexes.get(tree);if (!index) {index = cliDocIndex(@@ -544,8 +796,7 @@ export async function nodeContent(catalog, tree, node) {);typedDocIndexes.set(tree, index);}- const resolve = await linkResolver(catalog, node.providerId);- return linkBlocks(cliDocSection(node.ref.selfDoc, index).content, resolve);+ return index;}/**diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjsindex c098207b79..4d25e28573 100644--- a/packages/cli/api/docs/docs.doc.mjs+++ b/packages/cli/api/docs/docs.doc.mjs@@ -20,7 +20,8 @@ export const doc = {'ReferenceDoc, and `index: true` returns its section index (each ' +'section\'s key, title, and summary); a topic plus a section returns ' +'that one section. Token-ref blocks are ' +- 'inlined in every read. The topic set is the CLI\'s own docs plus the ' ++ 'inlined in every read, and so is a section\'s reference block: the doc it ' ++ 'includes, then the command that opens that doc. The topic set is the CLI\'s own docs plus the ' +'ones the project\'s configured integrations contribute, including any ' +'topic an integration replaces or extends, so it depends on the cwd. ' +'A route opens a node of the docs tree instead: a namespace such as ' +@@ -97,7 +98,7 @@ export const doc = {{type: 'docs.detail',description:- "One topic's full ReferenceDoc, with token-ref blocks inlined, plus links.",+ "One topic's full ReferenceDoc, with token-ref and reference blocks inlined, plus links.",},{type: 'docs.index',@@ -107,7 +108,7 @@ export const doc = {{type: 'docs.detail.section',description:- 'One ReferenceSection of the topic, found by key or title, with token-ref blocks inlined.',+ 'One ReferenceSection of the topic, found by key or title, with token-ref and reference blocks inlined.',},{type: 'docs.node',diff --git a/packages/cli/api/docs/docs.type.mjs b/packages/cli/api/docs/docs.type.mjsindex bb202e9d4a..6ba3c5490e 100644--- a/packages/cli/api/docs/docs.type.mjs+++ b/packages/cli/api/docs/docs.type.mjs@@ -56,15 +56,31 @@* astryx --json docs <topic>* @typedef {object} DocsDetailResponse* @property {'docs.detail'} type- * @property {import('@astryxdesign/cli/authoring').ReferenceDoc & {links: DocsLinks}} data+ * @property {DocsReadDoc & {links: DocsLinks}} data* the whole doc, and the moves from it*/+/**+ * A topic section as a read returns it. A read inlines each token reference+ * and each `reference` block the author wrote, so its content holds only the+ * stable ReferenceContentBlock kinds.+ * @typedef {Omit<import('@astryxdesign/cli/authoring').ReferenceSection, 'content'>+ * & {content: import('@astryxdesign/cli/authoring').ReferenceContentBlock[]}} DocsReadSection+ */++/**+ * A topic as a read returns it: every section a {@link DocsReadSection}.+ * @typedef {Omit<import('@astryxdesign/cli/authoring').ReferenceDoc, 'sections'>+ * & {sections: DocsReadSection[]}} DocsReadDoc+ */+/*** The doc a link opens (spec:AST-047 FR9). A docs read resolves every link:- * an inline `{@link <target>}` reads as `link.command`, a `reference` block- * carries `link` (null when the target names no doc), and each `workflow` step- * carries `links`, one per reference.+ * an inline `{@link <target>}` reads as `link.command`, a `reference` block in+ * a namespace doc carries `link` (null when the target names no doc), and each+ * `workflow` step carries `links`, one per reference. A topic read inlines a+ * section's `reference` block as the doc it includes, then a line naming where+ * that comes from and the command that opens it.* @typedef {import('../../foundation/doc-compiler/links.mjs').DocLink} DocLink*/@@ -110,7 +126,7 @@* astryx --json docs <topic> <section>* @typedef {object} DocsDetailSectionResponse* @property {'docs.detail.section'} type- * @property {import('@astryxdesign/cli/authoring').ReferenceSection & {links: DocsLinks}} data+ * @property {DocsReadSection & {links: DocsLinks}} data* the section, and the moves from it: up to its topic's index, and across to* the sections before and after it*/diff --git a/packages/cli/api/docs/integration-tree.test.mjs b/packages/cli/api/docs/integration-tree.test.mjsindex 620e172cd3..6ea3c7f704 100644--- a/packages/cli/api/docs/integration-tree.test.mjs+++ b/packages/cli/api/docs/integration-tree.test.mjs@@ -151,7 +151,15 @@ describe('integration docs in the docs tree', () => {title: 'Broken',description: 'A topic whose block no topic may hold.',sections: [- {title: 'Only', content: [{type: 'reference', target: 'generic:setup'}]},+ {+ title: 'Only',+ content: [+ {+ type: 'workflow',+ steps: [{title: 'Set up', references: ['generic:setup']}],+ },+ ],+ },],},});diff --git a/packages/cli/api/docs/reference-blocks.test.mjs b/packages/cli/api/docs/reference-blocks.test.mjsnew file mode 100644index 0000000000..f6d4da54e9--- /dev/null+++ b/packages/cli/api/docs/reference-blocks.test.mjs@@ -0,0 +1,406 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A topic section's `reference` block (spec:AST-047 FR9). A read+ * includes the doc it names from that doc's own source, narrowed by its+ * projection, and still returns only the stable block kinds. A block that+ * cannot include what it names fails the authoring check.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import {docs} from './docs.mjs';+import {+ builtinCatalog,+ docsLinkProblems,+ linkResolver,+ loadDocsCatalog,+ projectTree,+} from './_adapter.mjs';+import {integrationDocConflicts} from '../integration/authoring-checks.mjs';+import {checkDocsTree} from '../doctor/doctor.mjs';+import {createDocId} from '../../foundation/identity/provider-identity.mjs';+import {CLI_PROVIDER_ID} from '../../foundation/identity/providers.mjs';+import {runCli} from '../../test-utils/run-cli.mjs';++const SLOW = 60_000;++/** The block kinds a read returns: a token reference and a reference block are inlined. */+const READ_KINDS = new Set(['prose', 'heading', 'code', 'table', 'list']);++/** The primary fixture: two fields of the CLI's integration manifest schema. */+const MANIFEST_FIELDS = {+ type: 'reference',+ target: '@astryxdesign/cli:schema:integration',+ projection: {fields: ['components', 'docs']},+};++/** A topic whose sections include canonical CLI docs. */+const SETUP = {+ type: 'generic',+ name: 'acme-setup',+ title: 'Acme setup',+ description: 'Set up the Acme kit.',+ sections: [+ {+ id: 'manifest',+ title: 'Point the manifest at your folders',+ content: [+ {type: 'prose', text: 'Add these fields to astryx.integration.mjs.'},+ MANIFEST_FIELDS,+ ],+ },+ {+ id: 'check',+ title: 'Check the docs',+ content: [+ {type: 'prose', text: 'Run the check before you publish.'},+ {+ type: 'reference',+ target: '@astryxdesign/cli:command:doctor integration docs',+ presentation: 'compact',+ },+ ],+ },+ {+ id: 'more',+ title: 'Read more',+ content: [+ {+ type: 'reference',+ target: '@astryxdesign/cli:function:docs',+ presentation: 'summary',+ },+ {type: 'reference', target: '@astryxdesign/cli:generic:theme'},+ ],+ },+ ],+};++/** A topic whose reference blocks each name something they cannot include. */+const BROKEN = {+ type: 'generic',+ name: 'acme-broken',+ title: 'Acme broken',+ description: 'References that include nothing.',+ sections: [+ {+ id: 'gaps',+ title: 'Gaps',+ content: [+ {+ type: 'reference',+ target: '@astryxdesign/cli:schema:integration',+ projection: {fields: ['components', 'nope']},+ },+ {type: 'reference', target: '@astryxdesign/cli:schema:nothing'},+ {+ type: 'reference',+ target: '@astryxdesign/cli:command:doctor',+ projection: {fields: ['--json']},+ },+ {+ type: 'reference',+ target: '@astryxdesign/cli:schema:config',+ projection: {sections: ['fields']},+ },+ {+ type: 'reference',+ target: '@astryxdesign/cli:generic:theme',+ presentation: 'full',+ },+ ],+ },+ ],+};++/** @type {string} */+let tmpDir;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-reference-test-'));+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++/**+ * A consumer project that configures `@acme/kit`, which ships these docs.+ * @param {Record<string, object>} files doc file name -> doc+ */+function scaffold(files) {+ fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "consumer"}\n');+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.config.mjs'),+ "export default {integrations: ['@acme/kit']};\n",+ );+ const kit = path.join(tmpDir, 'node_modules', '@acme', 'kit');+ fs.mkdirSync(path.join(kit, 'docs'), {recursive: true});+ fs.writeFileSync(+ path.join(kit, 'package.json'),+ JSON.stringify({name: '@acme/kit', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(kit, 'astryx.integration.mjs'),+ "export default {docs: './docs'};\n",+ );+ for (const [file, doc] of Object.entries(files)) {+ fs.writeFileSync(+ path.join(kit, 'docs', file),+ `export const docs = ${JSON.stringify(doc, null, 2)};\n`,+ );+ }+}++/**+ * @param {string} topic+ * @param {string} [section]+ */+async function read(topic, section) {+ return (await docs(topic, section, {cwd: tmpDir})).data;+}++describe('a reference block in a topic section', () => {+ it(+ 'includes the fields a schema reference names, then where they come from',+ async () => {+ scaffold({'acme-setup.doc.mjs': SETUP});+ const section = await read('acme-setup', 'manifest');+ expect(section.content.map(block => block.type)).toEqual([+ 'prose',+ 'table',+ 'prose',+ ]);+ const table = section.content[1];+ expect(table.headers).toEqual([+ 'Field',+ 'Type',+ 'Required',+ 'Description',+ ]);+ // The fields the block names, in the order it names them.+ expect(table.rows.map(row => row[0])).toEqual(['components', 'docs']);+ expect(section.content[2]).toEqual({+ type: 'prose',+ text: 'From Astryx Integration: `astryx docs authoring integration`',+ });+ },+ SLOW,+ );++ it(+ "reads the included fields from the schema's own doc, not a copy",+ async () => {+ scaffold({'acme-setup.doc.mjs': SETUP});+ const included = (await read('acme-setup', 'manifest')).content[1].rows;+ const schema = (await docs('authoring', 'integration')).data.content.find(+ block => block.type === 'table',+ );+ expect(included).toEqual(+ MANIFEST_FIELDS.projection.fields.map(name =>+ schema.rows.find(row => row[0] === name),+ ),+ );+ },+ SLOW,+ );++ it(+ 'returns only the stable block kinds in every read, in JSON and in each language',+ async () => {+ scaffold({'acme-setup.doc.mjs': SETUP});+ for (const lang of [null, 'zh']) {+ const whole = (await docs('acme-setup', undefined, {cwd: tmpDir, lang}))+ .data;+ const kinds = new Set(+ whole.sections.flatMap(section => section.content.map(b => b.type)),+ );+ expect([...kinds].filter(kind => !READ_KINDS.has(kind))).toEqual([]);+ for (const {id} of whole.sections) {+ const one = (await docs('acme-setup', id, {cwd: tmpDir, lang})).data;+ expect(one.content.every(block => READ_KINDS.has(block.type))).toBe(+ true,+ );+ }+ }+ },+ SLOW,+ );++ it(+ 'includes a whole command doc, without code when compact; a summary and a topic show as one line',+ async () => {+ scaffold({'acme-setup.doc.mjs': SETUP});+ const check = (await read('acme-setup', 'check')).content;+ expect(check.some(block => block.type === 'code')).toBe(false);+ expect(check.find(block => block.type === 'table')?.headers).toEqual([+ 'Argument',+ 'Description',+ ]);+ // The included doc's own links resolve against its own provider.+ expect(+ check.some(+ block =>+ block.type === 'prose' &&+ block.text.includes(+ 'Read it with `astryx docs cli/api/functions/integration-doc-conflicts`.',+ ),+ ),+ ).toBe(true);+ expect(check.at(-1)).toEqual({+ type: 'prose',+ text: 'From astryx doctor integration docs: `astryx docs cli/commands/doctor-integration-docs`',+ });+ const more = (await read('acme-setup', 'more')).content;+ expect(more).toHaveLength(2);+ expect(more[0].text).toMatch(+ /^docs\(\): Read the reference docs: .* Read it with `astryx docs cli\/api\/functions\/docs`\.$/,+ );+ expect(more[1].text).toMatch(+ /^Theme System: .* Read it with `astryx docs theme`\.$/,+ );+ },+ SLOW,+ );++ it(+ 'prints the included content in text',+ async () => {+ scaffold({'acme-setup.doc.mjs': SETUP});+ const {status, stdout} = await runCli(+ ['docs', 'acme-setup', 'manifest'],+ tmpDir,+ );+ expect(status).toBe(0);+ expect(stdout).toMatch(/^Field +\| Type +\| Required +\| Description/m);+ expect(stdout).toMatch(/^components +\| string +\| no +\| /m);+ expect(stdout).toContain(+ 'From Astryx Integration: `astryx docs authoring integration`',+ );+ },+ SLOW,+ );+});++describe('a reference block that includes what it names', () => {+ it(+ 'passes the authoring check',+ async () => {+ scaffold({'acme-setup.doc.mjs': SETUP});+ const {data} = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ expect(data.issues).toEqual([]);+ const cli = await runCli(+ ['doctor', 'integration', 'docs', '@acme/kit'],+ tmpDir,+ );+ expect(cli.status).toBe(0);+ },+ SLOW,+ );+});++describe('what a reference block names', () => {+ it('resolves a CLI authoring schema by identity, to its section of `astryx docs authoring`', async () => {+ const resolve = await linkResolver(builtinCatalog(), CLI_PROVIDER_ID);+ expect(await resolve('schema:integration')).toMatchObject({+ id: createDocId(CLI_PROVIDER_ID, 'schema', 'integration'),+ route: 'authoring',+ title: 'Astryx Integration',+ command: 'astryx docs authoring integration',+ });+ const opened = await docs('authoring', 'integration');+ expect(opened.type).toBe('docs.detail.section');+ expect(opened.data.id).toBe('integration');+ });++ it(+ "leaves no reference in the CLI's own docs that cannot include what it names",+ async () => {+ const catalog = builtinCatalog();+ expect(+ await docsLinkProblems(catalog, await projectTree(catalog), {+ references: true,+ }),+ ).toEqual([]);+ },+ SLOW,+ );+});++describe('a reference block that cannot include what it names', () => {+ it(+ 'fails the authoring check, once for each part it cannot include',+ async () => {+ scaffold({'acme-broken.doc.mjs': BROKEN});+ const {data} = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ const errors = data.issues.filter(+ issue => issue.code === 'invalid_doc_reference',+ );+ expect(errors.every(issue => issue.severity === 'error')).toBe(true);+ const messages = errors.map(issue => issue.message);+ expect(messages).toHaveLength(5);+ expect(messages[0]).toMatch(+ /^acme-broken § gaps: projection\.fields: "nope" is not a field of Astryx Integration/,+ );+ expect(messages[1]).toMatch(+ /"@astryxdesign\/cli:schema:nothing" names no doc/,+ );+ expect(messages[2]).toMatch(+ /projection\.fields: names the fields of a schema doc/,+ );+ expect(messages[3]).toMatch(/projection\.sections: /);+ expect(messages[4]).toMatch(+ /"@astryxdesign\/cli:generic:theme" is a topic/,+ );+ // They are not also reported as links that print as written.+ expect(+ data.issues.filter(issue => issue.code === 'invalid_doc_graph'),+ ).toEqual([]);+ const cli = await runCli(+ ['doctor', 'integration', 'docs', '@acme/kit'],+ tmpDir,+ );+ expect(cli.status).toBe(1);+ },+ SLOW,+ );++ it(+ 'marks the missing content where a read would show it',+ async () => {+ scaffold({'acme-broken.doc.mjs': BROKEN});+ const texts = (await read('acme-broken', 'gaps')).content+ .filter(block => block.type === 'prose')+ .map(block => block.text);+ expect(texts).toContain(+ '[reference: field "nope" not found in "@astryxdesign/cli:schema:integration"]',+ );+ expect(texts).toContain(+ '[reference: "@astryxdesign/cli:schema:nothing" names no doc]',+ );+ // The field it could include is still there.+ const table = (await read('acme-broken', 'gaps')).content.find(+ block => block.type === 'table',+ );+ expect(table.rows.map(row => row[0])).toEqual(['components']);+ },+ SLOW,+ );++ it(+ "warns in a project's doctor, which an app cannot fix",+ async () => {+ scaffold({'acme-broken.doc.mjs': BROKEN});+ const check = await checkDocsTree({+ docsCatalog: await loadDocsCatalog(tmpDir),+ });+ expect(check.status).toBe('warn');+ expect(check.message).toContain(+ '"nope" is not a field of Astryx Integration',+ );+ },+ SLOW,+ );+});diff --git a/packages/cli/api/doctor/doctor.mjs b/packages/cli/api/doctor/doctor.mjsindex d1beabff56..11d147993a 100644--- a/packages/cli/api/doctor/doctor.mjs+++ b/packages/cli/api/doctor/doctor.mjs@@ -1032,13 +1032,17 @@ export async function checkDocsTree(_ctx, options = {}) {}}// Every link between docs names a doc that exists (spec:AST-047 FR9):- // typed fields, reference and workflow blocks, and inline links.+ // typed fields, reference and workflow blocks, and inline links. A+ // reference block also includes all it names.for (const node of tree.nodes.values()) {for (const edge of typedEdges(tree, node).unresolved) {problems.push(`${node.route}: ${edge}`);}}problems.push(...(await docsLinkProblems(catalog, tree)));+ problems.push(+ ...(await docsLinkProblems(catalog, tree, {references: true})),+ );}// New findings warn: a project that passed before keeps passing// (0.6 compatibility), and the warning names what to fix.diff --git a/packages/cli/api/integration/authoring-checks.mjs b/packages/cli/api/integration/authoring-checks.mjsindex 7470ff33a0..942a74ef1a 100644--- a/packages/cli/api/integration/authoring-checks.mjs+++ b/packages/cli/api/integration/authoring-checks.mjs@@ -15,7 +15,10 @@*/import {getCliInvocation} from '../../foundation/env/package-manager.mjs';-import {packageDocsProblems} from '../docs/_adapter.mjs';+import {+ packageDocsProblems,+ packageReferenceProblems,+} from '../docs/_adapter.mjs';import {findCoreDir} from '../../foundation/fs/paths.mjs';import {discoverIntegrationComponents,@@ -371,6 +374,16 @@ export async function integrationDocConflicts(pkg, options = {}) {)) {issues.push({code: 'invalid_doc_graph', severity: 'warning', message});}++ // A reference block includes content rather than linking to it, so one+ // that cannot include what it names loses that content for every reader:+ // an error, where a link that names no doc still prints as written.+ for (const message of await packageReferenceProblems(+ /** @type {{name: string}} */ (resolved.integration),+ discovered,+ )) {+ issues.push({code: 'invalid_doc_reference', severity: 'error', message});+ }}return {diff --git a/packages/cli/authoring/doctypes/_schema.mjs b/packages/cli/authoring/doctypes/_schema.mjsindex 05172a44f8..f1609b2c25 100644--- a/packages/cli/authoring/doctypes/_schema.mjs+++ b/packages/cli/authoring/doctypes/_schema.mjs@@ -16,6 +16,7 @@ import {z} from 'zod';/** @typedef {import('./namespace/type.js').NamespaceDoc} NamespaceDoc *//** @typedef {import('./reference/type.js').ReferenceContentBlock} ReferenceContentBlock *//** @typedef {import('./reference/type.js').GraphContentBlock} GraphContentBlock */+/** @typedef {import('./reference/type.js').ReferenceSection} ReferenceSection *//** @typedef {import('./reference/type.js').ReferenceDoc} ReferenceDoc *//** @typedef {import('./component/type.js').SingleComponentDoc} SingleComponentDoc *//** @typedef {import('./base/type.js').ComponentPropDoc} ComponentPropDoc */@@ -179,6 +180,20 @@ export const GraphContentBlockSchema = z.discriminatedUnion('type', [ReferenceBlockSchema,]);+/**+ * A topic section's blocks: the stable union, plus a reference block, which a+ * read inlines as the doc it includes.+ */+export const SectionContentBlockSchema = z.discriminatedUnion('type', [+ ProseBlockSchema,+ HeadingBlockSchema,+ CodeBlockSchema,+ TableBlockSchema,+ ListBlockSchema,+ TokenReferenceBlockSchema,+ ReferenceBlockSchema,+]);+/** Namespace content accepts both stable reference blocks and graph-only blocks. */export const NamespaceContentBlockSchema = z.discriminatedUnion('type', [ProseBlockSchema,@@ -210,12 +225,21 @@ export const NamespaceContentBlockSchema = z.discriminatedUnion('type', [* >} _GraphContentBlockDriftLock*/+/**+ * @typedef {import('../_shared/contract.js').Expect<+ * import('../_shared/contract.js').Equal<+ * z.infer<typeof SectionContentBlockSchema>,+ * ReferenceSection['content'][number]+ * >+ * >} _SectionContentBlockDriftLock+ */+const ReferenceSectionSchema = z.object({id: nonEmptyString.optional(),title: nonEmptyString,category: z.string().optional(),- content: z.array(ReferenceContentBlockSchema),+ content: z.array(SectionContentBlockSchema),previewType: z.enum(['swatch',diff --git a/packages/cli/authoring/doctypes/load-contract.test.mjs b/packages/cli/authoring/doctypes/load-contract.test.mjsindex 7be86e34a3..3a4a8e3acc 100644--- a/packages/cli/authoring/doctypes/load-contract.test.mjs+++ b/packages/cli/authoring/doctypes/load-contract.test.mjs@@ -182,6 +182,31 @@ describe('unknown fields', () => {);});+ it("are refused inside a section's reference block, which a section takes", () => {+ const [section] = EXAMPLES.generic.sections;+ const reference = {+ type: 'reference',+ target: '@astryxdesign/cli:schema:integration',+ projection: {fields: ['docs']},+ presentation: 'compact',+ };+ /** @param {object} block */+ const withBlock = block =>+ parseDoc(+ {...EXAMPLES.generic, sections: [{...section, content: [block]}]},+ 'r.doc.mjs',+ );+ expect(() => withBlock(reference)).not.toThrow();+ expect(() => withBlock({...reference, notAField: true})).toThrow();+ expect(() =>+ withBlock({...reference, projection: {fields: ['docs'], rows: []}}),+ ).toThrow();+ // Workflow and collection blocks belong to a namespace doc.+ expect(() =>+ withBlock({type: 'collection', source: {slot: 'guides'}}),+ ).toThrow();+ });+it('are refused inside sections and content blocks', () => {const [section] = EXAMPLES.generic.sections;expect(() =>diff --git a/packages/cli/authoring/doctypes/reference/reference.doc.mjs b/packages/cli/authoring/doctypes/reference/reference.doc.mjsindex 52758377ca..6ad029dd7b 100644--- a/packages/cli/authoring/doctypes/reference/reference.doc.mjs+++ b/packages/cli/authoring/doctypes/reference/reference.doc.mjs@@ -93,9 +93,9 @@ export const doc = {},{name: 'sections[].content',- type: 'ReferenceContentBlock[]',+ type: '(ReferenceContentBlock | ReferenceDocBlock)[]',description:- 'Ordered content blocks: prose, heading, code, table, list, and token-ref. Graph-only workflow, collection, and reference blocks are available through GraphContentBlock on NamespaceDoc, without widening this stable union. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.',+ "Ordered content blocks: prose, heading, code, table, list, token-ref, and reference. A `reference` block (`{type: 'reference', target, projection?, presentation?}`) includes another doc from its canonical source instead of a copy: a schema, command, function, or enum doc as `astryx docs` prints it, then the command that opens it. `projection.fields` keeps only those fields of a schema; `presentation` is `full` (the default), `compact` (no code blocks), or `summary` (only the doc's title, summary, and command). Any other doc shows as a summary. Graph-only workflow and collection blocks are available through GraphContentBlock on NamespaceDoc, without widening the stable ReferenceContentBlock union. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.",required: true,},{@@ -144,7 +144,27 @@ export const docs = {},{type: 'prose',- text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, the stable discriminated union of prose, heading, code, table, list, and token-ref. Docs-graph-only workflow, collection, and reference blocks are exported separately as GraphContentBlock and accepted by NamespaceDoc. choice, callout, and checklist remain invalid. ReferenceContentBlock is also reused by the `notes` field on SchemaDoc and CommandDoc. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.',+ text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, the stable discriminated union of prose, heading, code, table, list, and token-ref, plus the reference block (ReferenceDocBlock). A read inlines a reference block the way it inlines a token-ref, so `astryx docs`, in text and in `--json`, returns only the stable block kinds. Docs-graph-only workflow and collection blocks are exported separately as GraphContentBlock and accepted by NamespaceDoc. choice, callout, and checklist remain invalid. ReferenceContentBlock is also reused by the `notes` field on SchemaDoc and CommandDoc. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.',+ },+ {+ type: 'prose',+ text: "A reference block includes content, where a link only points at it: `astryx doctor integration docs` fails when its target names no doc, when `projection.fields` names a field the schema does not have, or when the doc cannot take the projection or presentation it sets, and a read marks the missing content. A target without a provider names a doc of the package that wrote it, so an integration names the CLI's docs with the CLI's provider, as in `@astryxdesign/cli:schema:integration`.",+ },+ {+ type: 'code',+ lang: 'js',+ label: 'A section that includes two fields of the integration manifest',+ code: `{+ title: 'Point the manifest at your folders',+ content: [+ {type: 'prose', text: 'Add these fields to astryx.integration.mjs.'},+ {+ type: 'reference',+ target: '@astryxdesign/cli:schema:integration',+ projection: {fields: ['components', 'docs']},+ },+ ],+}`,},{type: 'code',@@ -158,10 +178,17 @@ export const docs = {| { type: 'list'; style: 'ordered' | 'unordered' | 'do' | 'dont'; items: string[] }| { type: 'token-ref'; topic: string; section: string };+type ReferenceDocBlock = {+ type: 'reference';+ target: string;+ projection?: { fields?: string[]; sections?: string[] };+ presentation?: 'summary' | 'compact' | 'full';+};+type GraphContentBlock =| { type: 'workflow'; title?: string; steps: WorkflowStep[] }| { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }- | { type: 'reference'; target: string; presentation?: 'summary' | 'compact' };`,+ | ReferenceDocBlock;`,},{type: 'prose',diff --git a/packages/cli/authoring/doctypes/reference/type.ts b/packages/cli/authoring/doctypes/reference/type.tsindex 569fab74c2..e03ffab219 100644--- a/packages/cli/authoring/doctypes/reference/type.ts+++ b/packages/cli/authoring/doctypes/reference/type.ts@@ -30,19 +30,32 @@ export interface CollectionDocBlock {whenEmpty?: 'show' | 'omit';}-/** A bounded projection of one canonical doc. */+/**+ * A bounded projection of one canonical doc. In a namespace doc's `blocks` it+ * is layout the docs tree renders later. In a topic section, a read includes+ * the doc it names in place of the block: a schema, command, function, or+ * enum doc as `astryx docs` prints it (`projection.fields` keeps only those+ * fields of a schema), then the command that opens that doc. Any other doc+ * shows its title and summary.+ */export interface ReferenceDocBlock {type: 'reference';+ /** The doc it names, by identity: `[<provider>:]<kind>:<name>`. */target: string;projection?: {fields?: string[];sections?: string[];};+ /** `summary`: only the doc's title, summary, and the command that opens it.+ * `compact`: the included doc without its code blocks. `full`, the default:+ * the included doc. */presentation?: 'summary' | 'compact' | 'full';}-/** Graph-only content blocks. These are additive and do not widen the stable- * {@link ReferenceContentBlock} union consumed by existing exhaustive renderers. */+/** Graph-only content blocks, for a namespace doc's `blocks`. These are+ * additive and do not widen the stable {@link ReferenceContentBlock} union+ * consumed by existing exhaustive renderers. A topic section accepts the+ * `reference` block too, and a read inlines it as stable blocks. */export type GraphContentBlock =WorkflowDocBlock | CollectionDocBlock | ReferenceDocBlock;@@ -148,8 +161,10 @@ export interface ReferenceSection {/** Navigation category ('guide' | 'foundations'). Mirrors the parent doc's* category so sections can be grouped independently in the docsite nav. */category?: string;- /** Ordered content blocks. Mix prose, code, tables, and lists freely. */- content: ReferenceContentBlock[];+ /** Ordered content blocks. Mix prose, code, tables, and lists freely. A+ * `reference` block includes another doc from its canonical source, so a+ * guide never copies a schema's fields or a command's options. */+ content: (ReferenceContentBlock | ReferenceDocBlock)[];/** Preview type for token tables in this section. When set, the docsite* renders a visual preview column using the token's computed CSS value* from the current theme. Omit for non-token sections. */diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjsindex 81d05bc0ed..a2901c3658 100644--- a/packages/cli/clients/cli/commands/docs.mjs+++ b/packages/cli/clients/cli/commands/docs.mjs@@ -115,7 +115,7 @@ function formatBlock(block, detail) {}/**- * @param {import('@astryxdesign/cli/authoring').ReferenceSection} section+ * @param {import('../../../api/docs/docs.type.mjs').DocsReadSection} section* @param {'full' | 'compact' | 'brief'} detail* @returns {string}*/@@ -135,7 +135,7 @@ function formatSection(section, detail) {}/**- * @param {import('@astryxdesign/cli/authoring').ReferenceDoc} docs+ * @param {import('../../../api/docs/docs.type.mjs').DocsReadDoc} docs* @param {'full' | 'compact' | 'brief'} detail* @returns {string}*/diff --git a/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjsindex 0f7ab7565c..1ba8eab2ee 100644--- a/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs+++ b/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs@@ -32,7 +32,7 @@ export const doc = {],exitCodes: [{code: 0, when: 'all Core overlaps are explicitly declared or no overlap exists'},- {code: 1, when: 'an overlap is accidental, a doc is invalid, or a namespace or placement fails. A link that names no doc is a warning, and does not change the exit code'},+ {code: 1, when: 'an overlap is accidental, a doc is invalid, a namespace or placement fails, or a reference block cannot include what it names. A link that names no doc is a warning, and does not change the exit code'},],related: ['doctor integration validate', 'docs'],};diff --git a/packages/cli/foundation/discovery/authoring-self-docs.mjs b/packages/cli/foundation/discovery/authoring-self-docs.mjsindex 543cfa1603..d49be59625 100644--- a/packages/cli/foundation/discovery/authoring-self-docs.mjs+++ b/packages/cli/foundation/discovery/authoring-self-docs.mjs@@ -133,6 +133,24 @@ function fieldRows(fields) {]);}+/**+ * A schema's fields as the table its section prints, each nested field on the+ * row after its parent; null when there are none. A reference block that+ * names some of a schema's fields includes this table of just those.+ * @param {any[]} fields+ * @returns {{type: 'table', headers: string[], rows: string[][]} | null}+ */+export function schemaFieldTable(fields) {+ const rows = fieldRows(fields);+ return rows.length > 0+ ? {+ type: 'table',+ headers: ['Field', 'Type', 'Required', 'Description'],+ rows,+ }+ : null;+}+/*** One self-doc as a topic section, keyed by the doc's own name.* @param {any} doc@@ -144,14 +162,8 @@ export function selfDocSection(doc) {if (doc.appliesTo) {content.push({type: 'prose', text: `Applies to: ${doc.appliesTo}`});}- const rows = fieldRows(doc.fields ?? []);- if (rows.length > 0) {- content.push({- type: 'table',- headers: ['Field', 'Type', 'Required', 'Description'],- rows,- });- }+ const table = schemaFieldTable(doc.fields ?? []);+ if (table) content.push(table);for (const example of doc.examples ?? []) {if (typeof example?.code !== 'string' || example.code.trim() === '')continue;diff --git a/packages/cli/foundation/discovery/authoring-self-docs.test.mjs b/packages/cli/foundation/discovery/authoring-self-docs.test.mjsindex 5c007311b9..091f68e1e4 100644--- a/packages/cli/foundation/discovery/authoring-self-docs.test.mjs+++ b/packages/cli/foundation/discovery/authoring-self-docs.test.mjs@@ -82,15 +82,20 @@ describe('what the authoring docs say about the docs tree', () => {expect(graphFieldsDoc.description).toMatch(/not built yet/);});- it('keeps graph blocks behind the separate GraphContentBlock type', () => {+ it('keeps graph blocks behind the separate GraphContentBlock type, and a section takes a reference block', () => {const content = referenceDoc.fields.flatMap(field => [field, ...(field.fields ?? [])]).find(field => field.name === 'sections[].content');- expect(content.type).toBe('ReferenceContentBlock[]');+ expect(content.type).toBe('(ReferenceContentBlock | ReferenceDocBlock)[]');expect(content.description).toContain('GraphContentBlock');for (const type of GRAPH_BLOCK_TYPES) {expect(content.description).toContain(type);}+ // A section's reference block reads as the doc it includes.+ expect(GRAPH_BLOCK_TYPES.has('reference')).toBe(false);+ expect(content.description).toMatch(+ /A `reference` block .* includes another doc/,+ );});it('says where namespace docs live: the CLI tree, and each integration', () => {diff --git a/packages/cli/foundation/discovery/docs-discovery.mjs b/packages/cli/foundation/discovery/docs-discovery.mjsindex a2fd8f96d7..b3902c0464 100644--- a/packages/cli/foundation/discovery/docs-discovery.mjs+++ b/packages/cli/foundation/discovery/docs-discovery.mjs@@ -145,14 +145,15 @@ const BLOCK_FIELDS = {table: ['headers', 'rows'],list: ['style', 'items'],'token-ref': ['topic', 'section'],+ // A read inlines it as the doc it names includes (spec:AST-047 FR9).+ reference: ['target'],};-/** Blocks that are valid authoring but require the compiled graph renderer. */-export const GRAPH_BLOCK_TYPES = new Set([- 'workflow',- 'collection',- 'reference',-]);+/**+ * Blocks that are valid authoring but require the compiled graph renderer: a+ * namespace doc's `blocks` hold them, a topic section does not.+ */+export const GRAPH_BLOCK_TYPES = new Set(['workflow', 'collection']);/*** Doc fields only the docs tree reads. A flat topic that sets one fails to@@ -168,6 +169,7 @@ export const GRAPH_ONLY_FIELDS = ['placement', 'aliases', 'audience'];/** @type {Record<string, string[]>} */const OPTIONAL_BLOCK_FIELDS = {code: ['label'],+ reference: ['projection', 'presentation'],};/**@@ -179,8 +181,12 @@ const OPTIONAL_BLOCK_FIELDS = {const BLOCK_FIELD_VALUES = {heading: {level: [3, 4, 5, 6]},list: {style: ['ordered', 'unordered', 'do', 'dont']},+ reference: {presentation: ['summary', 'compact', 'full']},};+/** The parts of a doc a reference block's `projection` may select. */+const PROJECTION_FIELDS = ['fields', 'sections'];+/** Keys a section may carry. */const SECTION_FIELDS = ['id', 'title', 'category', 'content', 'previewType'];@@ -325,6 +331,34 @@ export function problemsInTopic(doc, {placement = false} = {}) {);}}+ // A projection names the parts of the doc to include, so each part+ // it names is a non-empty list of names.+ if (block.type === 'reference' && block.projection != null) {+ const projection = block.projection;+ if (typeof projection !== 'object' || Array.isArray(projection)) {+ problems.push(+ `${blockAt}.projection: expected {fields?, sections?}, naming the parts of the doc to include`,+ );+ } else {+ for (const [key, names] of Object.entries(projection)) {+ if (!PROJECTION_FIELDS.includes(key)) {+ problems.push(+ `${blockAt}.projection.${key}: not a field of a projection`,+ );+ } else if (+ !Array.isArray(names) ||+ names.length === 0 ||+ names.some(+ name => typeof name !== 'string' || name.trim() === '',+ )+ ) {+ problems.push(+ `${blockAt}.projection.${key}: expected a non-empty array of names`,+ );+ }+ }+ }+ }},);},diff --git a/packages/cli/foundation/discovery/docs-discovery.test.mjs b/packages/cli/foundation/discovery/docs-discovery.test.mjsindex b14337e09c..5fe4efc609 100644--- a/packages/cli/foundation/discovery/docs-discovery.test.mjs+++ b/packages/cli/foundation/discovery/docs-discovery.test.mjs@@ -310,6 +310,46 @@ describe('problemsInTopic', () => {}});+ it('takes a reference block, and checks its projection and presentation', () => {+ /** @param {any[]} content */+ const withBlocks = content =>+ problemsInTopic(topic({sections: [{title: 'Overview', content}]}));+ expect(+ withBlocks([+ {type: 'reference', target: 'schema:integration'},+ {+ type: 'reference',+ target: '@astryxdesign/cli:schema:integration',+ projection: {fields: ['docs']},+ presentation: 'compact',+ },+ ]),+ ).toEqual([]);+ expect(+ withBlocks([+ {type: 'reference', target: ''},+ {type: 'reference', target: 'schema:x', presentation: 'card'},+ {type: 'reference', target: 'schema:x', projection: {fields: []}},+ {type: 'reference', target: 'schema:x', projection: {rows: ['a']}},+ {type: 'reference', target: 'schema:x', projection: ['docs']},+ {type: 'reference', target: 'schema:x', link: {}},+ ]),+ ).toEqual([+ 'sections[0].content[0].target: expected a non-empty string',+ 'sections[0].content[1].presentation: "card" is not one of summary, compact, full',+ 'sections[0].content[2].projection.fields: expected a non-empty array of names',+ 'sections[0].content[3].projection.rows: not a field of a projection',+ 'sections[0].content[4].projection: expected {fields?, sections?}, naming the parts of the doc to include',+ 'sections[0].content[5].link: not a field of a reference block',+ ]);+ // Workflow and collection blocks stay in a namespace doc's `blocks`.+ for (const type of ['workflow', 'collection']) {+ expect(withBlocks([{type}]).join('\n')).toContain(+ 'requires the compiled graph renderer',+ );+ }+ });+it('rejects a name that is not URL-safe', () => {expect(problemsInTopic(topic({name: 'not a topic'})).join('\n')).toContain('URL-safe',diff --git a/packages/cli/foundation/doc-compiler/lenses.mjs b/packages/cli/foundation/doc-compiler/lenses.mjsindex 32d9b5d949..6597807450 100644--- a/packages/cli/foundation/doc-compiler/lenses.mjs+++ b/packages/cli/foundation/doc-compiler/lenses.mjs@@ -71,9 +71,11 @@ export function indexView(node) {}/**- * `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}@@ -84,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;@@ -126,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}\``},+ ];+}diff --git a/packages/cli/foundation/doc-compiler/links.mjs b/packages/cli/foundation/doc-compiler/links.mjsindex 13e2d3a436..22addb6f42 100644--- a/packages/cli/foundation/doc-compiler/links.mjs+++ b/packages/cli/foundation/doc-compiler/links.mjs@@ -8,8 +8,9 @@* `{@link <target>}`; and a resolver that finds the doc a target names.* @output The same content with every link resolved: an inline link becomes* the `astryx docs` command that opens its doc, and a block carries a `link`- * with the doc's identity, route, title, summary, and command. A link that- * names no doc is a problem, never a guess.+ * with the doc's identity, route, title, summary, and command. A reference+ * block in a topic section also carries the `content` it includes. A link+ * that names no doc is a problem, never a guess.* @position Pure. The docs adapter owns the resolver (the project's docs tree* and topic catalog) and applies this to every read and every doctor check.*/@@ -62,6 +63,16 @@ const CODE_SPAN = /(`[^`]*`)/;* @property {string} target the target as written* @property {string} message* @property {string} [section] the key of the section the link sits in+ * @property {true} [include] the problem is in a `reference` block, which+ * includes content rather than linking to it: a reader loses that content,+ * so the authoring check fails on it+ */++/**+ * What a `reference` block in a topic section includes of the doc it names:+ * stable content blocks, with anything it could not include named in+ * `problems`.+ * @typedef {(block: any) => Promise<{content: any[], problems: string[]}>} DocIncluder*//**@@ -119,9 +130,11 @@ export function unlinkText(text) {* @param {any[]} blocks* @param {LinkResolver} resolve* @param {{section?: string}} [at]+ * @param {DocIncluder} [include] how a `reference` block includes the doc it+ * names; without it, the block only carries its `link`* @returns {Promise<{content: any[], problems: LinkProblem[]}>}*/-export async function linkBlocks(blocks, resolve, at = {}) {+export async function linkBlocks(blocks, resolve, at = {}, include) {/** @type {LinkProblem[]} */const problems = [];const where = at.section ? {section: at.section} : {};@@ -195,9 +208,37 @@ export async function linkBlocks(blocks, resolve, at = {}) {});break;}- case 'reference':- content.push({...block, link: await find(block.target)});+ case 'reference': {+ // A reference includes content, so what it cannot include is a+ // problem the authoring check fails on, not one that prints as written.+ const found = await resolve(block.target);+ if ('problem' in found) {+ problems.push({+ target: block.target,+ message: found.problem,+ include: true,+ ...where,+ });+ content.push({...block, link: null});+ break;+ }+ /** @type {any} */+ const linked = {...block, link: found};+ if (include) {+ const included = await include(block);+ for (const message of included.problems) {+ problems.push({+ target: block.target,+ message,+ include: true,+ ...where,+ });+ }+ linked.content = included.content;+ }+ content.push(linked);break;+ }case 'workflow': {const steps = [];for (const step of block.steps ?? []) {diff --git a/packages/cli/foundation/doc-compiler/links.test.mjs b/packages/cli/foundation/doc-compiler/links.test.mjsindex 0463de3f6f..cd796d9646 100644--- a/packages/cli/foundation/doc-compiler/links.test.mjs+++ b/packages/cli/foundation/doc-compiler/links.test.mjs@@ -105,6 +105,59 @@ describe('linkBlocks', () => {);});+ it('includes what a reference block names, and marks what it cannot include', async () => {+ /** @type {any[]} */+ const asked = [];+ const include = async (/** @type {any} */ block) => {+ asked.push(block.target);+ return {+ content: [{type: 'prose', text: 'The doctor command.'}],+ problems: block.projection ? ['projection.fields: no such field'] : [],+ };+ };+ const {content, problems} = await linkBlocks(+ [+ {type: 'reference', target: 'command:doctor'},+ {+ type: 'reference',+ target: 'command:doctor',+ projection: {fields: ['--nope']},+ },+ {type: 'reference', target: 'command:gone'},+ ],+ resolve,+ {section: 'check'},+ include,+ );+ // A target that names no doc is never handed to the includer.+ expect(asked).toEqual(['command:doctor', 'command:doctor']);+ expect(content[0]).toMatchObject({+ link: {command: 'astryx docs cli/commands/doctor'},+ content: [{type: 'prose', text: 'The doctor command.'}],+ });+ expect(content[2]).toEqual({+ type: 'reference',+ target: 'command:gone',+ link: null,+ });+ // Both are the authoring check's: the block includes content, where a+ // link only points at it.+ expect(problems).toEqual([+ {+ target: 'command:doctor',+ message: 'projection.fields: no such field',+ include: true,+ section: 'check',+ },+ {+ target: 'command:gone',+ message: '"command:gone" names no doc',+ include: true,+ section: 'check',+ },+ ]);+ });+it('names every link that finds no doc, and never guesses', async () => {const {content, problems} = await linkSections([diff --git a/packages/cli/test/authoring-types/reference-section-block.exhaustive.ts b/packages/cli/test/authoring-types/reference-section-block.exhaustive.tsnew file mode 100644index 0000000000..27ba7df915--- /dev/null+++ b/packages/cli/test/authoring-types/reference-section-block.exhaustive.ts@@ -0,0 +1,36 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * A topic section's blocks are the six stable ReferenceContentBlock kinds and+ * the reference block, which a read inlines as the doc it includes. This+ * switch renders every one, so `typecheck:authoring` fails the moment a+ * section takes another kind. ReferenceContentBlock itself keeps its six+ * (reference-content-block.exhaustive.ts).+ */++import type {ReferenceSection} from '@astryxdesign/cli/authoring';++export function renderSectionBlock(+ block: ReferenceSection['content'][number],+): string {+ switch (block.type) {+ case 'prose':+ return block.text;+ case 'heading':+ return block.text;+ case 'code':+ return block.code;+ case 'table':+ return block.headers.join(' | ');+ case 'list':+ return block.items.join('\n');+ case 'token-ref':+ return `${block.topic} / ${block.section}`;+ case 'reference':+ return [block.target, ...(block.projection?.fields ?? [])].join(' ');+ default: {+ const unhandled: never = block;+ return unhandled;+ }+ }+}