Skip to content

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.md
new file mode 100644
index 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`.
+
+@josephfarina
diff --git a/docs/specs/AST-047-navigable-output/spec.md b/docs/specs/AST-047-navigable-output/spec.md
index 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 an
error, 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 a
provider names a doc of the provider that wrote the link: in a topic that
merges sections from several providers, each section resolves against its
own. The CLI MUST resolve
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
new file mode 100644
index 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;
+ }
+ }
+}