Skip to content

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

TypeScript

Add typed documentation graph contracts (#6471)

Joeyb7cc8b8d3e39
diff --git a/.changeset/typed-doc-graph-contracts.md b/.changeset/typed-doc-graph-contracts.md
new file mode 100644
index 0000000000..5aea419ead
--- /dev/null
+++ b/.changeset/typed-doc-graph-contracts.md
@@ -0,0 +1,18 @@
+---
+'@astryxdesign/cli': minor
+---
+
+[breaking] Add typed namespace docs, semantic content blocks, and stable provider-aware documentation identity. Consumers with exhaustive `AuthoredDocKind` or `ReferenceContentBlock` switches must add cases for `namespace`, `workflow`, `collection`, and `reference`; existing authored docs continue to parse unchanged.
+
+Every doc section now has a stable key: its `id`, or a key derived from its title. `astryx docs <topic> --index` (`docs(topic, undefined, {index: true})`) returns the topic's section index (`docs.index`), and `astryx docs <topic> <key>` reads one section. A topic read still returns the whole doc. `astryx docs authoring` documents every authoring schema, one section each.
+
+Breaking changes and how to migrate:
+
+- Section keys are validated. A topic whose sections derive the same key (for example `Quick Start` and `Quick-start`), whose section `id` is not lowercase words joined by hyphens, or whose section title yields no key (no Latin letters or digits) loaded before and is now invalid. Give the section a distinct title or an explicit `id`.
+- A section query matches a key, then an exact title, then a unique part of a title. A query that matches more than one section is now refused with the candidates instead of returning the first match; pass the key.
+- A topic extension's section replaces the base section with the same key before falling back to the same title, so an extension `id` that names a base key now replaces that section instead of being added beside it.
+- Human-readable `astryx docs` output wraps at 120 columns (CJK characters count as two), lists topics one per line, and prints a table wider than 120 columns one row at a time. `--json` output is unchanged.
+- When two packages claim one provider ID, the package being authored is used, otherwise the first-loaded one. The other is set aside, and every command, `astryx doctor`, and the project's issues name it; before, it was dropped without a word.
+- `astryx doctor` now fails when a topic's section index or any section is over 32 KB in any language it ships, when a contributed doc is invalid, or when an authoring doc is unreachable.
+
+@josephfarina
diff --git a/.claude/skills/writing-component-docs.md b/.claude/skills/writing-component-docs.md
index 8f9ef867b1..5a22d5c5d2 100644
--- a/.claude/skills/writing-component-docs.md
+++ b/.claude/skills/writing-component-docs.md
@@ -138,7 +138,8 @@ To add a new reference doc: create `packages/cli/assets/docs/mytopic.doc.mjs` ex
```bash
astryx docs # list topics
astryx docs tokens # full output
-astryx docs tokens spacing # single section
+astryx docs tokens --index # section index, one key per section
+astryx docs tokens spacing # single section, by key or title
astryx --detail compact docs tokens # agent-friendly
astryx --lang dense docs tokens # compressed prose
```
diff --git a/AGENTS.md b/AGENTS.md
index bfeddfee6a..75b364b3e6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -201,6 +201,8 @@ astryx docs theme --dense # theme provider, light/dark, overrides
astryx component --list # all components grouped by category
astryx template --list # available page templates
ON DEMAND:
+astryx docs <topic> --index # section index: one line per section, with its key
+astryx docs <topic> <section> # one section, by key or title
astryx component <Name> --dense # props, variants, usage, anatomy for one component
astryx template <name> # emit full page source
astryx template <name> --skeleton # layout skeleton with spatial annotations
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index dcfbae8fd2..4182100b7f 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -1744,6 +1744,8 @@ export interface ContentBlock {
}
export interface DocSection {
+ /** Stable key readers address the section by: astryx docs <topic> <id>. */
+ id?: string;
title: string;
content: ContentBlock[];
previewType?: string;
diff --git a/apps/docsite/src/components/docs/ContentBlockRenderer.tsx b/apps/docsite/src/components/docs/ContentBlockRenderer.tsx
index c6e30bcb12..b6f5c8e4c3 100644
--- a/apps/docsite/src/components/docs/ContentBlockRenderer.tsx
+++ b/apps/docsite/src/components/docs/ContentBlockRenderer.tsx
@@ -37,7 +37,18 @@ export function ContentBlockRenderer({block}: {block: ContentBlock}) {
);
case 'list':
return <ListBlock items={block.items ?? []} listStyle={block.style} />;
- default:
+ default: {
+ const type = (block as {type?: unknown}).type;
+ if (
+ type === 'workflow' ||
+ type === 'collection' ||
+ type === 'reference'
+ ) {
+ throw new Error(
+ `Documentation block "${type}" requires the compiled graph renderer.`,
+ );
+ }
return null;
+ }
}
}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/doc-preview/content-blocks/ContentBlockRenderer.tsx b/apps/sandbox/src/app/(sandbox)/pages/doc-preview/content-blocks/ContentBlockRenderer.tsx
index 443b274773..ff63db9c83 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/doc-preview/content-blocks/ContentBlockRenderer.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/doc-preview/content-blocks/ContentBlockRenderer.tsx
@@ -25,6 +25,12 @@ export function ContentBlockRenderer({block}: {block: ReferenceContentBlock}) {
return <ListBlock items={block.items} listStyle={block.style} />;
case 'token-ref':
return null;
+ case 'workflow':
+ case 'collection':
+ case 'reference':
+ throw new Error(
+ `Documentation block "${block.type}" requires the compiled graph renderer.`,
+ );
default:
return null;
}
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 652dcb5221..ec349cf985 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -403,7 +403,8 @@ Every response has a `type` discriminant. The full set is below (generated from
| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry. |
| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order. |
| `docs.detail` | One topic's full ReferenceDoc, with token-ref blocks inlined. |
-| `docs.detail.section` | A single ReferenceSection of a topic: the first whose title contains the section query. |
+| `docs.index` | One topic's section index (--index): each section's key, title, and one-line summary. |
+| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined. |
| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |
| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |
| `discover.list` | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered". |
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index 26d0810a41..6194bd629a 100644
--- a/packages/cli/api/docs/_adapter.mjs
+++ b/packages/cli/api/docs/_adapter.mjs
@@ -23,9 +23,16 @@ import {Project} from '../../foundation/config/project.mjs';
import {
DocsCatalog,
mergeTopic,
+ problemsInTopic,
+ withSourceTitle,
} from '../../foundation/discovery/docs-discovery.mjs';
+import {
+ sectionKeyProblems,
+ withSectionKeys,
+} from '../../foundation/discovery/docs-section-key.mjs';
import {AstryxError} from '../error.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {parseDoc} from '../../authoring/doctypes/parse.mjs';
/**
* The project's topics: the built-in ones plus whatever the configured
@@ -56,13 +63,20 @@ export async function loadDocsCatalog(cwd = process.cwd()) {
*/
export async function loadReferenceDocs(docPath, {lang} = {}) {
const mod = await import(pathToFileURL(docPath).href);
- const docs = mod.docs ?? mod.default;
+ const parsed = parseDoc(mod.docs ?? mod.default, path.basename(docPath));
+ if (!('sections' in parsed)) {
+ throw new Error(`${path.basename(docPath)} is not a reference document.`);
+ }
+ const problems = problemsInTopic(parsed);
+ if (problems.length > 0) {
+ throw new Error(
+ `${path.basename(docPath)} is invalid: ${problems.join('; ')}`,
+ );
+ }
+ const docs = parsed;
if (!lang || lang === 'en') return docs;
- const dir = path.dirname(docPath);
- const base = path.basename(docPath, '.doc.mjs');
- const locale = lang === 'dense' ? 'dense' : lang;
- const translationPath = path.join(dir, `${base}.doc.${locale}.mjs`);
+ const translationPath = overlayPath(docPath, lang);
if (!fs.existsSync(translationPath)) return docs;
const translationMod = await import(pathToFileURL(translationPath).href);
@@ -86,10 +100,12 @@ export async function loadReferenceDocs(docPath, {lang} = {}) {
...docs,
description: translation.description || docs.description,
sections: docs.sections.map(
- (/** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ section) => {
+ (
+ /** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ section,
+ ) => {
const ts = bySection.get(section.title);
if (!ts) return section;
- return {
+ const localized = {
...section,
title: ts.title || section.title,
content: section.content.map(
@@ -99,12 +115,15 @@ export async function loadReferenceDocs(docPath, {lang} = {}) {
) => {
const tb = ts.content?.[bi];
if (!tb) return block;
- if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
- if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
+ if (tb.type === 'prose' && block.type === 'prose')
+ return {...block, text: tb.text};
+ if (tb.type === 'list' && block.type === 'list')
+ return {...block, items: tb.items};
return block;
},
),
};
+ return withSourceTitle(localized, section.title);
},
),
};
@@ -127,8 +146,44 @@ export async function loadTopicDoc(entry, {lang} = {}) {
let doc = await loadReferenceDocs(entry.path, {lang});
for (const extension of entry.extensions) {
doc = mergeTopic(doc, await loadReferenceDocs(extension.path, {lang}));
+ // Merging matches on keys, so this holds unless merge itself regresses.
+ const problems = sectionKeyProblems(doc.sections);
+ if (problems.length > 0) {
+ throw new Error(
+ `${path.basename(extension.path)}, extending ${entry.name}, leaves two sections with one key: ${problems.join('; ')}`,
+ );
+ }
}
- return doc;
+ // Derived keys are stamped only now, so they never take part in merging.
+ return withSectionKeys(doc);
+}
+
+/** The localized overlays a docs read can apply. */
+export const OVERLAY_LANGUAGES = ['zh', 'dense'];
+
+/**
+ * Where the `lang` overlay of a doc file lives: `{topic}.doc.{lang}.mjs`.
+ * @param {string} docPath
+ * @param {string} lang
+ * @returns {string}
+ */
+function overlayPath(docPath, lang) {
+ return path.join(
+ path.dirname(docPath),
+ `${path.basename(docPath, '.doc.mjs')}.doc.${lang}.mjs`,
+ );
+}
+
+/**
+ * The overlay languages a topic ships for its own file or any extension.
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {string[]}
+ */
+export function overlayLanguages(entry) {
+ const files = [entry.path, ...entry.extensions.map(ext => ext.path)];
+ return OVERLAY_LANGUAGES.filter(lang =>
+ files.some(file => fs.existsSync(overlayPath(file, lang))),
+ );
}
/**
@@ -146,6 +201,7 @@ export async function loadTopicDoc(entry, {lang} = {}) {
* @returns {Promise<{
* catalog: DocsCatalog,
* docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
+ * lang: string | null,
* }>}
*/
export async function resolveTopicDocs(topic, options = {}) {
@@ -166,5 +222,5 @@ export async function resolveTopicDocs(topic, options = {}) {
}
const docsData = await loadTopicDoc(entry, {lang: effectiveLang});
- return {catalog, docsData};
+ return {catalog, docsData, lang: effectiveLang};
}
diff --git a/packages/cli/api/docs/detail/detail.mjs b/packages/cli/api/docs/detail/detail.mjs
index 1a1c327139..d51474d10f 100644
--- a/packages/cli/api/docs/detail/detail.mjs
+++ b/packages/cli/api/docs/detail/detail.mjs
@@ -12,18 +12,25 @@
*/
import {loadTopicDoc, resolveTopicDocs} from '../_adapter.mjs';
+import {
+ sectionKey,
+ sourceTitle,
+ withSourceTitle,
+} from '../../../foundation/discovery/docs-section-key.mjs';
/**
* Resolve token-ref blocks by inlining the referenced section's table.
* This allows section docs to reference token tables without duplicating data.
*
* The reference is resolved through the catalog, so a topic may point at one
- * an integration contributed (or replaced) rather than only at a built-in.
+ * an integration contributed (or replaced) rather than only at a built-in. It
+ * names the section by key or authored title, so it resolves in every language.
* @param {import('../docs.type.mjs').DocsDetailResponse['data']} docsData
* @param {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
+ * @param {{lang?: string | null}} [options]
* @returns {Promise<import('../docs.type.mjs').DocsDetailResponse['data']>}
*/
-async function resolveTokenRefs(docsData, catalog) {
+export async function resolveTokenRefs(docsData, catalog, {lang = null} = {}) {
const resolved = {...docsData, sections: [...docsData.sections]};
for (let si = 0; si < resolved.sections.length; si++) {
const section = resolved.sections[si];
@@ -36,10 +43,12 @@ async function resolveTokenRefs(docsData, catalog) {
newContent.push({type: 'prose', text: `[token-ref: unknown topic "${block.topic}"]`});
continue;
}
- const refDocs = await loadTopicDoc(refEntry);
+ const refDocs = await loadTopicDoc(refEntry, {lang});
+ const wanted = block.section.toLowerCase();
const refSection = refDocs.sections.find(
(/** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ s) =>
- s.title.toLowerCase() === block.section.toLowerCase(),
+ sectionKey(s) === block.section ||
+ sourceTitle(s).toLowerCase() === wanted,
);
if (!refSection) {
newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
@@ -52,14 +61,20 @@ async function resolveTokenRefs(docsData, catalog) {
}
// If the referenced section has a previewType, attach it to our section
if (refSection.previewType && !section.previewType) {
- resolved.sections[si] = {...section, previewType: refSection.previewType, content: newContent};
+ resolved.sections[si] = withSourceTitle(
+ {...section, previewType: refSection.previewType, content: newContent},
+ sourceTitle(section),
+ );
}
} else {
newContent.push(block);
}
}
if (resolved.sections[si] === section) {
- resolved.sections[si] = {...section, content: newContent};
+ resolved.sections[si] = withSourceTitle(
+ {...section, content: newContent},
+ sourceTitle(section),
+ );
} else {
resolved.sections[si].content = newContent;
}
@@ -77,7 +92,7 @@ async function resolveTokenRefs(docsData, catalog) {
* @returns {Promise<import('../docs.type.mjs').DocsDetailResponse>}
*/
export async function detail(topic, options = {}) {
- const {catalog, docsData} = await resolveTopicDocs(topic, options);
- const resolved = await resolveTokenRefs(docsData, catalog);
+ const {catalog, docsData, lang} = await resolveTopicDocs(topic, options);
+ const resolved = await resolveTokenRefs(docsData, catalog, {lang});
return {type: 'docs.detail', data: resolved};
}
diff --git a/packages/cli/api/docs/detail/section/section.mjs b/packages/cli/api/docs/detail/section/section.mjs
index cf3346a684..0c103ce2f5 100644
--- a/packages/cli/api/docs/detail/section/section.mjs
+++ b/packages/cli/api/docs/detail/section/section.mjs
@@ -1,25 +1,31 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file docs.detail.section leaf — load a single named section of a topic.
+ * @file docs.detail.section leaf — load a single section of a topic.
*
* @input A topic name, a section query, and optional {lang, zh, dense}. Resolves
- * and loads the topic via the shared adapter, then finds the first section
- * whose title contains the (case-insensitive) query.
- * @output { type: 'docs.detail.section', data: ReferenceSection } — matching
- * `xds --json docs <topic> <section>`. Throws ERR_UNKNOWN_SECTION when no
- * section title matches.
+ * and loads the topic via the shared adapter, then finds the section by its
+ * stable key, then by exact title, then by a title that contains the query.
+ * @output { type: 'docs.detail.section', data: ReferenceSection } with any
+ * token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
+ * Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
+ * more than one section (the candidates come back as suggestions).
* @position Leaf nested under api/docs/detail. Shares discovery/loading/
* topic-resolution with the detail leaf via _adapter.mjs.
*/
import {AstryxError} from '../../../error.mjs';
import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
+import {
+ findDocSection,
+ sectionKey,
+} from '../../../../foundation/discovery/docs-section-key.mjs';
import {resolveTopicDocs} from '../../_adapter.mjs';
+import {resolveTokenRefs} from '../detail.mjs';
/**
* @param {string} topic
- * @param {string} sectionName
+ * @param {string} sectionName a section key, or a title (or part of one)
* @param {object} [options]
* @param {string} [options.lang]
* @param {boolean} [options.zh]
@@ -28,10 +34,9 @@ import {resolveTopicDocs} from '../../_adapter.mjs';
* @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
*/
export async function section(topic, sectionName, options = {}) {
- // An empty section name must error, not resolve to the first section via
- // `.includes('')`. The docs() dispatcher routes a falsy section to detail, but
- // the leaf must be safe on its own. A non-string would also throw a raw
- // TypeError below (`.toLowerCase()`) → downgrades to ERR_UNKNOWN.
+ // An empty section name must error, not resolve to the first section. The
+ // docs() dispatcher routes a falsy section to the topic, but the leaf must be
+ // safe on its own; a non-string would otherwise throw a raw TypeError.
if (typeof sectionName !== 'string' || !sectionName.trim()) {
throw new AstryxError(
'A section name is required',
@@ -39,16 +44,31 @@ export async function section(topic, sectionName, options = {}) {
ERROR_CODES.ERR_UNKNOWN_SECTION,
);
}
- const {docsData} = await resolveTopicDocs(topic, options);
+ const {catalog, docsData, lang} = await resolveTopicDocs(topic, options);
- const normalizedSection = sectionName.toLowerCase();
- const match = docsData.sections.find(s => s.title.toLowerCase().includes(normalizedSection));
+ const {section: match, candidates} = findDocSection(
+ docsData.sections,
+ sectionName,
+ );
if (!match) {
+ const ambiguous = candidates.length > 1;
throw new AstryxError(
- `Section "${sectionName}" not found in "${topic}"`,
- docsData.sections.map(s => ({name: s.title, reason: 'available section'})),
+ ambiguous
+ ? `Section "${sectionName}" matches ${candidates.length} sections in "${topic}". Read one by its key.`
+ : `Section "${sectionName}" not found in "${topic}"`,
+ (ambiguous ? candidates : docsData.sections).map(s => ({
+ name: sectionKey(s),
+ reason: s.title,
+ })),
ERROR_CODES.ERR_UNKNOWN_SECTION,
);
}
- return {type: 'docs.detail.section', data: match};
+ // A section read on its own inlines its token refs, as the whole topic does;
+ // otherwise a section that is only a token-ref prints blank.
+ const {sections} = await resolveTokenRefs(
+ {...docsData, sections: [match]},
+ catalog,
+ {lang},
+ );
+ return {type: 'docs.detail.section', data: sections[0]};
}
diff --git a/packages/cli/api/docs/detail/section/section.test.mjs b/packages/cli/api/docs/detail/section/section.test.mjs
index 8d41b2a577..5ca38b9123 100644
--- a/packages/cli/api/docs/detail/section/section.test.mjs
+++ b/packages/cli/api/docs/detail/section/section.test.mjs
@@ -10,6 +10,7 @@
import {describe, it, expect} from 'vitest';
import {section} from './section.mjs';
import {AstryxError} from '../../../error.mjs';
+import {loadDocsCatalog, loadTopicDoc} from '../../_adapter.mjs';
const SLOW = 30_000;
@@ -39,4 +40,43 @@ describe('docs.detail.section leaf', () => {
code: 'ERR_UNKNOWN_SECTION',
});
}, SLOW);
+
+ it('reads a section by its stable key', async () => {
+ const doc = await loadTopicDoc((await loadDocsCatalog()).resolve('theme'));
+ const target = doc.sections[doc.sections.length - 1];
+ const res = await section('theme', target.id);
+ expect(res.data.title).toBe(target.title);
+ expect(res.data.id).toBe(target.id);
+ }, SLOW);
+
+ it('refuses a query that matches more than one section', async () => {
+ const err = await section('theme', 'e').catch(e => e);
+ expect(err).toBeInstanceOf(AstryxError);
+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+ expect(err.message).toMatch(/matches \d+ sections/);
+ expect(err.suggestions.length).toBeGreaterThan(1);
+ }, SLOW);
+
+ it.each([null, 'zh', 'dense'])(
+ 'inlines token refs when a section is read on its own (lang %s)',
+ async lang => {
+ const catalog = await loadDocsCatalog();
+ let checked = 0;
+ for (const entry of catalog.entries()) {
+ const doc = await loadTopicDoc(entry);
+ for (const own of doc.sections) {
+ if (!own.content.some(block => block.type === 'token-ref')) continue;
+ const res = await section(entry.name, own.id, lang ? {lang} : {});
+ expect(res.data.content.length).toBeGreaterThan(0);
+ expect(res.data.content.some(block => block.type === 'token-ref')).toBe(
+ false,
+ );
+ expect(JSON.stringify(res.data.content)).not.toContain('[token-ref:');
+ checked += 1;
+ }
+ }
+ expect(checked).toBeGreaterThan(0);
+ },
+ SLOW,
+ );
});
diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjs
index 3962d2cae6..c220664af7 100644
--- a/packages/cli/api/docs/docs.doc.mjs
+++ b/packages/cli/api/docs/docs.doc.mjs
@@ -13,18 +13,20 @@ export const doc = {
name: 'docs',
displayName: 'docs()',
summary:
- 'Read the reference docs: list every topic, one topic, or a single section of a topic.',
+ 'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',
description:
- 'Routes on its arguments: no topic lists every reference-doc topic; a topic ' +
- 'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
- 'plus a section returns the first section whose title contains the ' +
- '(case-insensitive) query. The topic set is the CLI\'s own docs plus the ' +
+ 'No topic lists every reference-doc topic; a topic returns that full ' +
+ 'ReferenceDoc; `index: true` returns the topic\'s section index instead ' +
+ '(each section\'s key, title, and summary); a topic plus a section returns ' +
+ 'that one section, found by its key, then its exact title, then a unique ' +
+ 'part of its title (an ambiguous query is refused). Token-ref blocks are ' +
+ 'inlined in every read. 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. ' +
'Overlay options select localized or dense variants.',
importPath: '@astryxdesign/cli/api',
signature:
- 'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse>',
+ 'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse>',
keywords: [
'docs',
'documentation',
@@ -46,7 +48,7 @@ export const doc = {
name: 'section',
type: 'string',
description:
- 'Section within the topic to return; matches the first section title that contains this (case-insensitive).',
+ "Section to return: its key (from the topic's index), its title, or a unique part of its title (case-insensitive).",
},
{
name: 'options.lang',
@@ -63,6 +65,12 @@ export const doc = {
type: 'boolean',
description: 'Return the token-efficient dense doc variant.',
},
+ {
+ name: 'options.index',
+ type: 'boolean',
+ description:
+ "Return the topic's section index (each section's key, title, and summary) instead of the whole doc.",
+ },
{
name: 'options.cwd',
type: 'string',
@@ -81,10 +89,15 @@ export const doc = {
description:
"One topic's full ReferenceDoc, with token-ref blocks inlined.",
},
+ {
+ type: 'docs.index',
+ description:
+ "One topic's section index (index: true): {name, title, description, sections: [{id, title, summary}]}.",
+ },
{
type: 'docs.detail.section',
description:
- 'A single ReferenceSection of the topic: the first whose title contains the section query.',
+ 'One ReferenceSection of the topic, found by key or title, with token-ref blocks inlined.',
},
],
throws: [
@@ -94,13 +107,17 @@ export const doc = {
},
{
code: 'ERR_UNKNOWN_SECTION',
- when: 'a section is requested but is empty or matches no section title in the topic',
+ when: 'a section is requested but is empty, matches no section, or matches more than one',
},
],
examples: [
{label: 'List topics', code: 'const r = await docs();'},
{label: 'Load a topic', code: "await docs('principles');"},
- {label: 'One section', code: "await docs('tokens', 'spacing');"},
+ {
+ label: "A topic's sections",
+ code: "await docs('principles', undefined, {index: true});",
+ },
+ {label: 'One section by key', code: "await docs('tokens', 'spacing');"},
],
command: 'docs',
related: ['search', 'component', 'hook', 'template'],
diff --git a/packages/cli/api/docs/docs.mjs b/packages/cli/api/docs/docs.mjs
index c9fc5239ad..59a57ee5b9 100644
--- a/packages/cli/api/docs/docs.mjs
+++ b/packages/cli/api/docs/docs.mjs
@@ -3,24 +3,27 @@
/**
* @file Programmatic API for the docs command.
*
- * Dispatcher + barrel. `docs()` routes by argument shape into one of three
+ * Dispatcher + barrel. `docs()` routes by argument shape into one of four
* leaves, each projecting into a single { type, data } envelope:
*
- * docs() -> list -> docs.list
- * docs(topic) -> detail -> docs.detail
- * docs(topic, section) -> section -> docs.detail.section
+ * docs() -> list -> docs.list
+ * docs(topic) -> detail -> docs.detail
+ * docs(topic, undefined, {index: true}) -> index -> docs.index
+ * docs(topic, section) -> section -> docs.detail.section
*
- * The leaves live in list/, detail/, and detail/section/; the discovery,
- * overlay loading, and topic resolution they share sit in _adapter.mjs. This
- * module keeps the same `docs` export (and re-exports the leaves) so
- * api/index.mjs and the CLI consumer import from here unchanged.
+ * A topic read returns the whole doc, as it always has. The index is how a
+ * reader works progressively instead: list the topic's sections, then read one
+ * by its key. The leaves live in list/, index/, detail/, and detail/section/;
+ * the discovery, overlay loading, and topic resolution they share sit in
+ * _adapter.mjs.
*/
import {list} from './list/list.mjs';
+import {index} from './index/index.mjs';
import {detail} from './detail/detail.mjs';
import {section as sectionLeaf} from './detail/section/section.mjs';
-export {list, detail, sectionLeaf as section};
+export {list, index, detail, sectionLeaf as section};
/**
* @param {string} [topic]
@@ -29,9 +32,12 @@ export {list, detail, sectionLeaf as section};
* @param {string} [options.lang]
* @param {boolean} [options.zh]
* @param {boolean} [options.dense]
+ * @param {boolean} [options.index] return the topic's section index instead of
+ * the whole doc
* @param {string} [options.cwd]
* @returns {Promise<
* import('./docs.type.mjs').DocsListResponse |
+ * import('./docs.type.mjs').DocsIndexResponse |
* import('./docs.type.mjs').DocsDetailResponse |
* import('./docs.type.mjs').DocsDetailSectionResponse
* >}
@@ -39,5 +45,6 @@ export {list, detail, sectionLeaf as section};
export async function docs(topic, section, options = {}) {
if (!topic) return list(options);
if (section) return sectionLeaf(topic, section, options);
+ if (options.index) return index(topic, options);
return detail(topic, options);
}
diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjs
index f564e678cf..59fa375b63 100644
--- a/packages/cli/api/docs/docs.test.mjs
+++ b/packages/cli/api/docs/docs.test.mjs
@@ -33,6 +33,12 @@ describe('docs() dispatcher routing', () => {
expect(r.type).toBe('docs.detail');
}, SLOW);
+ it('topic + index -> docs.index', async () => {
+ const {data} = await docs();
+ const r = await docs(data[0].topic, undefined, {index: true});
+ expect(r.type).toBe('docs.index');
+ }, SLOW);
+
it('topic + section -> docs.detail.section', async () => {
const {data} = await docs();
let routed = null;
diff --git a/packages/cli/api/docs/docs.type.mjs b/packages/cli/api/docs/docs.type.mjs
index 8033743307..d2433e8fe3 100644
--- a/packages/cli/api/docs/docs.type.mjs
+++ b/packages/cli/api/docs/docs.type.mjs
@@ -8,6 +8,7 @@
* ------------------------------------------------------------
* xds --json docs -> docs.list
* xds --json docs <topic> -> docs.detail
+ * xds --json docs <topic> --index -> docs.index
* xds --json docs <topic> <section> -> docs.detail.section
* (unknown topic/section) -> CLIError
*/
@@ -29,6 +30,13 @@
* was contributed as a replacement
*/
+/**
+ * xds --json docs <topic> --index
+ * @typedef {object} DocsIndexResponse
+ * @property {'docs.index'} type
+ * @property {DocsIndex} data
+ */
+
/**
* xds --json docs <topic>
* @typedef {object} DocsDetailResponse
@@ -36,6 +44,24 @@
* @property {import('@astryxdesign/cli/authoring').ReferenceDoc} data
*/
+/**
+ * The section index of one topic: what the topic is, and the key each section
+ * is read by.
+ * @typedef {object} DocsIndex
+ * @property {string} name the topic
+ * @property {string} title
+ * @property {string} description
+ * @property {DocsIndexSection[]} sections
+ */
+
+/**
+ * @typedef {object} DocsIndexSection
+ * @property {string} id stable key; pass it as the section argument
+ * @property {string} title
+ * @property {string} summary the section's first line of text, at most 240
+ * characters
+ */
+
/**
* xds --json docs <topic> <section>
* @typedef {object} DocsDetailSectionResponse
@@ -49,6 +75,8 @@
* @property {string} [lang]
* @property {boolean} [zh]
* @property {boolean} [dense]
+ * @property {boolean} [index] return a topic's section index instead of its
+ * whole doc
* @property {string} [cwd] project directory whose configured integrations
* contribute topics; defaults to process.cwd()
*/
diff --git a/packages/cli/api/docs/index/index.mjs b/packages/cli/api/docs/index/index.mjs
new file mode 100644
index 0000000000..0fb9305c03
--- /dev/null
+++ b/packages/cli/api/docs/index/index.mjs
@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs.index leaf — the section index of one topic.
+ *
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves and loads
+ * the topic via the shared adapter.
+ * @output { type: 'docs.index', data: DocsIndex } — the topic's name, title and
+ * description and, for each section, the key it is read by, its title, and a
+ * one-line summary. Matches `astryx --json docs <topic> --index`.
+ * @position Leaf under api/docs: a topic's opt-in progressive read. One section
+ * is the section leaf (`docs <topic> <key>`); the whole topic, a plain topic
+ * read, is the detail leaf.
+ */
+
+import {buildDocsIndexData} from '../../../foundation/discovery/docs-section-key.mjs';
+import {resolveTopicDocs} from '../_adapter.mjs';
+
+/**
+ * @param {string} topic
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
+ */
+export async function index(topic, options = {}) {
+ const {docsData} = await resolveTopicDocs(topic, options);
+ return {type: 'docs.index', data: buildDocsIndexData(docsData)};
+}
diff --git a/packages/cli/api/docs/index/index.test.mjs b/packages/cli/api/docs/index/index.test.mjs
new file mode 100644
index 0000000000..a721a3087d
--- /dev/null
+++ b/packages/cli/api/docs/index/index.test.mjs
@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {docs} from '../docs.mjs';
+import {index} from './index.mjs';
+import {loadDocsCatalog} from '../_adapter.mjs';
+
+const SLOW = 60_000;
+
+describe('docs.index leaf', () => {
+ it('lists each section by key, title, and summary', async () => {
+ const res = await index('theme');
+ expect(res.type).toBe('docs.index');
+ expect(res.data).toMatchObject({name: 'theme', title: expect.any(String)});
+ const keys = res.data.sections.map(s => s.id);
+ expect(new Set(keys).size).toBe(keys.length);
+ for (const entry of res.data.sections) {
+ expect(Object.keys(entry)).toEqual(['id', 'title', 'summary']);
+ expect(entry.summary.length).toBeLessThanOrEqual(240);
+ }
+ }, SLOW);
+
+ it('names the sections the full topic has, with the same keys', async () => {
+ const full = await docs('theme');
+ const {data} = await index('theme');
+ expect(data.sections.map(s => [s.id, s.title])).toEqual(
+ full.data.sections.map(s => [s.id, s.title]),
+ );
+ }, SLOW);
+
+ it('keeps every key the same in every language', async () => {
+ const english = (await index('theme')).data.sections.map(s => s.id);
+ for (const lang of ['zh', 'dense']) {
+ const localized = await index('theme', {lang});
+ expect(localized.data.sections.map(s => s.id)).toEqual(english);
+ }
+ }, SLOW);
+
+ it('lists keys every section can be read by', async () => {
+ const catalog = await loadDocsCatalog();
+ for (const entry of catalog.entries()) {
+ const {data} = await index(entry.name);
+ for (const {id, title} of data.sections) {
+ const read = await docs(entry.name, id);
+ expect(read.data.title).toBe(title);
+ }
+ }
+ }, SLOW);
+});
+
+describe('docs() topic reads', () => {
+ it('returns the whole topic by default, as before', async () => {
+ const res = await docs('theme');
+ expect(res.type).toBe('docs.detail');
+ expect(res.data.sections[0].content.length).toBeGreaterThan(0);
+ }, SLOW);
+
+ it('returns the section index on request', async () => {
+ const res = await docs('theme', undefined, {index: true});
+ expect(res.type).toBe('docs.index');
+ }, SLOW);
+});
diff --git a/packages/cli/api/docs/integrationDocs.test.mjs b/packages/cli/api/docs/integrationDocs.test.mjs
index 2ae8c3ec59..4d9fc759f3 100644
--- a/packages/cli/api/docs/integrationDocs.test.mjs
+++ b/packages/cli/api/docs/integrationDocs.test.mjs
@@ -177,6 +177,112 @@ describe('integration-contributed topics', () => {
expect(extended.data.sections.length).toBe(builtin.data.sections.length + 1);
}, SLOW);
+ it('migrates a real built-in section to a stable ID without duplicating it', async () => {
+ const builtin = await docs('theme');
+ // Readers see a key on every section; the migration case is one whose
+ // source authors no id.
+ const {docs: authored} = await import('../../assets/docs/theme.doc.mjs');
+ const target = authored.sections.find(section => section.id == null);
+ expect(target).toBeDefined();
+ scaffold({
+ 'theme-internal.doc.mjs': topic({
+ name: 'theme-internal',
+ extends: 'theme',
+ sections: [
+ {
+ id: 'acme-theme-setup',
+ title: target.title,
+ content: [{type: 'prose', text: 'Use the Acme theme.'}],
+ },
+ ],
+ }),
+ });
+
+ const extended = await docs('theme', undefined, {cwd: tmpDir});
+ expect(extended.data.sections).toHaveLength(builtin.data.sections.length);
+ const matches = extended.data.sections.filter(
+ section => section.title === target.title,
+ );
+ expect(matches).toEqual([
+ expect.objectContaining({
+ id: 'acme-theme-setup',
+ content: [{type: 'prose', text: 'Use the Acme theme.'}],
+ }),
+ ]);
+ }, SLOW);
+
+ it('replaces a real built-in section by the key its index shows', async () => {
+ const index = await docs('theme', undefined, {index: true});
+ const target = index.data.sections[0];
+ scaffold({
+ 'theme-internal.doc.mjs': topic({
+ name: 'theme-internal',
+ extends: 'theme',
+ sections: [
+ {
+ id: target.id,
+ title: `${target.title} with Acme`,
+ content: [{type: 'prose', text: 'Acme first.'}],
+ },
+ ],
+ }),
+ });
+
+ const extended = await docs('theme', undefined, {cwd: tmpDir});
+ expect(extended.data.sections).toHaveLength(index.data.sections.length);
+ expect(extended.data.sections.filter(s => s.id === target.id)).toEqual([
+ expect.objectContaining({content: [{type: 'prose', text: 'Acme first.'}]}),
+ ]);
+ const read = await docs('theme', target.id, {cwd: tmpDir});
+ expect(read.data.title).toBe(`${target.title} with Acme`);
+ }, SLOW);
+
+ it.each(['zh', 'dense'])(
+ 'replaces translated real sections by their authored titles under --%s',
+ async lang => {
+ const english = await docs('theme');
+ const englishTitles = english.data.sections.map(section => section.title);
+ expect(englishTitles).toEqual(
+ expect.arrayContaining(['Quick Start', 'Theme Props']),
+ );
+ scaffold({
+ 'theme-internal.doc.mjs': topic({
+ name: 'theme-internal',
+ extends: 'theme',
+ sections: [
+ {
+ id: 'acme-quick-start',
+ title: 'Quick Start',
+ content: [{type: 'prose', text: 'Acme quick start.'}],
+ },
+ {
+ title: 'Theme Props',
+ content: [{type: 'prose', text: 'Acme props.'}],
+ },
+ ],
+ }),
+ });
+
+ const base = await docs('theme', undefined, {lang});
+ expect(base.data.sections.map(section => section.title)).not.toEqual(
+ englishTitles,
+ );
+ const extended = await docs('theme', undefined, {cwd: tmpDir, lang});
+ expect(extended.data.sections).toHaveLength(base.data.sections.length);
+ expect(
+ extended.data.sections.filter(
+ section => section.id === 'acme-quick-start',
+ ),
+ ).toHaveLength(1);
+ expect(
+ extended.data.sections.filter(
+ section => section.content[0]?.text === 'Acme props.',
+ ),
+ ).toHaveLength(1);
+ },
+ SLOW,
+ );
+
it('offers the contributed topics as suggestions on an unknown one', async () => {
scaffold({'deploying.doc.mjs': topic()});
await expect(docs('nope-not-a-topic', undefined, {cwd: tmpDir})).rejects.toBeInstanceOf(
diff --git a/packages/cli/api/doctor/doctor.mjs b/packages/cli/api/doctor/doctor.mjs
index 93d0310bb2..e8f6045354 100644
--- a/packages/cli/api/doctor/doctor.mjs
+++ b/packages/cli/api/doctor/doctor.mjs
@@ -27,6 +27,15 @@ import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/nod
import {CLI_ROOT, findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
import {explainPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
import {findConfigPath, Project} from '../../foundation/config/project.mjs';
+import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
+import {buildDocsIndexData} from '../../foundation/discovery/docs-section-key.mjs';
+import {
+ DOC_OUTPUT_BUDGET_BYTES,
+ docsIndexBytes,
+ oversizedDocSections,
+} from '../../foundation/discovery/docs-output-budget.mjs';
+import {loadTopicDoc, overlayLanguages} from '../docs/_adapter.mjs';
+import {resolveTokenRefs} from '../docs/detail/detail.mjs';
import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
/**
@@ -52,6 +61,11 @@ import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env
* @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]|null} [integrations]
* Every integration the project loaded, or null when the project could not be
* read at all.
+ * @property {DocsCatalog|null} [docsCatalog] - The topics a docs read sees.
+ * @property {Array<{package?: string, code: string, message: string}>} [docsCatalogIssues]
+ * `invalid_doc` issues from the project's contributed docs.
+ * @property {string|null} [docsCatalogError] - Why the project's docs catalog
+ * could not be built, when it could not.
* @property {Error|null} [configError] - Error thrown while resolving the config
* path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
*/
@@ -627,6 +641,205 @@ export function checkPackageManager(ctx) {
};
}
+/**
+ * Check 6b — every contributing integration owns its provider identity.
+ *
+ * Artifact and document IDs are provider-scoped, so a package that claims a
+ * provider ID an earlier-loaded package already holds is loaded inert: its
+ * components, templates, themes, docs, and codemods are withdrawn while the
+ * earlier package keeps contributing. That can be a deliberate transition
+ * (a renamed package installed beside its predecessor), so it warns rather
+ * than fails, but it is never allowed to happen quietly.
+ *
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkProviderIdentity(ctx) {
+ const id = 'provider-identity';
+ const label = 'Integration provider identity';
+
+ if (ctx.integrations == null) {
+ return {
+ id,
+ label,
+ status: 'info',
+ message: 'Skipped — the project configuration could not be read.',
+ };
+ }
+
+ const conflicts = ctx.integrations.filter(
+ integration => integration.__providerConflict,
+ );
+ if (conflicts.length > 0) {
+ return {
+ id,
+ label,
+ status: 'warn',
+ message: conflicts
+ .map(integration => integration.__providerConflict?.message)
+ .join(' '),
+ fix:
+ 'Give each integration its own `providerId` in astryx.integration.*. ' +
+ "A renamed package may keep its predecessor's ID only when the " +
+ 'predecessor is no longer installed.',
+ };
+ }
+
+ const count = ctx.integrations.filter(
+ integration =>
+ integration.providerId != null && integration.__loadError == null,
+ ).length;
+ if (count === 0) {
+ return {
+ id,
+ label,
+ status: 'info',
+ message: 'None — no loaded integration has a provider identity.',
+ };
+ }
+ return {
+ id,
+ label,
+ status: 'pass',
+ message:
+ count === 1
+ ? '1 loaded integration has its own provider ID.'
+ : `${count} loaded integrations each have their own provider ID.`,
+ };
+}
+
+/** @param {number} bytes */
+const kilobytes = bytes => `${Math.ceil(bytes / 1024)} KB`;
+
+/**
+ * @param {string[]} problems
+ * @returns {string}
+ */
+function joinProblems(problems) {
+ return problems.length === 1
+ ? problems[0]
+ : `${problems.length} problems: ${problems.join('; ')}`;
+}
+
+/**
+ * Every authoring self-doc is reachable from `astryx docs authoring`, loads,
+ * and fits in one read. The audit is imported here, inside the try, so a
+ * malformed self-doc is reported rather than taking Doctor down.
+ * @param {DoctorContext} [_ctx]
+ * @returns {Promise<DoctorCheck>}
+ */
+export async function checkAuthoringDocs(_ctx) {
+ const id = 'authoring-docs';
+ const label = 'Authoring docs';
+ try {
+ const {auditAuthoringSelfDocs} = await import(
+ '../../foundation/discovery/authoring-self-docs.mjs'
+ );
+ const audit = await auditAuthoringSelfDocs();
+ const problems = [
+ ...audit.unreachable.map(
+ source => `${source} is not in \`astryx docs authoring\``,
+ ),
+ ...audit.failed.map(({source, error}) => `${source} failed to load: ${error}`),
+ ...audit.oversized.map(
+ ({key, bytes}) =>
+ `authoring section "${key}" is ${kilobytes(bytes)}, over the ${kilobytes(DOC_OUTPUT_BUDGET_BYTES)} one read may return`,
+ ),
+ ];
+ if (problems.length > 0) {
+ return {
+ id,
+ label,
+ status: 'fail',
+ message: joinProblems(problems),
+ fix: 'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.',
+ };
+ }
+ return {
+ id,
+ label,
+ status: 'pass',
+ message: `All ${audit.sections} authoring schemas are readable in \`astryx docs authoring\`.`,
+ };
+ } catch (err) {
+ return {
+ id,
+ label,
+ status: 'fail',
+ message: `The authoring docs could not be audited: ${err instanceof Error ? err.message : String(err)}`,
+ fix: 'Reinstall @astryxdesign/cli.',
+ };
+ }
+}
+
+/**
+ * Every topic reads progressively, in every language it ships: it loads, its
+ * section index and each of its sections fit in one read, and no contributed
+ * doc is invalid.
+ * @param {DoctorContext | Partial<DoctorContext>} ctx
+ * @returns {Promise<DoctorCheck>}
+ */
+export async function checkDocsProgressiveDisclosure(ctx) {
+ const id = 'docs-progressive-disclosure';
+ const label = 'Documentation navigation and size';
+ const budget = kilobytes(DOC_OUTPUT_BUDGET_BYTES);
+ /** @type {string[]} */
+ const problems = [];
+ if (ctx.docsCatalogError) {
+ problems.push(`The docs catalog could not be built: ${ctx.docsCatalogError}`);
+ }
+ for (const issue of ctx.docsCatalogIssues ?? []) {
+ problems.push(`${issue.package ?? 'a contributed doc'}: ${issue.message}`);
+ }
+ let topics = 0;
+ const catalog = ctx.docsCatalog;
+ if (catalog) {
+ for (const entry of catalog.entries()) {
+ for (const lang of [null, ...overlayLanguages(entry)]) {
+ const where = lang ? `${entry.name} [${lang}]` : entry.name;
+ try {
+ const doc = await resolveTokenRefs(
+ await loadTopicDoc(entry, {lang}),
+ catalog,
+ {lang},
+ );
+ if (lang == null) topics += 1;
+ const indexBytes = docsIndexBytes(buildDocsIndexData(doc));
+ if (indexBytes > DOC_OUTPUT_BUDGET_BYTES) {
+ problems.push(
+ `${where}: its section index is ${kilobytes(indexBytes)}, over the ${budget} one read may return`,
+ );
+ }
+ for (const over of oversizedDocSections(doc.sections)) {
+ problems.push(
+ `${where} ${over.key}: ${kilobytes(over.bytes)}, over the ${budget} one read may return`,
+ );
+ }
+ } catch (err) {
+ problems.push(
+ `${where}: ${err instanceof Error ? err.message : String(err)}`,
+ );
+ }
+ }
+ }
+ }
+ if (problems.length > 0) {
+ return {
+ id,
+ label,
+ status: 'fail',
+ message: joinProblems(problems),
+ fix: 'Fix the doc each problem names; split a section that is too large into smaller ones, each with its own key.',
+ };
+ }
+ return {
+ id,
+ label,
+ status: 'pass',
+ message: `${topics} topics: every section index and section fits in one ${budget} read.`,
+ };
+}
+
/**
* Ordered list of synchronous check functions. Append here to add a check.
* (checkConfig is async and is awaited separately by {@link runChecks}.)
@@ -638,6 +851,7 @@ export const SYNC_CHECKS = [
checkVersionAlignment,
checkThemes,
checkImplicitIntegrations,
+ checkProviderIdentity,
checkAgentDocs,
checkPeerDeps,
checkPackageManager,
@@ -669,11 +883,28 @@ export async function runChecks(options = {}) {
let configTheme = null;
/** @type {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]|null} */
let integrations = null;
+ // A docs read falls back to the built-in topics when the project cannot be
+ // read, so the docs checks do too; the config check reports the config.
+ /** @type {DocsCatalog|null} */
+ let docsCatalog = DocsCatalog.fromBuiltins();
+ /** @type {Array<{package?: string, code: string, message: string}>} */
+ let docsCatalogIssues = [];
+ /** @type {string|null} */
+ let docsCatalogError = null;
try {
const project = await Project.load(cwd);
configTheme =
/** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
integrations = project.loadedIntegrations;
+ try {
+ docsCatalog = await project.docs();
+ docsCatalogIssues = (await project.issues()).filter(
+ issue => issue.code === 'invalid_doc',
+ );
+ } catch (err) {
+ docsCatalog = null;
+ docsCatalogError = err instanceof Error ? err.message : String(err);
+ }
} catch {
// Best-effort: a missing/invalid config leaves configTheme null.
}
@@ -686,6 +917,9 @@ export async function runChecks(options = {}) {
configPath,
configTheme,
integrations,
+ docsCatalog,
+ docsCatalogIssues,
+ docsCatalogError,
configError,
};
@@ -698,6 +932,8 @@ export async function runChecks(options = {}) {
checks.push(await checkConfig(ctx));
}
}
+ checks.push(await checkAuthoringDocs(ctx));
+ checks.push(await checkDocsProgressiveDisclosure(ctx));
const summary = {pass: 0, warn: 0, fail: 0, info: 0};
for (const c of checks) summary[c.status] += 1;
diff --git a/packages/cli/api/doctor/doctor.test.mjs b/packages/cli/api/doctor/doctor.test.mjs
index 6b39e21d42..ff313d4e24 100644
--- a/packages/cli/api/doctor/doctor.test.mjs
+++ b/packages/cli/api/doctor/doctor.test.mjs
@@ -11,9 +11,13 @@ import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
+import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
import {
doctor,
+ checkAuthoringDocs,
+ checkDocsProgressiveDisclosure,
checkImplicitIntegrations,
+ checkProviderIdentity,
checkVersionAlignment,
checkPackageManager,
} from './doctor.mjs';
@@ -214,6 +218,77 @@ describe('checkPackageManager', () => {
});
});
+describe('checkProviderIdentity', () => {
+ /** @param {object} [fields] */
+ const loaded = (fields = {}) => ({
+ name: '@acme/widgets',
+ providerId: '@acme/widgets',
+ version: '1.0.0',
+ __spec: '@acme/widgets',
+ __packageDir: '/abs/node_modules/@acme/widgets',
+ __manifestFile: '/abs/node_modules/@acme/widgets/astryx.integration.mjs',
+ ...fields,
+ });
+
+ it('skips when the project could not be read', () => {
+ expect(checkProviderIdentity({integrations: null}).status).toBe('info');
+ });
+
+ it('reports none when nothing is loaded', () => {
+ const c = checkProviderIdentity({integrations: []});
+ expect(c.status).toBe('info');
+ expect(c.message).toContain('None');
+ });
+
+ it('passes when each loaded integration has its own provider ID', () => {
+ const c = checkProviderIdentity({
+ integrations: [
+ loaded(),
+ loaded({
+ name: '@acme/charts',
+ providerId: '@acme/charts',
+ __spec: '@acme/charts',
+ }),
+ ],
+ });
+ expect(c.status).toBe('pass');
+ expect(c.message).toContain('2 loaded integrations');
+ });
+
+ it('warns and names both packages when a later claimant is set aside', () => {
+ const message =
+ '@acme/[email protected] and @acme/[email protected] both claim provider ID ' +
+ '"@acme/widgets". @acme/[email protected] loads first and is used; ' +
+ '@acme/[email protected] contributes nothing until one package changes ' +
+ 'its providerId.';
+ const c = checkProviderIdentity({
+ integrations: [
+ loaded(),
+ loaded({
+ name: '@acme/renamed',
+ version: '2.0.0',
+ __spec: '@acme/renamed',
+ __providerConflict: {
+ providerId: '@acme/widgets',
+ claimedBy: '@acme/widgets',
+ message,
+ },
+ }),
+ ],
+ });
+ expect(c.status).toBe('warn');
+ expect(c.message).toBe(message);
+ expect(c.fix).toContain('providerId');
+ });
+
+ it('is part of the report doctor returns', async () => {
+ const r = await doctor({cwd});
+ expect(r.data.checks.map(check => check.id)).toContain(
+ 'provider-identity',
+ );
+ }, SLOW);
+});
+
describe('checkImplicitIntegrations', () => {
/** @param {object} [fields] */
const autolinked = (fields = {}) => ({
@@ -297,3 +372,124 @@ describe('checkImplicitIntegrations', () => {
expect(r.data.checks.map(c => c.id)).toContain('implicit-integrations');
}, SLOW);
});
+
+describe('checkDocsProgressiveDisclosure', () => {
+ it('passes when every topic index and section fits one read', async () => {
+ const c = await checkDocsProgressiveDisclosure({
+ docsCatalog: DocsCatalog.fromBuiltins(),
+ docsCatalogIssues: [],
+ });
+ expect(c).toMatchObject({id: 'docs-progressive-disclosure', status: 'pass'});
+ expect(c.message).toMatch(/^\d+ topics: /);
+ }, SLOW);
+
+ it('fails on an invalid doc an integration contributed', async () => {
+ const c = await checkDocsProgressiveDisclosure({
+ docsCatalogIssues: [
+ {
+ package: '@acme/widgets',
+ code: 'invalid_doc',
+ severity: 'error',
+ message: 'bad.doc.mjs exports no doc',
+ },
+ ],
+ });
+ expect(c.status).toBe('fail');
+ expect(c.message).toBe('@acme/widgets: bad.doc.mjs exports no doc');
+ });
+
+ it('fails when the docs catalog cannot be built', async () => {
+ const c = await checkDocsProgressiveDisclosure({docsCatalogError: 'boom'});
+ expect(c.status).toBe('fail');
+ expect(c.message).toContain('boom');
+ });
+
+ it('names a section over the budget and a topic that fails to load', async () => {
+ const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-docs-'));
+ tmpDirs.push(dir);
+ const huge = {
+ name: 'huge',
+ title: 'Huge',
+ description: 'Too big for one read.',
+ sections: [
+ {title: 'Small', content: [{type: 'prose', text: 'Fits.'}]},
+ {title: 'Everything', content: [{type: 'prose', text: 'x'.repeat(40 * 1024)}]},
+ ],
+ };
+ fs.writeFileSync(
+ path.join(dir, 'huge.doc.mjs'),
+ `export const docs = ${JSON.stringify(huge)};\n`,
+ );
+ fs.writeFileSync(path.join(dir, 'broken.doc.mjs'), 'export const docs = {;\n');
+ const c = await checkDocsProgressiveDisclosure({
+ docsCatalog: DocsCatalog.fromBuiltins({
+ huge: path.join(dir, 'huge.doc.mjs'),
+ broken: path.join(dir, 'broken.doc.mjs'),
+ }),
+ docsCatalogIssues: [],
+ });
+ expect(c.status).toBe('fail');
+ expect(c.message).toMatch(/^2 problems: /);
+ expect(c.message).toContain('huge everything: 41 KB, over the 32 KB one read may return');
+ expect(c.message).toContain('broken: ');
+ expect(c.message).not.toContain('huge small');
+ });
+});
+
+describe('checkAuthoringDocs', () => {
+ it('passes when every authoring self-doc is reachable and fits one read', async () => {
+ const c = await checkAuthoringDocs();
+ expect(c).toMatchObject({id: 'authoring-docs', status: 'pass'});
+ expect(c.message).toContain('astryx docs authoring');
+ }, SLOW);
+});
+
+describe('doctor docs checks', () => {
+ it('runs both docs checks and they pass on the repo', async () => {
+ const r = await doctor({cwd});
+ const byId = Object.fromEntries(r.data.checks.map(c => [c.id, c.status]));
+ expect(byId['authoring-docs']).toBe('pass');
+ expect(byId['docs-progressive-disclosure']).toBe('pass');
+ }, SLOW);
+});
+
+describe('checkDocsProgressiveDisclosure languages', () => {
+ it('checks every overlay a topic ships, not only English', async () => {
+ const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-lang-'));
+ tmpDirs.push(dir);
+ const deploying = {
+ name: 'deploying',
+ title: 'Deploying',
+ description: 'Ship it.',
+ sections: [{title: 'Overview', content: [{type: 'prose', text: 'Push the button.'}]}],
+ };
+ fs.writeFileSync(
+ path.join(dir, 'deploying.doc.mjs'),
+ `export const docs = ${JSON.stringify(deploying)};\n`,
+ );
+ fs.writeFileSync(
+ path.join(dir, 'deploying.doc.zh.mjs'),
+ "throw new Error('zh overlay broken');\n",
+ );
+ fs.writeFileSync(
+ path.join(dir, 'deploying.doc.dense.mjs'),
+ `export const docsDense = ${JSON.stringify({
+ sections: [
+ {
+ section: 'Overview',
+ title: 'Overview',
+ content: [{type: 'prose', text: 'x'.repeat(40 * 1024)}],
+ },
+ ],
+ })};\n`,
+ );
+ const c = await checkDocsProgressiveDisclosure({
+ docsCatalog: DocsCatalog.fromBuiltins({deploying: path.join(dir, 'deploying.doc.mjs')}),
+ docsCatalogIssues: [],
+ });
+ expect(c.status).toBe('fail');
+ expect(c.message).toContain('deploying [zh]: zh overlay broken');
+ expect(c.message).toContain('deploying [dense] overview: 41 KB');
+ expect(c.message).not.toMatch(/deploying overview:/);
+ });
+});
diff --git a/packages/cli/api/upgrade/_adapter.mjs b/packages/cli/api/upgrade/_adapter.mjs
index 33497ae96f..bd6fc8f6b4 100644
--- a/packages/cli/api/upgrade/_adapter.mjs
+++ b/packages/cli/api/upgrade/_adapter.mjs
@@ -33,7 +33,10 @@ import {
} from '../../foundation/agent-docs/agent-docs.mjs';
import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
import {Project} from '../../foundation/config/project.mjs';
-import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
+import {
+ loadIntegrations,
+ markProviderConflicts,
+} from '../../foundation/integrations/integrations.mjs';
import {warnOnIntegrationIssues} from '../../foundation/integrations/integration-warnings.mjs';
import {logger} from '../logger.mjs';
@@ -308,6 +311,15 @@ export async function runCoreCodemods(versionManifests, {apply, path: srcPath, c
});
}
+/**
+ * One installed package at one version; two specs that reach it share this.
+ * @param {{name: string, version?: string}} integration
+ * @returns {string}
+ */
+function packageIdentity(integration) {
+ return `${integration.name}\u0000${integration.version ?? ''}`;
+}
+
/**
* Load the consumer project's config + integrations. Throws on invalid config;
* the run leaf decides between the config_fixable preview and a hard abort.
@@ -321,11 +333,65 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
// cache entry; ordinary Project discovery remains cached by default.
const project = await Project.load(cwd, {fresh: true});
const postCodemodHooks = project.config.hooks?.postCodemod ?? [];
- const integrationSpecs = uniqueFiles([
- ...(project.integrations ?? []),
- ...(extraIntegrationSpecs ?? []),
+ const configuredSpecs = new Set(project.integrations ?? []);
+ // Configured packages come from Project, which has already resolved provider
+ // identity over configured, autolinked, and local packages. Loading them
+ // again here would let upgrade run codemods from a package Project set aside.
+ const configured = project.loadedIntegrations.filter(
+ integration =>
+ !integration.__autolinked && configuredSpecs.has(integration.__spec),
+ );
+ // A package that lists itself runs its installed copy's released codemods,
+ // never the work in progress being authored, so that copy stands in for it.
+ const local = project.loadedIntegrations.find(
+ integration => integration.__local,
+ );
+ const selfListed = local != null && configured.includes(local);
+ if (local != null && selfListed && project.configPath) {
+ const installed = await loadIntegrations([local.__spec], {
+ cwd: path.dirname(project.configPath),
+ resolveProviders: false,
+ });
+ configured.splice(configured.indexOf(local), 1, ...installed);
+ }
+ const extraSpecs = uniqueFiles(extraIntegrationSpecs ?? []).filter(
+ spec => !configuredSpecs.has(spec),
+ );
+ const extras =
+ extraSpecs.length === 0
+ ? []
+ : await loadIntegrations(extraSpecs, {resolveProviders: false});
+ // Naming the package being authored with --integration asks for its
+ // installed copy too, so the local package must not claim against it.
+ const localStandsIn =
+ local != null &&
+ (selfListed || extras.some(extra => extra.name === local.name));
+ // Autolinked packages and the package being authored join the pass only as
+ // claimants: every other command uses them for their provider IDs, but
+ // upgrade has never run their codemods and still does not. An extra that
+ // names one of them opts it in, so the extra stands in for that claimant.
+ const extraIdentities = new Set(extras.map(packageIdentity));
+ const claimantsOnly = project.loadedIntegrations.filter(
+ integration =>
+ (integration.__autolinked || (integration.__local && !localStandsIn)) &&
+ !extraIdentities.has(packageIdentity(integration)),
+ );
+ const resolved = markProviderConflicts([
+ ...configured,
+ ...claimantsOnly,
+ ...extras,
]);
- const integrations = await loadIntegrations(integrationSpecs);
+ // Claimants leave by package directory, not object identity: the pass can
+ // return one as a new conflict entry, and upgrade must not warn that a
+ // package every other command uses contributes nothing.
+ const claimantDirs = new Set(
+ claimantsOnly.map(integration => integration.__packageDir),
+ );
+ const integrations = resolved.filter(
+ integration =>
+ integration.__packageDir == null ||
+ !claimantDirs.has(integration.__packageDir),
+ );
return {postCodemodHooks, integrations};
}
diff --git a/packages/cli/api/upgrade/project-context.test.mjs b/packages/cli/api/upgrade/project-context.test.mjs
new file mode 100644
index 0000000000..f75db0dae9
--- /dev/null
+++ b/packages/cli/api/upgrade/project-context.test.mjs
@@ -0,0 +1,272 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `loadProjectContext` agrees with Project on provider identity, so
+ * `astryx upgrade` never runs codemods from a package Project set aside.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadProjectContext, selectIntegrationCodemodsFor} from './_adapter.mjs';
+
+let tmpDir;
+let originalCwd;
+
+beforeEach(() => {
+ originalCwd = process.cwd();
+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-upgrade-context-'));
+});
+
+afterEach(() => {
+ process.chdir(originalCwd);
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Install an integration package that ships one 0.2.0 codemod.
+ * @param {string} name
+ * @param {string} version
+ * @param {Record<string, unknown>} [manifest]
+ */
+function installWithCodemod(name, version, manifest = {}) {
+ const pkgDir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+ const codemodDir = path.join(pkgDir, 'codemods', '0.2.0');
+ fs.mkdirSync(codemodDir, {recursive: true});
+ fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify({name, version}));
+ fs.writeFileSync(
+ path.join(pkgDir, 'astryx.integration.mjs'),
+ `export default ${JSON.stringify({codemods: './codemods', ...manifest})};\n`,
+ );
+ fs.writeFileSync(
+ path.join(codemodDir, 'rename.mjs'),
+ "export default {type: 'code', title: 'Rename', transform: file => file.source};\n",
+ );
+}
+
+/** @param {string[]} integrations */
+function configure(integrations) {
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.config.mjs'),
+ `export default ${JSON.stringify({integrations})};\n`,
+ );
+}
+
+describe('loadProjectContext provider identity', () => {
+ it('keeps codemods from a configured package the authored package sets aside', async () => {
+ installWithCodemod('@acme/widgets', '1.0.0');
+ configure(['@acme/widgets']);
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: '@acme/renamed', version: '2.0.0-dev'}),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ "export default {providerId: '@acme/widgets'};\n",
+ );
+
+ const {integrations} = await loadProjectContext(tmpDir);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ Boolean(integration.__providerConflict),
+ ]),
+ ).toEqual([['@acme/widgets', true]]);
+ expect(
+ await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+ ).toEqual([]);
+ });
+
+ it('still selects codemods from a configured package nothing else claims', async () => {
+ installWithCodemod('@acme/widgets', '1.0.0');
+ configure(['@acme/widgets']);
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+
+ const {integrations} = await loadProjectContext(tmpDir);
+ const selected = await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0');
+ expect(selected.map(entry => entry.version)).toEqual(['0.2.0']);
+ });
+
+ it('sets aside an --integration extra that claims a configured provider ID', async () => {
+ installWithCodemod('@acme/widgets', '1.0.0');
+ installWithCodemod('@acme/other', '1.0.0', {providerId: '@acme/widgets'});
+ configure(['@acme/widgets']);
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+ // `--integration` specs resolve from the process cwd, as they always have.
+ process.chdir(tmpDir);
+
+ const {integrations} = await loadProjectContext(tmpDir, ['@acme/other']);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ integration.__providerConflict?.claimedBy ?? null,
+ ]),
+ ).toEqual([
+ ['@acme/widgets', null],
+ ['@acme/other', '@acme/widgets'],
+ ]);
+ });
+
+ it('runs the installed copy of a package that lists itself, not its work in progress', async () => {
+ installWithCodemod('@acme/widgets', '1.0.0');
+ configure(['@acme/widgets']);
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: '@acme/widgets', version: '3.0.0-dev'}),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ "export default {codemods: './codemods'};\n",
+ );
+ fs.mkdirSync(path.join(tmpDir, 'codemods', '0.2.0'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, 'codemods', '0.2.0', 'local-wip.mjs'),
+ "export default {type: 'code', title: 'Local WIP', transform: file => file.source};\n",
+ );
+
+ const {integrations} = await loadProjectContext(tmpDir);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ integration.version,
+ Boolean(integration.__local),
+ Boolean(integration.__providerConflict),
+ ]),
+ ).toEqual([['@acme/widgets', '1.0.0', false, false]]);
+ const selected = JSON.stringify(
+ await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+ );
+ expect(selected).toContain('rename');
+ expect(selected).not.toContain('local-wip');
+ });
+
+ it('runs the installed copy when the authored package is named with --integration', async () => {
+ installWithCodemod('@acme/widgets', '1.0.0');
+ configure([]);
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: '@acme/widgets', version: '3.0.0-dev'}),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ "export default {codemods: './codemods'};\n",
+ );
+ fs.mkdirSync(path.join(tmpDir, 'codemods', '0.2.0'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, 'codemods', '0.2.0', 'local-wip.mjs'),
+ "export default {type: 'code', title: 'Local WIP', transform: file => file.source};\n",
+ );
+ process.chdir(tmpDir);
+
+ const {integrations} = await loadProjectContext(tmpDir, ['@acme/widgets']);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ integration.version,
+ Boolean(integration.__local),
+ integration.__providerConflict?.claimedBy ?? null,
+ ]),
+ ).toEqual([['@acme/widgets', '1.0.0', false, null]]);
+ const selected = JSON.stringify(
+ await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+ );
+ expect(selected).toContain('rename');
+ expect(selected).not.toContain('local-wip');
+ });
+
+ it("sets aside an --integration extra that claims an autolinked package's ID", async () => {
+ installWithCodemod('@acme/a', '1.0.0');
+ installWithCodemod('@acme/b', '1.0.0', {providerId: '@acme/a'});
+ configure([]);
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: 'consumer', dependencies: {'@acme/a': '1.0.0'}}),
+ );
+ process.chdir(tmpDir);
+
+ const {integrations} = await loadProjectContext(tmpDir, ['@acme/b']);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ integration.__providerConflict?.claimedBy ?? null,
+ ]),
+ ).toEqual([['@acme/b', '@acme/a']]);
+ expect(
+ await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+ ).toEqual([]);
+ });
+
+ it('runs an autolinked package the user names with --integration', async () => {
+ installWithCodemod('@acme/a', '1.0.0');
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: 'consumer', dependencies: {'@acme/a': '1.0.0'}}),
+ );
+ process.chdir(tmpDir);
+
+ const {integrations} = await loadProjectContext(tmpDir, ['@acme/a']);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ integration.__providerConflict?.claimedBy ?? null,
+ ]),
+ ).toEqual([['@acme/a', null]]);
+ const selected = await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0');
+ expect(selected.map(entry => entry.version)).toEqual(['0.2.0']);
+ });
+
+ it('never reports a claimant that every other command uses as set aside', async () => {
+ installWithCodemod('@acme/widgets', '1.0.0');
+ installWithCodemod('@acme/renamed', '2.0.0', {providerId: '@acme/widgets'});
+ configure(['@acme/widgets']);
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({
+ name: '@acme/widgets',
+ version: '3.0.0-dev',
+ dependencies: {'@acme/renamed': '2.0.0'},
+ }),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ "export default {providerId: '@acme/widgets-next'};\n",
+ );
+
+ const {integrations} = await loadProjectContext(tmpDir);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ integration.version,
+ integration.__providerConflict?.claimedBy ?? null,
+ ]),
+ ).toEqual([['@acme/widgets', '1.0.0', null]]);
+ });
+
+ it("sets aside an --integration extra that claims the authored package's ID", async () => {
+ installWithCodemod('@acme/widgets', '1.0.0');
+ configure([]);
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: '@acme/renamed', version: '2.0.0-dev'}),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ "export default {providerId: '@acme/widgets'};\n",
+ );
+ process.chdir(tmpDir);
+
+ const {integrations} = await loadProjectContext(tmpDir, ['@acme/widgets']);
+ expect(
+ integrations.map(integration => [
+ integration.name,
+ integration.__providerConflict?.claimedBy ?? null,
+ ]),
+ ).toEqual([['@acme/widgets', '@acme/renamed']]);
+ expect(
+ await selectIntegrationCodemodsFor(integrations, '0.1.0', '0.3.0'),
+ ).toEqual([]);
+ });
+});
diff --git a/packages/cli/assets/docs/README.md b/packages/cli/assets/docs/README.md
index dbd59235ab..6d5445aca1 100644
--- a/packages/cli/assets/docs/README.md
+++ b/packages/cli/assets/docs/README.md
@@ -48,3 +48,12 @@ The material is usually good; the finding is placement, not quality. It goes in
**Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/Contributing), or `CONTRIBUTING.md` when it is a step someone follows with the repo cloned. Never default it back to this directory.
Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
+
+## Sections are read one at a time
+
+`astryx docs <topic> --index` lists a topic's sections, and readers then open
+one section by its key. A section's key is its `id`, or a key derived from its
+title when it has none. Give a section an `id` when its title may change, since
+readers and extensions link to the key. Two sections in one topic cannot share
+a key. Keep each section small enough to read on its own: `astryx doctor` fails
+any section over 32 KB.
diff --git a/packages/cli/assets/docs/authoring.doc.mjs b/packages/cli/assets/docs/authoring.doc.mjs
new file mode 100644
index 0000000000..83177a3393
--- /dev/null
+++ b/packages/cli/assets/docs/authoring.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring`: every authoring schema, one section each.
+ *
+ * Built from the self-docs colocated under packages/cli/authoring, so it cannot
+ * drift from the schemas it describes. `astryx doctor` names a self-doc this
+ * topic cannot reach.
+ */
+
+import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = await buildAuthoringTopic();
diff --git a/packages/cli/assets/docs/cli-integrations.doc.mjs b/packages/cli/assets/docs/cli-integrations.doc.mjs
index 4a7b550ab7..2a59c077a3 100644
--- a/packages/cli/assets/docs/cli-integrations.doc.mjs
+++ b/packages/cli/assets/docs/cli-integrations.doc.mjs
@@ -22,6 +22,10 @@ export const docs = {
type: 'prose',
text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run `npx astryx docs getting-started`.',
},
+ {
+ type: 'prose',
+ text: 'Every file an integration author writes is documented field by field in `npx astryx docs authoring`: the manifest, astryx.config, codemods, identity, and each doc type. `npx astryx docs authoring --index` lists them, and `npx astryx docs authoring <key>` reads one.',
+ },
{
type: 'prose',
text: 'A consumer can still name the package explicitly when order or precedence matters:',
@@ -189,7 +193,7 @@ export const docs = {
},
{
type: 'prose',
- text: "`extends: 'x'` merges onto a topic instead of owning it: a section whose title matches one in the base replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
+ text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
},
{
type: 'list',
diff --git a/packages/cli/authoring/doctypes/_schema.mjs b/packages/cli/authoring/doctypes/_schema.mjs
index 8e86c19648..6d789280ba 100644
--- a/packages/cli/authoring/doctypes/_schema.mjs
+++ b/packages/cli/authoring/doctypes/_schema.mjs
@@ -3,16 +3,194 @@
/**
* @file Sealed doc load-boundary schemas (doctypes-internal).
*
- * These zod schemas are the implementation detail behind the doctypes parsers.
- * They are NOT part of the public authoring surface: nothing outside
- * `authoring/doctypes/**` imports them, and they never appear in a public type.
- * They accept BOTH the stamped formats (`type: 'component' | 'function' |
- * 'generic'`) and the legacy loose `export const docs = {...}` shape, so the
- * ~600+ existing docs keep validating unchanged.
+ * Existing doctypes keep their historical top-level passthrough policy so
+ * already-published docs continue to load. NamespaceDoc and every semantic
+ * content block are strict: a misspelled field cannot reach a renderer as
+ * missing data.
*/
import {z} from 'zod';
+/** @typedef {import('./base/type').AuthoredDocGraphFields} AuthoredDocGraphFieldsType */
+/** @typedef {import('./base/type').AuthoredDocKind} AuthoredDocKind */
+/** @typedef {import('./namespace/type').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./reference/type').ReferenceContentBlock} ReferenceContentBlock */
+
+const nonEmptyString = z.string().min(1);
+
+/** Every authored doc-kind discriminant accepted by parseDoc. */
+export const AuthoredDocKindSchema = z.enum([
+ 'component',
+ 'function',
+ 'generic',
+ 'page',
+ 'block',
+ 'schema',
+ 'command',
+ 'enum',
+ 'namespace',
+]);
+
+/** Shared optional graph fields for every authored doc kind. */
+export const AuthoredDocGraphFields = {
+ placement: z
+ .object({
+ parent: nonEmptyString,
+ slot: nonEmptyString.optional(),
+ order: z.number().int().safe().optional(),
+ })
+ .strict()
+ .optional(),
+ aliases: z.array(nonEmptyString).optional(),
+ audience: z.enum(['public', 'internal']).optional(),
+};
+
+const _AuthoredDocGraphSchema = z.object(AuthoredDocGraphFields).strict();
+
+/**
+ * @typedef {import('../_shared/contract').Expect<
+ * import('../_shared/contract').MutuallyAssignable<
+ * z.infer<typeof _AuthoredDocGraphSchema>,
+ * AuthoredDocGraphFieldsType
+ * >
+ * >} _AuthoredDocGraphDriftLock
+ */
+
+const ProseBlockSchema = z
+ .object({type: z.literal('prose'), text: nonEmptyString})
+ .strict();
+const HeadingBlockSchema = z
+ .object({
+ type: z.literal('heading'),
+ level: z.union([z.literal(3), z.literal(4), z.literal(5), z.literal(6)]),
+ text: nonEmptyString,
+ })
+ .strict();
+const CodeBlockSchema = z
+ .object({
+ type: z.literal('code'),
+ lang: nonEmptyString,
+ code: z.string(),
+ label: nonEmptyString.optional(),
+ })
+ .strict();
+const TableBlockSchema = z
+ .object({
+ type: z.literal('table'),
+ headers: z.array(z.string()).min(1),
+ rows: z.array(z.array(z.string())),
+ })
+ .strict()
+ .superRefine((table, context) => {
+ table.rows.forEach((row, index) => {
+ if (row.length !== table.headers.length) {
+ context.addIssue({
+ code: 'custom',
+ path: ['rows', index],
+ message: `expected ${table.headers.length} cells`,
+ });
+ }
+ });
+ });
+const ListBlockSchema = z
+ .object({
+ type: z.literal('list'),
+ style: z.enum(['ordered', 'unordered', 'do', 'dont']),
+ items: z.array(nonEmptyString).min(1),
+ })
+ .strict();
+const TokenReferenceBlockSchema = z
+ .object({
+ type: z.literal('token-ref'),
+ topic: nonEmptyString,
+ section: nonEmptyString,
+ })
+ .strict();
+const WorkflowBlockSchema = z
+ .object({
+ type: z.literal('workflow'),
+ title: nonEmptyString.optional(),
+ steps: z
+ .array(
+ z
+ .object({
+ title: nonEmptyString,
+ description: nonEmptyString.optional(),
+ references: z.array(nonEmptyString).min(1).optional(),
+ })
+ .strict(),
+ )
+ .min(1),
+ })
+ .strict();
+const CollectionBlockSchema = z
+ .object({
+ type: z.literal('collection'),
+ title: nonEmptyString.optional(),
+ source: z.object({slot: nonEmptyString}).strict(),
+ presentation: z.enum(['list', 'cards', 'compact']).optional(),
+ whenEmpty: z.enum(['show', 'omit']).optional(),
+ })
+ .strict();
+const ReferenceBlockSchema = z
+ .object({
+ type: z.literal('reference'),
+ target: nonEmptyString,
+ projection: z
+ .object({
+ fields: z.array(nonEmptyString).min(1).optional(),
+ sections: z.array(nonEmptyString).min(1).optional(),
+ })
+ .strict()
+ .optional(),
+ presentation: z.enum(['summary', 'compact', 'full']).optional(),
+ })
+ .strict();
+
+/** Runtime schema for every existing and V1 semantic content block. */
+export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
+ ProseBlockSchema,
+ HeadingBlockSchema,
+ CodeBlockSchema,
+ TableBlockSchema,
+ ListBlockSchema,
+ TokenReferenceBlockSchema,
+ WorkflowBlockSchema,
+ CollectionBlockSchema,
+ ReferenceBlockSchema,
+]);
+
+/**
+ * @typedef {import('../_shared/contract').Expect<
+ * import('../_shared/contract').Equal<
+ * z.infer<typeof ReferenceContentBlockSchema>,
+ * ReferenceContentBlock
+ * >
+ * >} _ReferenceContentBlockDriftLock
+ */
+
+const ReferenceSectionSchema = z
+ .object({
+ id: nonEmptyString.optional(),
+ title: nonEmptyString,
+ category: z.string().optional(),
+ content: z.array(ReferenceContentBlockSchema),
+ previewType: z
+ .enum([
+ 'swatch',
+ 'shadow-box',
+ 'radius-box',
+ 'spacing-bar',
+ 'size-bar',
+ 'border-line',
+ 'duration-bar',
+ 'easing-curve',
+ 'font-sample',
+ ])
+ .optional(),
+ })
+ .strict();
+
const PropSchema = z
.object({
name: z.string().min(1, 'prop name is required'),
@@ -42,6 +220,7 @@ const ReturnSchema = z
.passthrough();
const BaseDocFields = {
+ ...AuthoredDocGraphFields,
name: z.string().min(1, 'name is required'),
displayName: z.string().optional(),
description: z.string().optional(),
@@ -56,21 +235,22 @@ const BaseDocFields = {
isHiddenFromOverview: z.boolean().optional(),
};
-/** New-format stamped component doc (`type: 'component'`). */
-export const ComponentDocKindSchema = z
+const ComponentBaseSchema = z
.object({
...BaseDocFields,
type: z.literal('component'),
- props: z.array(PropSchema),
theming: z.unknown().optional(),
playground: z.unknown().optional(),
examples: z.array(z.unknown()).optional(),
})
.passthrough();
-/** Return entry for the generalized function doc: `name` is optional so CLI/API
- * functions can document their `{type, data}` envelope entries (which have no
- * field name), while hooks keep listing named return fields. */
+/** New-format stamped component doc (`type: 'component'`). */
+export const ComponentDocKindSchema = ComponentBaseSchema.extend({
+ props: z.array(PropSchema),
+});
+
+/** Return entry for generalized function docs. */
const FunctionReturnSchema = z
.object({
name: z.string().min(1).optional(),
@@ -79,8 +259,7 @@ const FunctionReturnSchema = z
})
.passthrough();
-/** New-format stamped function doc (`type: 'function'`) — hooks and CLI/API
- * functions alike (the discriminant and schema are shared). */
+/** New-format stamped function doc (`type: 'function'`). */
export const FunctionDocKindSchema = z
.object({
...BaseDocFields,
@@ -90,30 +269,52 @@ export const FunctionDocKindSchema = z
})
.passthrough();
-/** New-format stamped generic reference/topic doc (`type: 'generic'`). */
+/**
+ * Stamped generic reference/topic doc (`type: 'generic'`). `title` and
+ * `sections` stay optional at this parser boundary for docs produced by the
+ * shipped v0.3.0 factory-removal codemod. When present, all rich fields and
+ * semantic blocks are validated.
+ */
export const GenericDocKindSchema = z
.object({
...BaseDocFields,
type: z.literal('generic'),
- // Declared rather than left to the passthrough: these two are read by
- // docs discovery to resolve one topic against another, so a non-string
- // should fail at the load boundary, not halfway through resolution.
- replaces: z.string().optional(),
- extends: z.string().optional(),
+ title: nonEmptyString.optional(),
+ sections: z.array(ReferenceSectionSchema).min(1).optional(),
+ replaces: nonEmptyString.optional(),
+ extends: nonEmptyString.optional(),
+ tokenCategory: z.string().optional(),
})
- .passthrough();
+ .passthrough()
+ .superRefine((doc, context) => {
+ if (doc.replaces != null && doc.extends != null) {
+ context.addIssue({
+ code: 'custom',
+ path: ['extends'],
+ message: 'declares both `replaces` and `extends`; choose one',
+ });
+ }
+ const sectionIds = new Set();
+ doc.sections?.forEach((section, index) => {
+ if (section.id == null) return;
+ if (sectionIds.has(section.id)) {
+ context.addIssue({
+ code: 'custom',
+ path: ['sections', index, 'id'],
+ message: `duplicate section id "${section.id}"`,
+ });
+ }
+ sectionIds.add(section.id);
+ });
+ });
-/** Recursive field descriptor for a SchemaDoc (objects nest via `fields`). The
- * explicit cast breaks the self-referential type inference (TS7022) that the
- * authoring-contract `checkJs` pass would otherwise flag. */
+/** Recursive field descriptor for a SchemaDoc. */
const SchemaFieldSchema =
/** @type {import('zod').ZodType<import('./schema/type').SchemaFieldDoc>} */ (
z.lazy(() =>
z
.object({
name: z.string().min(1, 'field name is required'),
- // `{error}` covers a missing (undefined) type; `.min(1)` covers an
- // empty string — both give the same author-friendly message.
type: z
.string({error: 'field type is required'})
.min(1, 'field type is required'),
@@ -128,15 +329,15 @@ const SchemaFieldSchema =
)
);
-/** New stamped schema doc (`type: 'schema'`) — documents an authored object. */
+/** New stamped schema doc (`type: 'schema'`). */
export const SchemaDocKindSchema = z
.object({
+ ...AuthoredDocGraphFields,
type: z.literal('schema'),
name: z.string().min(1, 'name is required'),
displayName: z.string().min(1, 'displayName is required'),
description: z.string(),
namespace: z.string().optional(),
- aliases: z.array(z.string()).optional(),
appliesTo: z.string().optional(),
fields: z.array(SchemaFieldSchema),
examples: z
@@ -146,21 +347,20 @@ export const SchemaDocKindSchema = z
.passthrough(),
)
.optional(),
- notes: z.array(z.unknown()).optional(),
+ notes: z.array(ReferenceContentBlockSchema).optional(),
})
.passthrough();
-/** New stamped command doc (`type: 'command'`) — a function's terminal binding;
- * references a FunctionDoc via `fn`. */
+/** New stamped command doc (`type: 'command'`). */
export const CommandDocKindSchema = z
.object({
+ ...AuthoredDocGraphFields,
type: z.literal('command'),
name: z.string().min(1, 'name is required'),
displayName: z.string().min(1, 'displayName is required'),
summary: z.string(),
description: z.string().optional(),
namespace: z.string().optional(),
- aliases: z.array(z.string()).optional(),
fn: z.string().optional(),
args: z
.array(
@@ -207,20 +407,19 @@ export const CommandDocKindSchema = z
.array(z.object({code: z.number(), when: z.string()}).passthrough())
.optional(),
related: z.array(z.string()).optional(),
- notes: z.array(z.unknown()).optional(),
+ notes: z.array(ReferenceContentBlockSchema).optional(),
})
.passthrough();
-/** New stamped enum doc (`type: 'enum'`) — a closed vocabulary (error codes,
- * response-type discriminants). */
+/** New stamped enum doc (`type: 'enum'`). */
export const EnumDocKindSchema = z
.object({
+ ...AuthoredDocGraphFields,
type: z.literal('enum'),
name: z.string().min(1, 'name is required'),
displayName: z.string().min(1, 'displayName is required'),
description: z.string(),
namespace: z.string().optional(),
- aliases: z.array(z.string()).optional(),
members: z.array(
z
.object({
@@ -233,8 +432,99 @@ export const EnumDocKindSchema = z
})
.passthrough();
-// ── Legacy loose format (unchanged, kept for back-compat) ─────────────
+const NamespaceSlotSchema = z
+ .object({
+ title: nonEmptyString,
+ accepts: z
+ .object({
+ kinds: z.array(AuthoredDocKindSchema).min(1),
+ providers: z.enum(['same', 'configured']).optional(),
+ })
+ .strict(),
+ })
+ .strict();
+
+/** The one new authored doctype: a hierarchy and layout owner. */
+export const NamespaceDocKindSchema = z
+ .object({
+ ...AuthoredDocGraphFields,
+ type: z.literal('namespace'),
+ name: nonEmptyString,
+ title: nonEmptyString,
+ summary: nonEmptyString,
+ keywords: z.array(nonEmptyString).optional(),
+ slots: z
+ .record(nonEmptyString, NamespaceSlotSchema)
+ .refine(slots => Object.keys(slots).length > 0, {
+ message: 'at least one slot is required',
+ }),
+ adopts: z
+ .array(
+ z
+ .object({
+ source: z
+ .object({
+ group: nonEmptyString,
+ kinds: z.array(AuthoredDocKindSchema).min(1).optional(),
+ })
+ .strict(),
+ into: nonEmptyString,
+ groupBy: z.literal('kind').optional(),
+ })
+ .strict(),
+ )
+ .optional(),
+ blocks: z.array(ReferenceContentBlockSchema).optional(),
+ })
+ .strict()
+ .superRefine((doc, context) => {
+ const slots = new Set(Object.keys(doc.slots));
+ doc.adopts?.forEach((rule, index) => {
+ const slot = doc.slots[rule.into];
+ if (slot == null) {
+ context.addIssue({
+ code: 'custom',
+ path: ['adopts', index, 'into'],
+ message: `must name a declared slot; received "${rule.into}"`,
+ });
+ return;
+ }
+ /** @type {AuthoredDocKind[]} */
+ const adoptedKinds =
+ rule.groupBy === 'kind' ? ['namespace'] : (rule.source.kinds ?? []);
+ adoptedKinds.forEach(kind => {
+ if (!slot.accepts.kinds.includes(kind)) {
+ context.addIssue({
+ code: 'custom',
+ path: ['adopts', index, 'into'],
+ message: `slot "${rule.into}" does not accept adopted kind "${kind}"`,
+ });
+ }
+ });
+ });
+ doc.blocks?.forEach((block, index) => {
+ if (block.type === 'collection' && !slots.has(block.source.slot)) {
+ context.addIssue({
+ code: 'custom',
+ path: ['blocks', index, 'source', 'slot'],
+ message: `must name a declared slot; received "${block.source.slot}"`,
+ });
+ }
+ });
+ });
+
+/**
+ * @typedef {import('../_shared/contract').Expect<
+ * import('../_shared/contract').Equal<
+ * z.infer<typeof NamespaceDocKindSchema>,
+ * NamespaceDoc
+ * >
+ * >} _NamespaceDocDriftLock
+ */
+
+// Legacy loose format stays permissive for backward compatibility.
const LegacyBaseDocSchema = z.object({
+ ...AuthoredDocGraphFields,
name: z.string().min(1, 'name is required'),
displayName: z.string().optional(),
description: z.string().optional(),
@@ -255,6 +545,37 @@ const LegacyBaseDocSchema = z.object({
relatedHooks: z.array(z.string()).optional(),
});
+const LegacyReferenceDocSchema = LegacyBaseDocSchema.extend({
+ title: nonEmptyString,
+ description: z.string(),
+ sections: z.array(ReferenceSectionSchema).min(1),
+ replaces: nonEmptyString.optional(),
+ extends: nonEmptyString.optional(),
+ tokenCategory: z.string().optional(),
+})
+ .passthrough()
+ .superRefine((doc, context) => {
+ if (doc.replaces != null && doc.extends != null) {
+ context.addIssue({
+ code: 'custom',
+ path: ['extends'],
+ message: 'declares both `replaces` and `extends`; choose one',
+ });
+ }
+ const sectionIds = new Set();
+ doc.sections.forEach((section, index) => {
+ if (section.id == null) return;
+ if (sectionIds.has(section.id)) {
+ context.addIssue({
+ code: 'custom',
+ path: ['sections', index, 'id'],
+ message: `duplicate section id "${section.id}"`,
+ });
+ }
+ sectionIds.add(section.id);
+ });
+ });
+
const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({
props: z.array(PropSchema),
}).passthrough();
@@ -274,10 +595,11 @@ const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({
props: z.array(PropSchema),
}).passthrough();
-/** The permissive legacy union (sub-component first, then hook, multi, single). */
+/** The permissive legacy union (sub-component, hook, multi, single, then reference). */
export const LegacyDocSchema = z.union([
LegacySubComponentDocSchema,
LegacyHookDocSchema,
LegacyMultiComponentDocSchema,
LegacySingleComponentDocSchema,
+ LegacyReferenceDocSchema,
]);
diff --git a/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs b/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
new file mode 100644
index 0000000000..741a790d4b
--- /dev/null
+++ b/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for graph metadata shared by every authored doc kind.
+ * @position packages/cli/authoring/doctypes/base — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+ type: 'schema',
+ name: 'authored-doc-graph-fields',
+ displayName: 'Authored doc graph fields',
+ namespace: 'authoring',
+ description:
+ 'Optional placement, compatibility aliases, and audience fields shared by every authored documentation kind.',
+ appliesTo: 'Every supported .doc.mjs object',
+ fields: [
+ {
+ name: 'placement',
+ type: 'DocPlacement',
+ description:
+ 'Requests one canonical parent. The compiler fails invalid explicit placement instead of silently using Unorganized.',
+ fields: [
+ {
+ name: 'placement.parent',
+ type: 'string',
+ description: 'Stable reference to the requested parent namespace.',
+ required: true,
+ },
+ {
+ name: 'placement.slot',
+ type: 'string',
+ description: 'Named slot owned by the parent namespace.',
+ },
+ {
+ name: 'placement.order',
+ type: 'number',
+ description: 'Integer sibling order within the slot.',
+ },
+ ],
+ },
+ {
+ name: 'aliases',
+ type: 'string[]',
+ description:
+ 'Prior names or routes retained for compatibility. Aliases do not create another identity.',
+ },
+ {
+ name: 'audience',
+ type: "'public' | 'internal'",
+ description: 'Bundle audience. Omit for public documentation.',
+ default: "'public'",
+ },
+ ],
+};
diff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.ts
index 0db4167261..b88c5e7804 100644
--- a/packages/cli/authoring/doctypes/base/type.ts
+++ b/packages/cli/authoring/doctypes/base/type.ts
@@ -4,6 +4,42 @@
* @file Shared leaf primitives used across the doc types.
*/
+/** Every authored documentation kind accepted by `parseDoc`. */
+export type AuthoredDocKind =
+ | 'component'
+ | 'function'
+ | 'generic'
+ | 'page'
+ | 'block'
+ | 'schema'
+ | 'command'
+ | 'enum'
+ | 'namespace';
+
+/** Visibility of an authored doc in a compiled audience-specific bundle. */
+export type DocAudience = 'public' | 'internal';
+
+/**
+ * Optional canonical placement request. The compiler resolves `parent` as a
+ * stable doc reference. `slot` selects one parent-owned slot, and `order`
+ * provides deterministic sibling ordering inside that slot.
+ */
+export interface DocPlacement {
+ parent: string;
+ slot?: string;
+ order?: number;
+}
+
+/** Graph metadata shared by every authored doc kind. */
+export interface AuthoredDocGraphFields {
+ /** Requested canonical parent. Omit to use source adoption or Unorganized. */
+ placement?: DocPlacement;
+ /** Prior routes or names that must continue to resolve to this stable doc. */
+ aliases?: string[];
+ /** Bundle audience. Omit for public docs. */
+ audience?: DocAudience;
+}
+
/**
* Stable public identity for generated registry resources.
*
diff --git a/packages/cli/authoring/doctypes/command/type.ts b/packages/cli/authoring/doctypes/command/type.ts
index 457e229275..7ee66e4582 100644
--- a/packages/cli/authoring/doctypes/command/type.ts
+++ b/packages/cli/authoring/doctypes/command/type.ts
@@ -9,6 +9,7 @@
* `--help`. Colocated at `clients/cli/commands/<name>.doc.mjs`.
*/
+import type {AuthoredDocGraphFields} from '../base/type';
import type {ReferenceContentBlock} from '../reference/type';
/** A positional argument. `param` links it to a FunctionDoc param for its description. */
@@ -53,7 +54,7 @@ export interface CommandExampleDoc {
* /\*\* @type {import('@astryxdesign/cli/authoring').CommandDoc} \*\/
* export const doc = { type: 'command', name: 'search', fn: 'search', ... };
*/
-export interface CommandDoc {
+export interface CommandDoc extends AuthoredDocGraphFields {
/** Doc-kind discriminant. */
type?: 'command';
/** Command path, e.g. 'search' | 'theme build'. */
diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjs
index 2bb83a9258..5fba8da8d9 100644
--- a/packages/cli/authoring/doctypes/component/component.doc.mjs
+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs
@@ -56,7 +56,7 @@ export const doc = {
name: 'keywords',
type: 'string[]',
description:
- 'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, shadcn). Lowercase. Used by `astryx component <term>` fuzzy matching.',
+ 'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, and others). Lowercase. Used by `astryx component <term>` fuzzy matching.',
},
{
name: 'hiddenComponents',
diff --git a/packages/cli/authoring/doctypes/component/type.ts b/packages/cli/authoring/doctypes/component/type.ts
index 46f1d0ed28..2895ba39d3 100644
--- a/packages/cli/authoring/doctypes/component/type.ts
+++ b/packages/cli/authoring/doctypes/component/type.ts
@@ -5,6 +5,7 @@
*/
import type {
+ AuthoredDocGraphFields,
ComponentAccessibilityRequirement,
ComponentAnatomyElement,
ComponentBestPractice,
@@ -24,7 +25,7 @@ import type {
* Shared fields between single-component and multi-component docs.
* Do not use this interface directly — use `ComponentDoc` (the union type).
*/
-export interface ComponentBaseDoc {
+export interface ComponentBaseDoc extends AuthoredDocGraphFields {
/** Doc-kind discriminant for the stamped default-export format
* (`export default { type: 'component', ... }`). Optional: legacy
* `export const docs = {...}` docs omit it, and `parseDoc` falls back to
@@ -49,7 +50,7 @@ export interface ComponentBaseDoc {
import?: string;
/** Search keywords for CLI discovery. Terms a developer might type when
* looking for this component: synonyms, related UI concepts, and common
- * names from other design systems (MUI, Chakra, Radix, shadcn).
+ * names from other design systems (MUI, Chakra, Radix, and others).
* Lowercase only. Used by `astryx component <term>` for fuzzy matching.
* e.g. `['accordion', 'expand', 'toggle', 'disclosure']` for Collapsible */
keywords?: string[];
diff --git a/packages/cli/authoring/doctypes/enum/type.ts b/packages/cli/authoring/doctypes/enum/type.ts
index 5fba25721d..f32c106c7d 100644
--- a/packages/cli/authoring/doctypes/enum/type.ts
+++ b/packages/cli/authoring/doctypes/enum/type.ts
@@ -5,6 +5,8 @@
* discriminants). Colocated next to the source of truth it documents.
*/
+import type {AuthoredDocGraphFields} from '../base/type';
+
/** One member of an enumerated vocabulary. */
export interface EnumMemberDoc {
/** The literal value, e.g. 'ERR_UNKNOWN_TOPIC' | 'component.list'. */
@@ -21,7 +23,7 @@ export interface EnumMemberDoc {
* /\*\* @type {import('@astryxdesign/cli/authoring').EnumDoc} \*\/
* export const doc = { type: 'enum', name: 'error-codes', ... };
*/
-export interface EnumDoc {
+export interface EnumDoc extends AuthoredDocGraphFields {
/** Doc-kind discriminant. */
type?: 'enum';
/** URL-safe identifier, used as the docs slug within its namespace. */
diff --git a/packages/cli/authoring/doctypes/function/type.ts b/packages/cli/authoring/doctypes/function/type.ts
index 962ffff207..5844181c83 100644
--- a/packages/cli/authoring/doctypes/function/type.ts
+++ b/packages/cli/authoring/doctypes/function/type.ts
@@ -10,7 +10,11 @@
* here — the function does not know it has a CLI.
*/
-import type {HookParamDoc, UsageDoc} from '../base/type';
+import type {
+ AuthoredDocGraphFields,
+ HookParamDoc,
+ UsageDoc,
+} from '../base/type';
/**
* A documented return. Hooks list named return fields (`name` set); CLI/API
@@ -45,7 +49,7 @@ export interface FunctionExampleDoc {
* /\*\* @type {import('@astryxdesign/cli/authoring').FunctionDoc} \*\/
* export const doc = { type: 'function', kind: 'api', name: 'search', ... };
*/
-export interface FunctionDoc {
+export interface FunctionDoc extends AuthoredDocGraphFields {
/** Doc-kind discriminant (shared with hooks). */
type?: 'function';
/** Export name, e.g. 'search' | 'useMediaQuery'. */
diff --git a/packages/cli/authoring/doctypes/hook/type.ts b/packages/cli/authoring/doctypes/hook/type.ts
index 250059244b..beab74a9f9 100644
--- a/packages/cli/authoring/doctypes/hook/type.ts
+++ b/packages/cli/authoring/doctypes/hook/type.ts
@@ -5,6 +5,7 @@
*/
import type {
+ AuthoredDocGraphFields,
ComponentAccessibilityRequirement,
ComponentBestPractice,
HookParamDoc,
@@ -27,7 +28,7 @@ import type {
* /\*\* @type {import('@astryxdesign/cli/authoring').HookDoc} \*\/
* export const docs = { ... };
*/
-export interface HookDoc {
+export interface HookDoc extends AuthoredDocGraphFields {
/** Doc-kind discriminant for the stamped default-export format
* (`export default { type: 'function', ... }`). Optional: legacy
* `export const docs = {...}` docs omit it. */
diff --git a/packages/cli/authoring/doctypes/legacy.mjs b/packages/cli/authoring/doctypes/legacy.mjs
index fb91bdee8d..d261b6e4a2 100644
--- a/packages/cli/authoring/doctypes/legacy.mjs
+++ b/packages/cli/authoring/doctypes/legacy.mjs
@@ -12,18 +12,19 @@ import {formatZodError} from '../_shared/errors.mjs';
/** @typedef {import('./types').ComponentDoc} ComponentDoc */
/** @typedef {import('./types').HookDoc} HookDoc */
+/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
/**
* Validate an unknown value as a legacy (unstamped) doc, or throw.
*
* @param {unknown} input
* @param {string} [label]
- * @returns {ComponentDoc | HookDoc}
+ * @returns {ComponentDoc | HookDoc | ReferenceDoc}
*/
export function parseLegacyDoc(input, label = 'doc') {
const result = LegacyDocSchema.safeParse(input);
if (!result.success) {
throw new Error(formatZodError(label, result.error));
}
- return /** @type {ComponentDoc | HookDoc} */ (result.data);
+ return /** @type {ComponentDoc | HookDoc | ReferenceDoc} */ (result.data);
}
diff --git a/packages/cli/authoring/doctypes/namespace/namespace.doc.mjs b/packages/cli/authoring/doctypes/namespace/namespace.doc.mjs
new file mode 100644
index 0000000000..6827e7d9ba
--- /dev/null
+++ b/packages/cli/authoring/doctypes/namespace/namespace.doc.mjs
@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for NamespaceDoc, the authored hierarchy and layout owner.
+ * @position packages/cli/authoring/doctypes/namespace — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+ type: 'schema',
+ name: 'namespace-doc',
+ displayName: 'NamespaceDoc',
+ namespace: 'authoring',
+ description:
+ 'Declares named navigation slots and renderer-neutral layout blocks for already-discovered docs. It never scans folders or copies child documents.',
+ appliesTo: '<namespace>.doc.mjs',
+ fields: [
+ {
+ name: 'type',
+ type: "'namespace'",
+ description: 'Doc-kind discriminant.',
+ required: true,
+ },
+ {
+ name: 'name',
+ type: 'string',
+ description:
+ 'Stable provider-local identity. Moving the namespace does not change this value.',
+ required: true,
+ },
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Human-readable page title.',
+ required: true,
+ },
+ {
+ name: 'summary',
+ type: 'string',
+ description: 'One-line summary used in listings and search results.',
+ required: true,
+ },
+ {
+ name: 'placement',
+ type: 'DocPlacement',
+ description:
+ 'Optional canonical parent request: {parent, slot?, order?}. Invalid explicit placement fails compilation instead of falling back.',
+ },
+ {
+ name: 'aliases',
+ type: 'string[]',
+ description:
+ 'Prior names or routes that must keep resolving to this doc.',
+ },
+ {
+ name: 'audience',
+ type: "'public' | 'internal'",
+ description: "Bundle audience. Defaults to 'public'.",
+ default: "'public'",
+ },
+ {
+ name: 'keywords',
+ type: 'string[]',
+ description: 'Search terms not already present in the title or summary.',
+ },
+ {
+ name: 'slots',
+ type: 'Record<string, NamespaceSlot>',
+ description:
+ 'Named placement and collection targets. Each slot declares a title and accepted doc kinds; configured providers require an explicit extension slot.',
+ required: true,
+ },
+ {
+ name: 'adopts',
+ type: 'NamespaceAdoptionRule[]',
+ description:
+ 'Provider-local rules that adopt otherwise-unplaced docs from a logical discovery group. They never scan a folder.',
+ },
+ {
+ name: 'blocks',
+ type: 'ReferenceContentBlock[]',
+ description:
+ 'Ordered layout content. V1 adds only workflow, collection, and reference to the existing prose, heading, code, table, list, and token-ref blocks.',
+ },
+ ],
+ examples: [
+ {
+ label: 'A CLI namespace with one adopted source group',
+ code: `/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'cli',
+ title: 'Astryx CLI',
+ summary: 'Commands, APIs, and integration authoring.',
+ slots: {
+ guides: {title: 'Guides', accepts: {kinds: ['namespace', 'generic']}},
+ reference: {
+ title: 'Reference',
+ accepts: {kinds: ['namespace', 'command']},
+ },
+ },
+ adopts: [{
+ source: {group: 'cli-commands', kinds: ['command']},
+ into: 'reference',
+ }],
+ blocks: [
+ {type: 'collection', source: {slot: 'guides'}, presentation: 'cards'},
+ {type: 'collection', source: {slot: 'reference'}, presentation: 'compact'},
+ ],
+};`,
+ },
+ ],
+ notes: [
+ {
+ type: 'prose',
+ text: 'Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.',
+ },
+ {
+ type: 'list',
+ style: 'dont',
+ items: [
+ 'Use a directory as implicit navigation.',
+ 'Put JSX, HTML, ANSI, callbacks, or custom renderer code in a doc.',
+ 'Use choice, callout, or checklist blocks before the full block-extension contract exists.',
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/authoring/doctypes/namespace/parse.mjs b/packages/cli/authoring/doctypes/namespace/parse.mjs
new file mode 100644
index 0000000000..1289693c58
--- /dev/null
+++ b/packages/cli/authoring/doctypes/namespace/parse.mjs
@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Namespace doc parser. Zod is sealed in `../_schema.mjs`; consumers call
+ * `parseNamespace` or use `parseDoc`.
+ */
+
+import {NamespaceDocKindSchema} from '../_schema.mjs';
+import {formatZodError} from '../../_shared/errors.mjs';
+
+/** @typedef {import('../types').NamespaceDoc} NamespaceDoc */
+
+/**
+ * Validate an unknown value as a NamespaceDoc, or throw a readable error.
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {NamespaceDoc}
+ */
+export function parseNamespace(input, label = 'namespace doc') {
+ const result = NamespaceDocKindSchema.safeParse(input);
+ if (!result.success) {
+ throw new Error(formatZodError(label, result.error));
+ }
+ return result.data;
+}
diff --git a/packages/cli/authoring/doctypes/namespace/parse.test.mjs b/packages/cli/authoring/doctypes/namespace/parse.test.mjs
new file mode 100644
index 0000000000..22f6e8b2d8
--- /dev/null
+++ b/packages/cli/authoring/doctypes/namespace/parse.test.mjs
@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {parseDoc, parseNamespace, parseReference} from '../../index.mjs';
+
+const namespaceDoc = {
+ type: 'namespace',
+ name: 'integrations',
+ title: 'Author integrations',
+ summary: 'Publish reusable Astryx packages.',
+ aliases: ['cli-integrations'],
+ placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
+ slots: {
+ contributions: {
+ title: 'What do you want to publish?',
+ accepts: {kinds: ['namespace']},
+ },
+ providerGuides: {
+ title: 'Provider guidance',
+ accepts: {providers: 'configured', kinds: ['generic', 'schema']},
+ },
+ },
+ adopts: [
+ {
+ source: {group: 'cli-api', kinds: ['function', 'schema', 'enum']},
+ into: 'contributions',
+ groupBy: 'kind',
+ },
+ ],
+ blocks: [
+ {
+ type: 'workflow',
+ title: 'Package lifecycle',
+ steps: [
+ {title: 'Add', references: ['command:integration-add']},
+ {
+ title: 'Validate',
+ references: ['command:doctor-integration-validate'],
+ },
+ ],
+ },
+ {
+ type: 'collection',
+ source: {slot: 'contributions'},
+ presentation: 'cards',
+ },
+ {
+ type: 'reference',
+ target: 'schema:integration',
+ projection: {fields: ['components', 'docs']},
+ },
+ ],
+};
+
+describe('NamespaceDoc', () => {
+ it('accepts the reviewed plain-object shape through both parsers', () => {
+ expect(parseNamespace(namespaceDoc)).toEqual(namespaceDoc);
+ expect(parseDoc(namespaceDoc)).toEqual(namespaceDoc);
+ });
+
+ it('reports stable nested field paths', () => {
+ expect(() =>
+ parseNamespace({
+ ...namespaceDoc,
+ blocks: [{type: 'workflow', steps: [{title: ''}]}],
+ }),
+ ).toThrow(/blocks\.0\.steps\.0\.title/u);
+ });
+
+ it.each(['choice', 'callout', 'checklist'])(
+ 'rejects unsupported %s blocks',
+ type => {
+ expect(() => parseNamespace({...namespaceDoc, blocks: [{type}]})).toThrow(
+ /blocks\.0\.type/u,
+ );
+ },
+ );
+
+ it('rejects misspelled fields instead of silently dropping them', () => {
+ expect(() =>
+ parseNamespace({...namespaceDoc, summmary: 'misspelled'}),
+ ).toThrow(/summmary/u);
+ });
+
+ it('requires at least one declared slot', () => {
+ expect(() => parseNamespace({...namespaceDoc, slots: {}})).toThrow(
+ /at least one slot is required/u,
+ );
+ });
+
+ it('rejects a collection that names an undeclared slot', () => {
+ expect(() =>
+ parseNamespace({
+ ...namespaceDoc,
+ blocks: [{type: 'collection', source: {slot: 'missing'}}],
+ }),
+ ).toThrow(/blocks\.0\.source\.slot.*declared slot/u);
+ });
+
+ it('rejects an adoption rule that names an undeclared slot', () => {
+ expect(() =>
+ parseNamespace({
+ ...namespaceDoc,
+ adopts: [{source: {group: 'cli-api'}, into: 'missing'}],
+ }),
+ ).toThrow(/adopts\.0\.into.*declared slot/u);
+ });
+
+ it('rejects an adoption rule whose generated kind is not accepted', () => {
+ expect(() =>
+ parseNamespace({
+ ...namespaceDoc,
+ adopts: [
+ {
+ source: {group: 'cli-api', kinds: ['command']},
+ into: 'providerGuides',
+ groupBy: 'kind',
+ },
+ ],
+ }),
+ ).toThrow(/does not accept adopted kind "namespace"/u);
+
+ expect(() =>
+ parseNamespace({
+ ...namespaceDoc,
+ adopts: [
+ {
+ source: {group: 'cli-api', kinds: ['command']},
+ into: 'providerGuides',
+ },
+ ],
+ }),
+ ).toThrow(/does not accept adopted kind "command"/u);
+ });
+});
+
+describe('semantic blocks in existing docs', () => {
+ it('accepts workflow, collection, and reference in a ReferenceDoc section', () => {
+ const parsed = parseReference({
+ type: 'generic',
+ name: 'publishing',
+ title: 'Publishing',
+ description: 'Publish an integration.',
+ sections: [
+ {
+ id: 'start',
+ title: 'Start',
+ content: namespaceDoc.blocks,
+ },
+ ],
+ });
+ expect(parsed.sections[0].id).toBe('start');
+ expect(parsed.sections[0].content.map(block => block.type)).toEqual([
+ 'workflow',
+ 'collection',
+ 'reference',
+ ]);
+ });
+
+ it('rejects an unknown stamped doc kind instead of treating it as legacy', () => {
+ expect(() => parseDoc({type: 'choice', name: 'x', props: []})).toThrow(
+ /unsupported type "choice"/u,
+ );
+ });
+});
diff --git a/packages/cli/authoring/doctypes/namespace/type.ts b/packages/cli/authoring/doctypes/namespace/type.ts
new file mode 100644
index 0000000000..2646f96b5f
--- /dev/null
+++ b/packages/cli/authoring/doctypes/namespace/type.ts
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Namespace doc types. A namespace owns navigation slots and a
+ * renderer-neutral layout over already-discovered docs. It never scans files
+ * or copies child documents.
+ */
+
+import type {AuthoredDocGraphFields, AuthoredDocKind} from '../base/type';
+import type {ReferenceContentBlock} from '../reference/type';
+
+/** Which providers may contribute appearances to a namespace slot. */
+export type NamespaceProviderScope = 'same' | 'configured';
+
+/** Constraints declared by the namespace that owns a slot. */
+export interface NamespaceSlotAcceptance {
+ /** Authored doc kinds accepted by this slot. */
+ kinds: AuthoredDocKind[];
+ /** Omit for the namespace provider; `configured` admits provider appearances. */
+ providers?: NamespaceProviderScope;
+}
+
+/** One named placement and collection target owned by a NamespaceDoc. */
+export interface NamespaceSlot {
+ /** Human-readable heading for children in this slot. */
+ title: string;
+ /** Which docs may be placed or shown in this slot. */
+ accepts: NamespaceSlotAcceptance;
+}
+
+/** One logical source group that a namespace may adopt. */
+export interface NamespaceAdoptionSource {
+ /** Provider-local discovery group, such as `cli-commands`. */
+ group: string;
+ /** Optional subset of authored kinds from the group. */
+ kinds?: AuthoredDocKind[];
+}
+
+/**
+ * Assigns otherwise-unplaced docs from one provider-local source group to a
+ * child namespace. Discovery defines groups; this rule never scans a folder.
+ */
+export interface NamespaceAdoptionRule {
+ source: NamespaceAdoptionSource;
+ /** Slot owned by this namespace that becomes the canonical destination. */
+ into: string;
+ /** Generate one child namespace per authored kind. */
+ groupBy?: 'kind';
+}
+
+/**
+ * An authored documentation namespace. Its ordered blocks control layout while
+ * slots and adoption rules describe where already-discovered docs may appear.
+ */
+export interface NamespaceDoc extends AuthoredDocGraphFields {
+ type: 'namespace';
+ /** Stable provider-local name. Navigation changes do not change this value. */
+ name: string;
+ /** Human-readable page title. */
+ title: string;
+ /** One-line summary shown in listings and search results. */
+ summary: string;
+ /** Search terms that are not already present in the title or summary. */
+ keywords?: string[];
+ /** Named child-placement and collection targets. */
+ slots: Record<string, NamespaceSlot>;
+ /** Optional source-adoption rules for otherwise-unplaced docs. */
+ adopts?: NamespaceAdoptionRule[];
+ /** Ordered renderer-neutral content and collection blocks. */
+ blocks?: ReferenceContentBlock[];
+}
diff --git a/packages/cli/authoring/doctypes/parse.mjs b/packages/cli/authoring/doctypes/parse.mjs
index a354d7dc37..9df666db44 100644
--- a/packages/cli/authoring/doctypes/parse.mjs
+++ b/packages/cli/authoring/doctypes/parse.mjs
@@ -15,6 +15,7 @@ import {parseTemplate} from './template/parse.mjs';
import {parseSchema} from './schema/parse.mjs';
import {parseCommand} from './command/parse.mjs';
import {parseEnum} from './enum/parse.mjs';
+import {parseNamespace} from './namespace/parse.mjs';
import {parseLegacyDoc} from './legacy.mjs';
/** @typedef {import('./types').ComponentDoc} ComponentDoc */
@@ -25,6 +26,7 @@ import {parseLegacyDoc} from './legacy.mjs';
/** @typedef {import('./types').SchemaDoc} SchemaDoc */
/** @typedef {import('./types').CommandDoc} CommandDoc */
/** @typedef {import('./types').EnumDoc} EnumDoc */
+/** @typedef {import('./types').NamespaceDoc} NamespaceDoc */
/**
* Validate an unknown loaded doc value into its typed shape, or throw.
@@ -34,7 +36,7 @@ import {parseLegacyDoc} from './legacy.mjs';
*
* @param {unknown} input
* @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc}
*/
export function parseDoc(input, label = 'doc') {
const type =
@@ -58,7 +60,11 @@ export function parseDoc(input, label = 'doc') {
return parseCommand(input, label);
case 'enum':
return parseEnum(input, label);
- default:
+ case 'namespace':
+ return parseNamespace(input, label);
+ case undefined:
return parseLegacyDoc(input, label);
+ default:
+ throw new Error(`${label} has unsupported type ${JSON.stringify(type)}.`);
}
}
diff --git a/packages/cli/authoring/doctypes/parse.test.mjs b/packages/cli/authoring/doctypes/parse.test.mjs
index dabb228592..b92a21031c 100644
--- a/packages/cli/authoring/doctypes/parse.test.mjs
+++ b/packages/cli/authoring/doctypes/parse.test.mjs
@@ -25,8 +25,18 @@ const goodComponent = {
displayName: 'Widget',
description: 'A small widget.',
props: [
- {name: 'label', type: 'string', description: 'Visible label.', required: true},
- {name: 'size', type: "'sm' | 'md'", description: 'Control size.', default: "'md'"},
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Visible label.',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Control size.',
+ default: "'md'",
+ },
],
};
@@ -35,7 +45,9 @@ const goodFunction = {
name: 'useThing',
displayName: 'useThing',
description: 'A thing hook.',
- params: [{name: 'input', type: 'string', description: 'The input.', required: true}],
+ params: [
+ {name: 'input', type: 'string', description: 'The input.', required: true},
+ ],
returns: [{name: 'value', type: 'string', description: 'The result.'}],
};
@@ -43,7 +55,11 @@ const goodGeneric = {
type: 'generic',
name: 'Theming',
displayName: 'Theming',
+ title: 'Theming',
description: 'How theming works.',
+ sections: [
+ {title: 'Overview', content: [{type: 'prose', text: 'Use a theme.'}]},
+ ],
};
/** Run parseDoc and return the thrown message (asserting it throws). */
@@ -101,6 +117,34 @@ describe('per-kind parsers (stamped format)', () => {
expect(() => parseReference(goodGeneric)).not.toThrow();
});
+ it('normalizes a migrated minimal generic doc to the public shape', () => {
+ expect(
+ parseReference({
+ type: 'generic',
+ name: 'Theming',
+ description: 'How theming works.',
+ }),
+ ).toMatchObject({
+ type: 'generic',
+ name: 'Theming',
+ title: 'Theming',
+ description: 'How theming works.',
+ sections: [],
+ });
+ });
+
+ it('rejects duplicate stable section IDs', () => {
+ expect(() =>
+ parseReference({
+ ...goodGeneric,
+ sections: [
+ {id: 'start', title: 'Start', content: []},
+ {id: 'start', title: 'Renamed start', content: []},
+ ],
+ }),
+ ).toThrow(/sections\.1\.id.*duplicate section id/u);
+ });
+
it('keeps nested rich blobs loose (usage/theming/playground passthrough)', () => {
expect(() =>
parseComponent({
@@ -123,6 +167,16 @@ describe('per-kind parsers (stamped format)', () => {
expect(parsed.parent).toBe('WidgetGroup');
expect(parsed.relatedDocs).toEqual(['Gauge', 'useThing']);
});
+
+ it('validates graph metadata on unstamped legacy docs', () => {
+ expect(() =>
+ parseDoc({name: 'Widget', props: [], placement: {parent: ''}}),
+ ).toThrow(/placement\.parent/u);
+ expect(() => parseDoc({name: 'Widget', props: [], aliases: [1]})).toThrow();
+ expect(() =>
+ parseDoc({name: 'Widget', props: [], audience: 'secret'}),
+ ).toThrow();
+ });
});
describe('parseDoc (load boundary, both formats)', () => {
@@ -175,6 +229,24 @@ describe('parseDoc (load boundary, both formats)', () => {
expect(() => parseDoc(hook)).not.toThrow();
});
+ it('accepts and validates the OLD loose reference-topic shape', () => {
+ const reference = {
+ name: 'theming',
+ title: 'Theming',
+ description: 'How theming works.',
+ sections: [
+ {id: 'start', title: 'Start', content: [{type: 'prose', text: 'Go.'}]},
+ ],
+ };
+ expect(parseDoc(reference)).toEqual(reference);
+ expect(() =>
+ parseDoc({
+ ...reference,
+ sections: [{title: 'Start', content: [{type: 'prose'}]}],
+ }),
+ ).toThrow();
+ });
+
it('accepts BOTH parent and legacy subComponentOf', () => {
const withParent = {name: 'A', parent: 'B', props: []};
const withSubComponentOf = {
@@ -289,7 +361,9 @@ describe('loadComponentDoc (end-to-end load boundary)', () => {
" type: 'generic',",
" name: 'Theming',",
" displayName: 'Theming',",
+ " title: 'Theming',",
" description: 'How theming works.',",
+ " sections: [{title: 'Overview', content: [{type: 'prose', text: 'Use a theme.'}]}],",
'};',
].join('\n'),
);
diff --git a/packages/cli/authoring/doctypes/reference/parse.mjs b/packages/cli/authoring/doctypes/reference/parse.mjs
index 64771adcc5..32f8d61e17 100644
--- a/packages/cli/authoring/doctypes/reference/parse.mjs
+++ b/packages/cli/authoring/doctypes/reference/parse.mjs
@@ -23,8 +23,11 @@ export function parseReference(input, label = 'reference doc') {
if (!result.success) {
throw new Error(formatZodError(label, result.error));
}
- // The schema is permissive (it also accepts legacy generic docs), so it is
- // deliberately looser than the rich public type; cast through unknown at this
- // validated boundary.
- return /** @type {ReferenceDoc} */ (/** @type {unknown} */ (result.data));
+ const doc = result.data;
+ return /** @type {ReferenceDoc} */ ({
+ ...doc,
+ title: doc.title ?? doc.displayName ?? doc.name,
+ description: doc.description ?? '',
+ sections: doc.sections ?? [],
+ });
}
diff --git a/packages/cli/authoring/doctypes/reference/reference.doc.mjs b/packages/cli/authoring/doctypes/reference/reference.doc.mjs
index cfdd3a377d..9ae1022ddd 100644
--- a/packages/cli/authoring/doctypes/reference/reference.doc.mjs
+++ b/packages/cli/authoring/doctypes/reference/reference.doc.mjs
@@ -55,7 +55,7 @@ export const doc = {
name: 'replaces',
type: 'string',
description:
- "Name of an existing topic this doc takes the place of. Authored by an integration that serves its own guide instead of the built-in one: on a doc of the same name it swaps the content, and on a doc of another name it also leaves the old name as an alias so `astryx docs <old>` still resolves. Exclusive with `extends`.",
+ 'Name of an existing topic this doc takes the place of. Authored by an integration that serves its own guide instead of the built-in one: on a doc of the same name it swaps the content, and on a doc of another name it also leaves the old name as an alias so `astryx docs <old>` still resolves. Exclusive with `extends`.',
example: "'getting-started'",
},
{
@@ -72,6 +72,12 @@ export const doc = {
'Ordered sections that make up the doc. Each becomes an h2 in full output and can be retrieved via `astryx docs <topic> <section>`.',
required: true,
fields: [
+ {
+ name: 'sections[].id',
+ type: 'string',
+ description:
+ 'Stable section anchor. New docs should set this instead of relying on a mutable title.',
+ },
{
name: 'sections[].title',
type: 'string',
@@ -89,7 +95,7 @@ export const doc = {
name: 'sections[].content',
type: 'ReferenceContentBlock[]',
description:
- 'Ordered content blocks. Mix prose, code, tables, and lists freely.',
+ 'Ordered content blocks. Existing prose, heading, code, table, list, and token-ref blocks remain; V1 adds workflow, collection, and reference.',
required: true,
},
{
@@ -134,7 +140,7 @@ export const docs = {
notes: [
{
type: 'prose',
- text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+ text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. V1 adds only workflow, collection, and reference; choice, callout, and checklist remain invalid. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
},
{
type: 'code',
@@ -146,7 +152,10 @@ export const docs = {
| { type: 'code'; lang: string; code: string; label?: string }
| { type: 'table'; headers: string[]; rows: string[][] }
| { type: 'list'; style: 'ordered' | 'unordered' | 'do' | 'dont'; items: string[] }
- | { type: 'token-ref'; topic: string; section: string };`,
+ | { type: 'token-ref'; topic: string; section: string }
+ | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
+ | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
+ | { type: 'reference'; target: string; projection?: {fields?: string[]; sections?: string[]} };`,
},
{
type: 'prose',
diff --git a/packages/cli/authoring/doctypes/reference/type.ts b/packages/cli/authoring/doctypes/reference/type.ts
index 400421ba5e..f2454b18c7 100644
--- a/packages/cli/authoring/doctypes/reference/type.ts
+++ b/packages/cli/authoring/doctypes/reference/type.ts
@@ -4,10 +4,48 @@
* @file Reference/topic doc types.
*/
+import type {AuthoredDocGraphFields} from '../base/type';
+
+/** One step in a renderer-neutral workflow. */
+export interface WorkflowStep {
+ title: string;
+ description?: string;
+ /** Stable doc references that supply detail for this step. */
+ references?: string[];
+}
+
+/** Ordered procedural guidance. */
+export interface WorkflowDocBlock {
+ type: 'workflow';
+ title?: string;
+ steps: WorkflowStep[];
+}
+
+/** A generated view over docs placed in one namespace slot. */
+export interface CollectionDocBlock {
+ type: 'collection';
+ title?: string;
+ source: {slot: string};
+ presentation?: 'list' | 'cards' | 'compact';
+ whenEmpty?: 'show' | 'omit';
+}
+
+/** A bounded projection of one canonical doc. */
+export interface ReferenceDocBlock {
+ type: 'reference';
+ target: string;
+ projection?: {
+ fields?: string[];
+ sections?: string[];
+ };
+ presentation?: 'summary' | 'compact' | 'full';
+}
+
/**
- * A content block within a reference doc section.
- * Ordered array of these makes up a section's content.
- * New block types can be added without breaking existing docs.
+ * A content block within a reference doc section or namespace.
+ * Ordered arrays of these blocks form renderer-neutral documentation content.
+ * A new semantic kind must ship with every renderer or fail visibly at a legacy
+ * reader boundary until that renderer is available.
*
* @example
* ```
@@ -17,6 +55,9 @@
* { type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']] }
* { type: 'list', style: 'do', items: ['Use semantic tokens'] }
* { type: 'token-ref', topic: 'tokens', section: 'Color Tokens' }
+ * { type: 'workflow', steps: [{title: 'Validate', references: ['command:doctor']}] }
+ * { type: 'collection', source: {slot: 'guides'}, presentation: 'cards' }
+ * { type: 'reference', target: 'schema:integration', projection: {fields: ['docs']} }
* ```
*/
export type ReferenceContentBlock =
@@ -39,7 +80,10 @@ export type ReferenceContentBlock =
topic: string;
/** Section title to pull from that topic. e.g. `'Color Tokens'` */
section: string;
- };
+ }
+ | WorkflowDocBlock
+ | CollectionDocBlock
+ | ReferenceDocBlock;
/**
* A reference documentation file (.doc.mjs).
@@ -54,7 +98,7 @@ export type ReferenceContentBlock =
* /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} *\/
* export const docs = { ... };
*/
-export interface ReferenceDoc {
+export interface ReferenceDoc extends AuthoredDocGraphFields {
/** Doc-kind discriminant for the stamped default-export format
* (`export default { type: 'generic', ... }`). Optional: legacy
* `export const docs = {...}` docs omit it. The value stays `'generic'`
@@ -95,6 +139,8 @@ export interface ReferenceDoc {
* and can be individually retrieved via `astryx docs <topic> <section>`.
*/
export interface ReferenceSection {
+ /** Stable section anchor. New docs should set this instead of relying on title. */
+ id?: string;
/** Section title, e.g. "Spacing Tokens", "Light/Dark Mode" */
title: string;
/** Navigation category ('guide' | 'foundations'). Mirrors the parent doc's
diff --git a/packages/cli/authoring/doctypes/schema/type.ts b/packages/cli/authoring/doctypes/schema/type.ts
index 0d0b0eb1f3..d89ec32ad1 100644
--- a/packages/cli/authoring/doctypes/schema/type.ts
+++ b/packages/cli/authoring/doctypes/schema/type.ts
@@ -6,6 +6,7 @@
* response envelope). Colocated as a `.doc.mjs` next to the schema it describes.
*/
+import type {AuthoredDocGraphFields} from '../base/type';
import type {ReferenceContentBlock} from '../reference/type';
/**
@@ -37,7 +38,7 @@ export interface SchemaFieldDoc {
* /\*\* @type {import('@astryxdesign/cli/authoring').SchemaDoc} \*\/
* export const doc = { type: 'schema', name: 'config', ... };
*/
-export interface SchemaDoc {
+export interface SchemaDoc extends AuthoredDocGraphFields {
/** Doc-kind discriminant. */
type?: 'schema';
/** URL-safe identifier, used as the docs slug within its namespace. */
diff --git a/packages/cli/authoring/doctypes/template/parse.mjs b/packages/cli/authoring/doctypes/template/parse.mjs
index 64d3a34ab6..029943e615 100644
--- a/packages/cli/authoring/doctypes/template/parse.mjs
+++ b/packages/cli/authoring/doctypes/template/parse.mjs
@@ -9,6 +9,7 @@
*/
import {z} from 'zod';
+import {AuthoredDocGraphFields} from '../_schema.mjs';
import {formatZodError} from '../../_shared/errors.mjs';
/** @typedef {import('../types').TemplateDoc} TemplateDoc */
@@ -37,9 +38,10 @@ const registryIdentitySchema = z
.strict();
const baseTemplateFields = {
+ ...AuthoredDocGraphFields,
name: z.string().min(1, 'name is required'),
displayName: z.string().min(1).optional(),
- description: z.string().min(1, 'description is required'),
+ description: z.string().min(1, 'description is required').optional(),
category: z.string().optional(),
componentsUsed: z.array(z.string()).optional(),
preview: previewSchema.optional(),
diff --git a/packages/cli/authoring/doctypes/template/parse.test.mjs b/packages/cli/authoring/doctypes/template/parse.test.mjs
index fdbf53a0d3..9ed67ca710 100644
--- a/packages/cli/authoring/doctypes/template/parse.test.mjs
+++ b/packages/cli/authoring/doctypes/template/parse.test.mjs
@@ -112,8 +112,14 @@ describe('parseTemplate (load boundary)', () => {
expect(reason({type: 'page', description: 'x'})).toContain('name');
});
- it('rejects a missing description', () => {
- expect(reason({type: 'page', name: 'x'})).toContain('description');
+ it('accepts an omitted description and rejects an empty one when present', () => {
+ expect(parseTemplate({type: 'page', name: 'x'})).toEqual({
+ type: 'page',
+ name: 'x',
+ });
+ expect(reason({type: 'page', name: 'x', description: ''})).toContain(
+ 'description',
+ );
});
it('rejects an empty-string name', () => {
diff --git a/packages/cli/authoring/doctypes/template/type.ts b/packages/cli/authoring/doctypes/template/type.ts
index 59082b1610..350855d0c7 100644
--- a/packages/cli/authoring/doctypes/template/type.ts
+++ b/packages/cli/authoring/doctypes/template/type.ts
@@ -4,9 +4,9 @@
* @file Template doc types.
*/
-import type {RegistryDocIdentity} from '../base/type';
+import type {AuthoredDocGraphFields, RegistryDocIdentity} from '../base/type';
-export interface BaseTemplateDoc {
+export interface BaseTemplateDoc extends AuthoredDocGraphFields {
/** Identifier name for the template. For block templates this matches
* the React component import name (e.g. `"ChatMessageMetadata"`); for
* page templates it's a human-readable label that doubles as the
diff --git a/packages/cli/authoring/doctypes/types.ts b/packages/cli/authoring/doctypes/types.ts
index 29fa9b0c5f..915dd82d3d 100644
--- a/packages/cli/authoring/doctypes/types.ts
+++ b/packages/cli/authoring/doctypes/types.ts
@@ -12,6 +12,7 @@ export type * from './component/type';
export type * from './hook/type';
export type * from './function/type';
export type * from './reference/type';
+export type * from './namespace/type';
export type * from './template/type';
export type * from './schema/type';
export type * from './command/type';
diff --git a/packages/cli/authoring/identity/identity.doc.mjs b/packages/cli/authoring/identity/identity.doc.mjs
new file mode 100644
index 0000000000..91867f859d
--- /dev/null
+++ b/packages/cli/authoring/identity/identity.doc.mjs
@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for provider, artifact, and immutable instance identity.
+ * @position packages/cli/authoring/identity — identity documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+ type: 'schema',
+ name: 'provider-identity',
+ displayName: 'Provider and artifact identity',
+ namespace: 'authoring',
+ description:
+ 'Separates stable provider/artifact identity from package instances and runtime lifecycle state.',
+ appliesTo: 'Compiler inputs, manifests, search, Build, and Doctor',
+ fields: [
+ {
+ name: 'ProviderId',
+ type: 'string',
+ description:
+ 'Canonical logical provider ID. It defaults to the lowercase npm package name; Core uses the same model without publishing an integration manifest.',
+ required: true,
+ },
+ {
+ name: 'ArtifactId',
+ type: 'string',
+ description:
+ 'Versioned serialization of provider ID, contribution kind, and stable artifact name. Every segment uses RFC 3986 escaping.',
+ required: true,
+ },
+ {
+ name: 'DocId',
+ type: 'ArtifactId',
+ description:
+ 'Artifact ID restricted to one authored doc kind. Navigation changes do not change it.',
+ required: true,
+ },
+ {
+ name: 'ProviderInstance',
+ type: '{ id; providerId; packageName; packageVersion; sourceDigest }',
+ description:
+ 'One immutable package version and source/content digest. Installed, configured, loaded, selected, and healthy state is a separate runtime overlay.',
+ required: true,
+ },
+ {
+ name: 'AuthoredDocEntry',
+ type: '{ id; provider; kind; stableName; source; authored }',
+ description:
+ 'Normalized compiler input. Discovery supplies stableName independently from the authored display name, source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
+ required: true,
+ },
+ ],
+ notes: [
+ {
+ type: 'prose',
+ text: 'Provider package renames require an explicit mapping: a ProviderInstance may retain its stable providerId while packageName changes. Silent identity changes are not inferred.',
+ },
+ ],
+};
diff --git a/packages/cli/authoring/identity/type.ts b/packages/cli/authoring/identity/type.ts
new file mode 100644
index 0000000000..05331af0dc
--- /dev/null
+++ b/packages/cli/authoring/identity/type.ts
@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stable provider, artifact, and authored-doc entry contracts.
+ *
+ * Logical IDs exclude installed/configured/loaded/healthy state. A concrete
+ * provider instance adds package version and a content digest, while an
+ * artifact ID stays stable across those instances.
+ */
+
+import type {AuthoredDocKind} from '../doctypes/base/type';
+import type {CommandDoc} from '../doctypes/command/type';
+import type {ComponentDoc} from '../doctypes/component/type';
+import type {EnumDoc} from '../doctypes/enum/type';
+import type {FunctionDoc} from '../doctypes/function/type';
+import type {HookDoc} from '../doctypes/hook/type';
+import type {NamespaceDoc} from '../doctypes/namespace/type';
+import type {ReferenceDoc} from '../doctypes/reference/type';
+import type {SchemaDoc} from '../doctypes/schema/type';
+import type {TemplateDoc} from '../doctypes/template/type';
+
+declare const providerIdBrand: unique symbol;
+declare const artifactIdBrand: unique symbol;
+declare const docIdBrand: unique symbol;
+declare const providerInstanceIdBrand: unique symbol;
+declare const contentDigestBrand: unique symbol;
+
+/** Canonical provider identity. It defaults to the normalized npm package name. */
+export type ProviderId = string & {readonly [providerIdBrand]: true};
+
+/** Stable provider + contribution kind + artifact-name identity. */
+export type ArtifactId = string & {readonly [artifactIdBrand]: true};
+
+/** ArtifactId narrowed to an authored documentation kind. */
+export type DocId = ArtifactId & {readonly [docIdBrand]: true};
+
+/** Immutable provider version + source/content digest identity. */
+export type ProviderInstanceId = string & {
+ readonly [providerInstanceIdBrand]: true;
+};
+
+/** Lowercase `sha256:<64 hex characters>` digest. */
+export type ContentDigest = string & {readonly [contentDigestBrand]: true};
+
+/** Every stable artifact kind owned by a provider. */
+export type ContributionKind =
+ AuthoredDocKind | 'theme' | 'codemod' | 'agent-doc';
+
+/** Stable logical identity for one provider-owned artifact. */
+export interface ArtifactIdentity {
+ readonly id: ArtifactId;
+ readonly providerId: ProviderId;
+ readonly kind: ContributionKind;
+ readonly name: string;
+}
+
+/** One immutable package instance. Runtime lifecycle state does not belong here. */
+export interface ProviderInstance {
+ readonly id: ProviderInstanceId;
+ readonly providerId: ProviderId;
+ readonly packageName: string;
+ readonly packageVersion: string;
+ readonly sourceDigest: ContentDigest;
+}
+
+/** Every authored value accepted by the documentation compiler boundary. */
+export type AuthoredDoc =
+ | ComponentDoc
+ | HookDoc
+ | FunctionDoc
+ | ReferenceDoc
+ | TemplateDoc
+ | SchemaDoc
+ | CommandDoc
+ | EnumDoc
+ | NamespaceDoc;
+
+/** Provenance attached by discovery before compilation. */
+export interface AuthoredDocSource {
+ /** Provider-local logical discovery group. */
+ readonly group: string;
+ /** Package-relative source path; excluded from compiled renderer data. */
+ readonly path: string;
+ /** Digest of the authored source bytes. */
+ readonly digest: ContentDigest;
+}
+
+/** Authored kind that corresponds to one public document type. */
+export type AuthoredDocKindOf<TDoc extends AuthoredDoc> =
+ TDoc extends ComponentDoc
+ ? 'component'
+ : TDoc extends HookDoc | FunctionDoc
+ ? 'function'
+ : TDoc extends ReferenceDoc
+ ? 'generic'
+ : TDoc extends TemplateDoc
+ ? TDoc['type']
+ : TDoc extends SchemaDoc
+ ? 'schema'
+ : TDoc extends CommandDoc
+ ? 'command'
+ : TDoc extends EnumDoc
+ ? 'enum'
+ : TDoc extends NamespaceDoc
+ ? 'namespace'
+ : never;
+
+type DeepReadonly<Value> = Value extends (...args: never[]) => unknown
+ ? Value
+ : Value extends readonly (infer Item)[]
+ ? readonly DeepReadonly<Item>[]
+ : Value extends object
+ ? {readonly [Key in keyof Value]: DeepReadonly<Value[Key]>}
+ : Value;
+
+/** Immutable authored-data snapshot stored in a compiler entry. */
+export type AuthoredDocSnapshot<TDoc extends AuthoredDoc = AuthoredDoc> =
+ DeepReadonly<TDoc>;
+
+/**
+ * One normalized compiler input. Stable identity is provider + authored kind +
+ * stable name; provider version and source bytes remain explicit provenance.
+ */
+export interface AuthoredDocEntry<TDoc extends AuthoredDoc = AuthoredDoc> {
+ readonly id: DocId;
+ readonly provider: ProviderInstance;
+ readonly kind: AuthoredDocKindOf<TDoc>;
+ /** Stable provider-local key used in the DocId; it need not equal a display name. */
+ readonly stableName: string;
+ readonly source: AuthoredDocSource;
+ readonly authored: AuthoredDocSnapshot<TDoc>;
+}
diff --git a/packages/cli/authoring/index.d.ts b/packages/cli/authoring/index.d.ts
index 23de59b6f0..92d4b34d87 100644
--- a/packages/cli/authoring/index.d.ts
+++ b/packages/cli/authoring/index.d.ts
@@ -31,6 +31,7 @@ export type {TemplateDoc} from './doctypes/types'; // Foo.template.{ts,mjs}
export type {SchemaDoc} from './doctypes/types'; // config.doc.mjs (object shape)
export type {CommandDoc} from './doctypes/types'; // search.doc.mjs (CLI command)
export type {EnumDoc} from './doctypes/types'; // error-codes.doc.mjs (vocabulary)
+export type {NamespaceDoc} from './doctypes/types'; // cli.doc.mjs (hierarchy)
export type {AstryxConfig} from './config/type'; // astryx.config.{ts,mjs}
export type {DebugEvent} from './debug/type'; // one recorded CLI run
export type {AstryxIntegration} from './integration/type'; // astryx.integration.{ts,mjs}
@@ -56,6 +57,7 @@ export {parseTemplate} from './doctypes/template/parse.mjs';
export {parseSchema} from './doctypes/schema/parse.mjs';
export {parseCommand} from './doctypes/command/parse.mjs';
export {parseEnum} from './doctypes/enum/parse.mjs';
+export {parseNamespace} from './doctypes/namespace/parse.mjs';
export {parseLegacyDoc} from './doctypes/legacy.mjs';
export {parseConfig} from './config/parse.mjs';
export {parseIntegration} from './integration/parse.mjs';
@@ -72,6 +74,26 @@ export {parseDebugEvent} from './debug/parse.mjs';
// need them to author. Names carry the doc kind they belong to.
// ═══════════════════════════════════════════════════════════════════════
export type {
+ ProviderId,
+ ArtifactId,
+ DocId,
+ ProviderInstanceId,
+ ContentDigest,
+ ContributionKind,
+ ArtifactIdentity,
+ ProviderInstance,
+ AuthoredDoc,
+ AuthoredDocKindOf,
+ AuthoredDocSnapshot,
+ AuthoredDocSource,
+ AuthoredDocEntry,
+} from './identity/type';
+export type {
+ // shared graph
+ AuthoredDocKind,
+ DocAudience,
+ DocPlacement,
+ AuthoredDocGraphFields,
// component
SingleComponentDoc,
MultiComponentDoc,
@@ -109,6 +131,16 @@ export type {
ReferenceContentBlock,
ReferenceTokenPreviewType,
ReferenceTranslationDoc,
+ WorkflowStep,
+ WorkflowDocBlock,
+ CollectionDocBlock,
+ ReferenceDocBlock,
+ // namespace
+ NamespaceProviderScope,
+ NamespaceSlotAcceptance,
+ NamespaceSlot,
+ NamespaceAdoptionSource,
+ NamespaceAdoptionRule,
// template
TemplateCategory,
// schema
diff --git a/packages/cli/authoring/index.mjs b/packages/cli/authoring/index.mjs
index 2471979145..d3207309fd 100644
--- a/packages/cli/authoring/index.mjs
+++ b/packages/cli/authoring/index.mjs
@@ -31,4 +31,5 @@ export {parseTemplate} from './doctypes/template/parse.mjs';
export {parseSchema} from './doctypes/schema/parse.mjs';
export {parseCommand} from './doctypes/command/parse.mjs';
export {parseEnum} from './doctypes/enum/parse.mjs';
+export {parseNamespace} from './doctypes/namespace/parse.mjs';
export {parseLegacyDoc} from './doctypes/legacy.mjs';
diff --git a/packages/cli/authoring/integration/integration.doc.mjs b/packages/cli/authoring/integration/integration.doc.mjs
index 81f4a76274..85997cc2e3 100644
--- a/packages/cli/authoring/integration/integration.doc.mjs
+++ b/packages/cli/authoring/integration/integration.doc.mjs
@@ -14,11 +14,18 @@ export const doc = {
namespace: 'cli',
description:
'The astryx.integration.* manifest that sits beside an integration ' +
- "package's package.json. Points the CLI at the package's components, " +
- 'templates, codemods, doc topics, source themes, and managed agent guidance, ' +
- 'and where to file issues. Every field is optional.',
+ "package's package.json. It can preserve a stable provider identity across a package rename, " +
+ "and points the CLI at the package's components, templates, codemods, doc topics, " +
+ 'source themes, managed agent guidance, and issue tracker. Every field is optional.',
appliesTo: 'astryx.integration.{ts,mjs,js}',
fields: [
+ {
+ name: 'providerId',
+ type: 'string',
+ description:
+ 'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
+ example: "'@acme/widgets'",
+ },
{
name: 'components',
type: 'string',
@@ -87,9 +94,9 @@ export const doc = {
{
type: 'prose',
text:
- "Identity, the integration's name and version, comes from the " +
- "package's package.json, not from this manifest. The manifest only " +
- 'declares where the CLI finds each kind of artifact.',
+ 'Provider identity defaults to package.json#name. During an explicit ' +
+ 'package rename, set `providerId` to the prior canonical package name so ' +
+ 'existing artifact IDs remain stable. Package version always comes from package.json.',
},
{
type: 'prose',
diff --git a/packages/cli/authoring/integration/parse.test.mjs b/packages/cli/authoring/integration/parse.test.mjs
index fdb03e0771..e3406d7c15 100644
--- a/packages/cli/authoring/integration/parse.test.mjs
+++ b/packages/cli/authoring/integration/parse.test.mjs
@@ -28,6 +28,9 @@ describe('parseIntegration (load boundary)', () => {
components: './src',
});
expect(parseIntegration({docs: './docs'})).toEqual({docs: './docs'});
+ expect(parseIntegration({providerId: '@acme/legacy-widgets'})).toEqual({
+ providerId: '@acme/legacy-widgets',
+ });
expect(parseIntegration({themes: './themes'})).toEqual({
themes: './themes',
});
@@ -66,7 +69,9 @@ describe('parseIntegration (load boundary)', () => {
? 'https://example.com/issues'
: key === 'agentDocs'
? {}
- : './x',
+ : key === 'providerId'
+ ? '@acme/widgets'
+ : './x',
]),
);
expect(unknownIntegrationKeys(everyKnownKey)).toEqual([]);
@@ -82,6 +87,10 @@ describe('parseIntegration (load boundary)', () => {
expect(reason({issuesUrl: 'nope'})).toContain('issuesUrl');
});
+ it('rejects a noncanonical providerId', () => {
+ expect(reason({providerId: 'Acme Widgets'})).toContain('providerId');
+ });
+
it('accepts an optional append array as manifest data', () => {
expect(
parseIntegration({
diff --git a/packages/cli/authoring/integration/schema.mjs b/packages/cli/authoring/integration/schema.mjs
index f035211b98..f00728a2df 100644
--- a/packages/cli/authoring/integration/schema.mjs
+++ b/packages/cli/authoring/integration/schema.mjs
@@ -21,6 +21,8 @@ import {formatZodError} from '../_shared/errors.mjs';
const MAX_AGENT_DOC_LINES = 8;
const MAX_AGENT_DOC_LINE_CODE_POINTS = 240;
const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;
+const PROVIDER_ID_RE =
+ /^(?:@[a-z0-9][a-z0-9._~!*'()-]*\/)?[a-z0-9][a-z0-9._~!*'()-]*$/u;
/**
* @param {string} value
@@ -66,6 +68,10 @@ export const agentDocsSchema = z.object({
});
export const integrationBaseSchema = z.object({
+ providerId: z
+ .string()
+ .regex(PROVIDER_ID_RE, 'providerId must be a canonical npm package name')
+ .optional(),
components: z.string().optional(),
templates: z.string().optional(),
codemods: z.string().optional(),
diff --git a/packages/cli/authoring/integration/type.ts b/packages/cli/authoring/integration/type.ts
index 35d724a64f..a3b1a70394 100644
--- a/packages/cli/authoring/integration/type.ts
+++ b/packages/cli/authoring/integration/type.ts
@@ -3,9 +3,10 @@
/**
* Public type surface for an Astryx integration manifest
* (`astryx.integration.{ts,mjs,js}`, sibling to the integration package's
- * package.json). Identity (name/version) comes from package.json, not the
- * manifest. Authors write a plain object against {@link AstryxIntegration};
- * the CLI validates it via `parseIntegration` at the load boundary.
+ * package.json). Identity defaults to the package name, but `providerId` can keep
+ * a stable logical identity across an explicit package rename. Authors write a
+ * plain object against {@link AstryxIntegration}; the CLI validates it via
+ * `parseIntegration` at the load boundary.
*
* The manifest module may also carry `debug` and `gapReport` NAMED exports.
* They are not fields here on purpose: a CLI released before a given manifest
@@ -13,6 +14,9 @@
* named export is simply not read. See the `cli-integrations` doc topic.
*/
export interface AstryxIntegration {
+ /** Stable logical provider ID. Omit to use package.json#name. Set this only
+ * when a package rename must preserve existing artifact IDs. */
+ providerId?: string;
/** Relative path to the components/docs root (resolved to absolute). */
components?: string;
/** Relative path to the templates root (resolved to absolute). */
diff --git a/packages/cli/clients/cli/commands/docs.doc.mjs b/packages/cli/clients/cli/commands/docs.doc.mjs
index 380de719c9..0be2c9097f 100644
--- a/packages/cli/clients/cli/commands/docs.doc.mjs
+++ b/packages/cli/clients/cli/commands/docs.doc.mjs
@@ -16,22 +16,32 @@ export const doc = {
summary: 'Print reference docs',
description:
'Reads the reference docs: with no topic it lists every topic; a topic prints that ' +
- 'full doc; a topic plus a section returns the first section whose title contains the ' +
- '(case-insensitive) query.',
+ 'full doc; `--index` lists its sections instead, each with the key to read it by; a ' +
+ 'topic plus a section prints that section (by key, exact title, or a unique part of ' +
+ 'a title).',
fn: 'docs',
args: [
{name: 'topic', param: 'topic', required: false},
{name: 'section', param: 'section', required: false},
],
+ options: [
+ {
+ flag: '--index',
+ param: 'options.index',
+ description: "List the topic's sections and their keys instead of printing the whole topic",
+ },
+ ],
examples: [
{label: 'List topics', cli: 'astryx docs'},
{label: 'One topic as JSON', cli: 'astryx docs spacing --json'},
+ {label: "A topic's sections", cli: 'astryx docs theme --index'},
+ {label: 'One section', cli: 'astryx docs theme quick-start'},
],
exitCodes: [
{code: 0, when: 'success'},
{
code: 1,
- when: 'unknown topic, or a section that matches no title in the topic',
+ when: 'unknown topic, or a section that matches no section or more than one',
},
],
related: ['search', 'component', 'hook', 'template'],
diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjs
index 3cfdc4c23c..4ee36f0095 100644
--- a/packages/cli/clients/cli/commands/docs.mjs
+++ b/packages/cli/clients/cli/commands/docs.mjs
@@ -3,18 +3,29 @@
/**
* @file docs command — Print Astryx reference docs
*
- * Auto-discovers .doc.mjs files from the docs/ directory.
+ * A topic prints its whole doc; `--index` lists its sections instead, so a
+ * reader can open one section by its key.
* Supports --detail (full|compact|brief) and --lang (en|zh|dense).
*
* Usage:
* astryx docs List available topics
- * astryx docs <topic> Print full doc
+ * astryx docs <topic> Print the whole topic
+ * astryx docs <topic> --index List the topic's sections
* astryx docs <topic> <section> Print one section
*/
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, records, text, code} from '../formatters/index.mjs';
+import {
+ emit,
+ section,
+ records,
+ text,
+ code,
+ wrapText,
+ displayWidth,
+ WRAP_WIDTH,
+} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {resultSet} from '../../../foundation/debug/index.mjs';
@@ -41,6 +52,28 @@ function formatTable(headers, rows) {
return `${head}\n${sep}\n${body}`;
}
+/**
+ * A table too wide for {@link WRAP_WIDTH}: one `header: cell` line per cell and
+ * a blank line between rows, so nothing runs off the side of a terminal.
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ * @returns {string}
+ */
+function formatTableVertical(headers, rows) {
+ const width = Math.max(...headers.map(h => h.length)) + 2;
+ return rows
+ .map(row =>
+ headers
+ .map((h, i) =>
+ wrapText(`${`${h}:`.padEnd(width)}${row[i] ?? ''}`, {
+ indent: ' '.repeat(width),
+ }),
+ )
+ .join('\n'),
+ )
+ .join('\n\n');
+}
+
/**
* @param {string[]} headers
* @param {string[][]} rows
@@ -58,7 +91,7 @@ function formatTableCompact(headers, rows) {
function formatBlock(block, detail) {
switch (block.type) {
case 'prose':
- return block.text;
+ return wrapText(block.text);
case 'heading':
return `${'#'.repeat(block.level || 3)} ${block.text}`;
@@ -77,16 +110,37 @@ function formatBlock(block, detail) {
if (detail === 'compact') {
return formatTableCompact(block.headers, block.rows);
}
- return formatTable(block.headers, block.rows);
+ {
+ const table = formatTable(block.headers, block.rows);
+ return table.split('\n').some(line => displayWidth(line) > WRAP_WIDTH)
+ ? formatTableVertical(block.headers, block.rows)
+ : table;
+ }
case 'list': {
- const prefix = block.style === 'ordered' ? (/** @type {number} */ i) => `${i + 1}. `
- : block.style === 'dont' ? () => 'x '
- : block.style === 'do' ? () => '+ '
- : () => '- ';
- return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
+ const prefix =
+ block.style === 'ordered'
+ ? (/** @type {number} */ i) => `${i + 1}. `
+ : block.style === 'dont'
+ ? () => 'x '
+ : block.style === 'do'
+ ? () => '+ '
+ : () => '- ';
+ return block.items
+ .map((item, i) => {
+ const head = prefix(i);
+ return wrapText(`${head}${item}`, {indent: ' '.repeat(head.length)});
+ })
+ .join('\n');
}
+ case 'workflow':
+ case 'collection':
+ case 'reference':
+ throw new Error(
+ `Documentation block "${block.type}" requires the compiled graph renderer.`,
+ );
+
default:
return null;
}
@@ -107,7 +161,8 @@ function formatSection(section, detail) {
return `${section.title}: ${first.split('\n')[0]}`;
}
- const heading = detail === 'compact' ? `[${section.title}]` : `## ${section.title}`;
+ const heading =
+ detail === 'compact' ? `[${section.title}]` : `## ${section.title}`;
return `${heading}\n\n${blocks.join('\n\n')}`;
}
@@ -118,25 +173,51 @@ function formatSection(section, detail) {
*/
function formatReferenceFull(docs, detail) {
if (detail === 'brief') {
- const header = `${docs.title}: ${docs.description}`;
+ const header = wrapText(`${docs.title}: ${docs.description}`);
const sections = docs.sections.map(s => formatSection(s, detail));
return `${header}\n${sections.join('\n')}`;
}
- const header = detail === 'compact'
- ? `# ${docs.title}\n${docs.description}`
- : `# ${docs.title}\n\n${docs.description}`;
+ const description = wrapText(docs.description);
+ const header =
+ detail === 'compact'
+ ? `# ${docs.title}\n${description}`
+ : `# ${docs.title}\n\n${description}`;
const sections = docs.sections.map(s => formatSection(s, detail));
const sep = detail === 'compact' ? '\n\n' : '\n\n';
return `${header}\n\n${sections.join(sep)}`;
}
+/**
+ * A topic's section index: what the topic is, one line per section with the
+ * key to read it by, and how to read further.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsIndex} index
+ * @param {string} run
+ */
+function emitIndex(index, run) {
+ emit(
+ section(index.title, index.description ? wrapText(index.description) : undefined),
+ records(index.sections, {
+ fields: ['id', 'title', 'summary'],
+ layout: 'inline',
+ overflow: 'truncate',
+ }),
+ text(
+ [
+ `Read one section: ${run} docs ${index.name} <section>`,
+ `Read everything: ${run} docs ${index.name}`,
+ ].join('\n'),
+ ),
+ );
+}
+
/**
* What the run answered with. A named topic (or one of its sections) resolves
* or throws, so it is always a direct match of one doc; the bare form lists
* every topic there is.
*
* @param {import('../../../api/docs/docs.type.mjs').DocsListResponse
+ * | import('../../../api/docs/docs.type.mjs').DocsIndexResponse
* | import('../../../api/docs/docs.type.mjs').DocsDetailResponse
* | import('../../../api/docs/docs.type.mjs').DocsDetailSectionResponse} result
* @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
@@ -155,7 +236,11 @@ function summarize(result) {
export function registerDocs(program) {
defineCommand(program, docsCommand, {
fn: docsFn,
- action: async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ sectionName) => {
+ action: async (
+ /** @type {string | undefined} */ topic,
+ /** @type {string | undefined} */ sectionName,
+ /** @type {{index?: boolean}} */ options = {},
+ ) => {
const run = getCliInvocation();
const lang = program.opts().lang || null;
const zh = program.opts().zh || false;
@@ -165,11 +250,17 @@ export function registerDocs(program) {
let result;
try {
- result = await docsApi(topic, sectionName, {lang, zh, dense});
+ result = await docsApi(topic, sectionName, {
+ lang,
+ zh,
+ dense,
+ index: Boolean(options.index),
+ });
} catch (e) {
// docs API throws structured errors with {name, reason} suggestions —
// pass them through untouched so the CLI envelope matches the API.
- const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+ const err =
+ /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
return cliError(err.message, {
suggestions: err.suggestions || [],
code: err.code,
@@ -188,17 +279,26 @@ export function registerDocs(program) {
// description), then the usage footer as plain prose.
emit(
section('Available docs'),
- records(result.data, {fields: ['topic', 'description']}),
+ records(result.data, {
+ fields: ['topic', 'description'],
+ layout: 'inline',
+ }),
text(
[
- `Usage: ${run} docs <topic>`,
- ` ${run} docs <topic> <section>`,
+ `Usage: ${run} docs <topic> read the whole topic`,
+ ` ${run} docs <topic> --index list its sections`,
+ ` ${run} docs <topic> <section> read one section`,
].join('\n'),
),
);
break;
}
+ case 'docs.index': {
+ emitIndex(result.data, run);
+ break;
+ }
+
case 'docs.detail': {
emit(code(formatReferenceFull(result.data, detail)));
break;
diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjs
index e1574313ab..7d4cd04b69 100644
--- a/packages/cli/clients/cli/commands/docs.test.mjs
+++ b/packages/cli/clients/cli/commands/docs.test.mjs
@@ -6,6 +6,8 @@ import * as path from 'node:path';
import * as os from 'node:os';
import {Command} from 'commander';
import {registerDocs} from './docs.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {displayWidth} from '../formatters/index.mjs';
let tmpDir;
@@ -100,3 +102,89 @@ describe('migration docs', () => {
expect(output).toContain('Map shadcn and Radix Primitives');
});
});
+
+describe('progressive reads', () => {
+ const SLOW = 60_000;
+ /** @param {string} out */
+ const widest = out => Math.max(...out.split('\n').map(line => line.length));
+
+ it('lists every topic on one line each', async () => {
+ const {status, stdout} = await runCli(['docs']);
+ expect(status).toBe(0);
+ expect(stdout).toMatch(/^principles +\S/m);
+ expect(widest(stdout)).toBeLessThanOrEqual(120);
+ }, SLOW);
+
+ it("prints a topic's section index with the keys to read by", async () => {
+ const {status, stdout} = await runCli(['docs', 'theme', '--index']);
+ expect(status).toBe(0);
+ expect(stdout).toMatch(/^quick-start +Quick Start/m);
+ expect(stdout).toContain('docs theme <section>');
+ expect(stdout).toMatch(/Read everything: +\S.* docs theme$/m);
+ expect(widest(stdout)).toBeLessThanOrEqual(120);
+ }, SLOW);
+
+ it('prints one section by its key', async () => {
+ const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);
+ expect(status).toBe(0);
+ expect(stdout).toMatch(/^## Quick Start/m);
+ }, SLOW);
+
+ it('prints the whole topic by default, as before', async () => {
+ const index = await runCli(['docs', 'theme', '--index']);
+ const full = await runCli(['docs', 'theme']);
+ expect(full.status).toBe(0);
+ expect(full.stdout).toMatch(/^## Quick Start/m);
+ expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);
+ expect((await runCli(['--detail', 'full', 'docs', 'theme'])).stdout).toBe(
+ full.stdout,
+ );
+ expect(widest(full.stdout.replace(/```[\s\S]*?```/g, ''))).toBeLessThanOrEqual(
+ 120,
+ );
+ }, SLOW);
+
+ it('returns the matching envelopes as JSON', async () => {
+ const envelope = async args => JSON.parse((await runCli([...args, '--json'])).stdout);
+ expect((await envelope(['docs', 'theme'])).type).toBe('docs.detail');
+ expect((await envelope(['docs', 'theme', '--index'])).type).toBe(
+ 'docs.index',
+ );
+ expect((await envelope(['docs', 'theme', 'quick-start'])).type).toBe(
+ 'docs.detail.section',
+ );
+ }, SLOW);
+});
+
+describe('text width in every language', () => {
+ const SLOW = 60_000;
+ /** Widest line outside code blocks, in terminal columns. */
+ const widest = out => {
+ let inCode = false;
+ let max = 0;
+ for (const line of out.split('\n')) {
+ if (/^\s*```/.test(line)) {
+ inCode = !inCode;
+ continue;
+ }
+ // A single unbreakable token (a long URL) cannot wrap without breaking it.
+ const oneToken = !/\s/.test(line.trim());
+ if (!inCode && !line.startsWith('#') && !oneToken) {
+ max = Math.max(max, displayWidth(line));
+ }
+ }
+ return max;
+ };
+
+ it.each([
+ [['docs', 'theme', '--index', '--lang', 'zh']],
+ [['docs', 'theme', '--lang', 'zh']],
+ [['--detail', 'full', 'docs', 'theme', '--lang', 'zh']],
+ [['--detail', 'full', 'docs', 'internationalization']],
+ [['--detail', 'full', 'docs', 'styling']],
+ ])('%j fits in 120 columns', async args => {
+ const {status, stdout} = await runCli(args);
+ expect(status).toBe(0);
+ expect(widest(stdout)).toBeLessThanOrEqual(120);
+ }, SLOW);
+});
diff --git a/packages/cli/clients/cli/formatters/index.mjs b/packages/cli/clients/cli/formatters/index.mjs
index 8947b1c1c8..a867c2f5b0 100644
--- a/packages/cli/clients/cli/formatters/index.mjs
+++ b/packages/cli/clients/cli/formatters/index.mjs
@@ -11,7 +11,8 @@
* which fields to show and in what order.
*
* Constraints (deliberately narrow):
- * - Plain ASCII only. No color, no TTY detection, no width wrapping. Output is
+ * - Plain ASCII only. No color and no TTY detection. Long lines wrap at a
+ * fixed {@link WRAP_WIDTH}, never at the terminal's width, so output is
* byte-for-byte deterministic whether printed or piped to an agent.
* - Renderers return an opaque {@link Block}; `emit` accepts ONLY Blocks, so a
* stray string can't leak onto stdout (the compiler rejects `emit('x')`).
@@ -33,6 +34,50 @@ export const BULLET = '-';
export const ERR = '!!';
export const WARN = '!';
+/** The column long human-output lines wrap at. */
+export const WRAP_WIDTH = 120;
+
+/** The widest first column an inline record pads to; a longer value overhangs. */
+const INLINE_LEAD_MAX = 32;
+
+/**
+ * Characters a terminal draws two columns wide: CJK ideographs and
+ * punctuation, kana, hangul, and fullwidth forms. A line may break between
+ * any two of them.
+ */
+const WIDE_CHAR =
+ /[\u1100-\u115f\u2e80-\u303e\u3041-\u33ff\u3400-\u4dbf\u4e00-\u9fff\ua000-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/u;
+
+/**
+ * How many terminal columns a string takes.
+ * @param {string} s
+ * @returns {number}
+ */
+export function displayWidth(s) {
+ let width = 0;
+ for (const ch of String(s)) width += WIDE_CHAR.test(ch) ? 2 : 1;
+ return width;
+}
+
+/**
+ * Cut a line to `width` columns, ending it with `...` when anything was cut.
+ * @param {string} line
+ * @param {number} width
+ * @returns {string}
+ */
+function truncateToWidth(line, width) {
+ if (displayWidth(line) <= width) return line;
+ let out = '';
+ let used = 0;
+ for (const ch of line) {
+ const w = WIDE_CHAR.test(ch) ? 2 : 1;
+ if (used + w > width - 3) break;
+ out += ch;
+ used += w;
+ }
+ return `${out.trimEnd()}...`;
+}
+
/**
* An opaque, renderer-produced block of output. Nominal via a private field:
* nothing outside this file can construct one, so `emit` can trust that whatever
@@ -67,6 +112,13 @@ export class Block {
* @property {Record<string, string>} [labels] - Rename a key for display.
* @property {Record<string, (value: any) => string>} [format] - Transform a
* value before rendering (e.g. prefix a command with the package manager).
+ * @property {'stacked' | 'inline'} [layout] - `stacked` (the default): one
+ * `key: value` line per field, a blank line between records. `inline`: one
+ * record per line, the first field in a padded column and the rest joined by
+ * ` - `, for a list a reader scans.
+ * @property {'wrap' | 'truncate'} [overflow] - What an inline record longer
+ * than {@link WRAP_WIDTH} does: `wrap` (the default) continues under the
+ * first column; `truncate` cuts it to one line.
*/
/** @param {unknown} v @returns {boolean} */
@@ -103,6 +155,72 @@ function toAscii(s) {
.replace(/\u00a0/g, ' ');
}
+/**
+ * Word-wrap text at `width`, keeping its own line breaks. A word longer than
+ * the width stays whole on a line of its own. Continuation lines start with
+ * `indent`.
+ * @param {string} input
+ * @param {{width?: number, indent?: string}} [options]
+ * @returns {string}
+ */
+export function wrapText(input, {width = WRAP_WIDTH, indent = ''} = {}) {
+ return String(input)
+ .split('\n')
+ .map(line => wrapLine(line, width, indent))
+ .join('\n');
+}
+
+/**
+ * @param {string} line
+ * @param {number} width
+ * @param {string} indent
+ * @returns {string}
+ */
+function wrapLine(line, width, indent) {
+ if (displayWidth(line) <= width) return line;
+ const lead = /^\s*/.exec(line)?.[0] ?? '';
+ // Tokens a line may break between: words, and each wide character on its
+ // own, since CJK text has no spaces to break at. `gap` is what joined a
+ // token to the one before it.
+ /** @type {{text: string, gap: string}[]} */
+ const tokens = [];
+ let gap = '';
+ let word = '';
+ const flush = () => {
+ if (word === '') return;
+ tokens.push({text: word, gap});
+ gap = '';
+ word = '';
+ };
+ for (const ch of line.slice(lead.length)) {
+ if (ch === ' ') {
+ flush();
+ gap = ' ';
+ } else if (WIDE_CHAR.test(ch)) {
+ flush();
+ tokens.push({text: ch, gap});
+ gap = '';
+ } else {
+ word += ch;
+ }
+ }
+ flush();
+ /** @type {string[]} */
+ const out = [];
+ let current = lead;
+ tokens.forEach(({text: token, gap: before}, i) => {
+ const joined = i === 0 ? current + token : current + before + token;
+ if (i > 0 && displayWidth(joined) > width && current.trim() !== '') {
+ out.push(current);
+ current = indent + token;
+ } else {
+ current = joined;
+ }
+ });
+ out.push(current);
+ return out.join('\n');
+}
+
/**
* A group label, optionally with an explanatory subtitle rendered on the line(s)
* directly beneath the heading (no blank line between). Whatever list/records
@@ -177,10 +295,53 @@ export function record(obj, options = {}) {
* @returns {Block}
*/
export function records(items, options = {}) {
+ if (options.layout === 'inline') return inlineRecords(items, options);
const blocks = items.map(o => record(o, options).toString()).filter(Boolean);
return new Block(blocks.join('\n\n'));
}
+/**
+ * @param {any[]} items
+ * @param {RecordOptions} options
+ * @returns {Block}
+ */
+function inlineRecords(items, options) {
+ const [lead, ...rest] = (options.fields ?? Object.keys(items[0] ?? {})).filter(
+ k => !options.omit?.includes(k),
+ );
+ if (lead == null) return new Block('');
+ /** @param {any} o @param {string} k */
+ const value = (o, k) => {
+ const fmt = options.format?.[k];
+ return fmt ? fmt(o[k]) : renderValue(o[k]);
+ };
+ const leads = items.map(o => (isEmpty(o[lead]) ? '' : value(o, lead)));
+ const column = Math.min(
+ Math.max(0, ...leads.map(l => displayWidth(l))),
+ INLINE_LEAD_MAX,
+ );
+ const indent = ' '.repeat(column + 2);
+ const lines = items.map((o, i) => {
+ const tail = toAscii(
+ rest
+ .filter(k => !isEmpty(o[k]))
+ .map(k => value(o, k))
+ .join(' - '),
+ );
+ if (tail === '') return toAscii(leads[i]);
+ const head = toAscii(`${leads[i].padEnd(column)} `);
+ if (options.overflow === 'truncate') {
+ return truncateToWidth(head + tail, WRAP_WIDTH);
+ }
+ // Wrap only the tail, so the padded first column survives the wrap.
+ const [first, ...more] = wrapText(tail, {
+ width: Math.max(20, WRAP_WIDTH - displayWidth(head)),
+ }).split('\n');
+ return [head + first, ...more.map(line => indent + line)].join('\n');
+ });
+ return new Block(lines.join('\n'));
+}
+
/**
* A verbatim block — source dumps, layout skeletons, or a markdown doc. Output
* is byte-for-byte (NOT ASCII-normalized), so it survives piping
diff --git a/packages/cli/clients/cli/formatters/index.test.mjs b/packages/cli/clients/cli/formatters/index.test.mjs
index efc1a518ee..15af2d58db 100644
--- a/packages/cli/clients/cli/formatters/index.test.mjs
+++ b/packages/cli/clients/cli/formatters/index.test.mjs
@@ -8,6 +8,9 @@ import {
list,
record,
records,
+ wrapText,
+ displayWidth,
+ WRAP_WIDTH,
code,
Block,
BULLET,
@@ -148,3 +151,91 @@ describe('emit', () => {
expect(spy).not.toHaveBeenCalled();
});
});
+
+describe('wrapText', () => {
+ it('leaves short lines and its own line breaks alone', () => {
+ expect(wrapText('a b\nc')).toBe('a b\nc');
+ });
+
+ it('wraps at the width with a hanging indent', () => {
+ expect(wrapText('aaa bbb ccc', {width: 7, indent: ' '})).toBe('aaa bbb\n ccc');
+ });
+
+ it('keeps a word longer than the width whole', () => {
+ expect(wrapText('x '.concat('y'.repeat(20)), {width: 10})).toBe(
+ `x\n${'y'.repeat(20)}`,
+ );
+ });
+});
+
+describe('records inline layout', () => {
+ const items = [
+ {id: 'a', title: 'Alpha', summary: 'First.'},
+ {id: 'bbb', title: 'Beta', summary: ''},
+ ];
+
+ it('puts one record on each line under a padded first column', () => {
+ expect(
+ records(items, {fields: ['id', 'title', 'summary'], layout: 'inline'}).toString(),
+ ).toBe('a Alpha - First.\nbbb Beta');
+ });
+
+ it('wraps a long record under the first column', () => {
+ const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+ layout: 'inline',
+ }).toString();
+ expect(out.split('\n').length).toBeGreaterThan(1);
+ expect(out.split('\n').every(line => line.length <= WRAP_WIDTH)).toBe(true);
+ expect(out.split('\n')[1].startsWith(' word')).toBe(true);
+ });
+
+ it('keeps the first column padded on a record that wraps', () => {
+ const out = records(
+ [
+ {id: 'a', text: 'word '.repeat(40).trim()},
+ {id: 'longer', text: 'x'},
+ ],
+ {layout: 'inline'},
+ ).toString();
+ const lines = out.split('\n');
+ expect(lines[0].startsWith(`a${' '.repeat(7)}word`)).toBe(true);
+ expect(lines[1].startsWith(' '.repeat(8) + 'word')).toBe(true);
+ expect(lines.at(-1)).toBe('longer x');
+ expect(lines.every(line => line.length <= WRAP_WIDTH)).toBe(true);
+ });
+
+ it('cuts a long record to one line when asked', () => {
+ const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+ layout: 'inline',
+ overflow: 'truncate',
+ }).toString();
+ expect(out.includes('\n')).toBe(false);
+ expect(out.length).toBeLessThanOrEqual(WRAP_WIDTH);
+ expect(out.endsWith('...')).toBe(true);
+ });
+});
+
+describe('wide characters', () => {
+ it('counts CJK characters as two columns', () => {
+ expect(displayWidth('亮/暗模式')).toBe(9);
+ });
+
+ it('wraps CJK text, which has no spaces, by columns', () => {
+ const out = wrapText('中'.repeat(100), {width: 20});
+ expect(out.split('\n').every(line => displayWidth(line) <= 20)).toBe(true);
+ expect(out.split('\n')).toHaveLength(10);
+ });
+
+ it('keeps spaces between Latin words next to CJK', () => {
+ expect(wrapText('运行 astryx docs 查看', {width: 200})).toBe('运行 astryx docs 查看');
+ });
+
+ it('cuts an inline record to columns, not characters', () => {
+ const out = records([{id: 'a', text: '中'.repeat(100)}], {
+ layout: 'inline',
+ overflow: 'truncate',
+ }).toString();
+ expect(displayWidth(out)).toBeLessThanOrEqual(WRAP_WIDTH);
+ expect(out.endsWith('...')).toBe(true);
+ });
+});
diff --git a/packages/cli/clients/cli/lib/manifest.mjs b/packages/cli/clients/cli/lib/manifest.mjs
index 2cc563ceec..154514f559 100644
--- a/packages/cli/clients/cli/lib/manifest.mjs
+++ b/packages/cli/clients/cli/lib/manifest.mjs
@@ -55,7 +55,7 @@ export const RESPONSE_TYPES = {
'component.detail.showcase',
'component.detail.blocks',
],
- docs: ['docs.list', 'docs.detail', 'docs.detail.section'],
+ docs: ['docs.list', 'docs.index', 'docs.detail', 'docs.detail.section'],
blog: ['blog.list', 'blog.detail'],
discover: [
'discover.list',
@@ -105,7 +105,12 @@ const EXAMPLES = {
'astryx component XDSButton',
'astryx component XDSButton --props --json',
],
- docs: ['astryx docs', 'astryx docs spacing --json'],
+ docs: [
+ 'astryx docs',
+ 'astryx docs spacing --json',
+ 'astryx docs theme --index',
+ 'astryx docs theme quick-start',
+ ],
discover: ['astryx discover --json'],
search: [
'astryx search modal --json',
diff --git a/packages/cli/foundation/config/project.mjs b/packages/cli/foundation/config/project.mjs
index cd5bfbfeb9..a24f9927ac 100644
--- a/packages/cli/foundation/config/project.mjs
+++ b/packages/cli/foundation/config/project.mjs
@@ -38,6 +38,7 @@ import {parseConfig} from '../../authoring/config/parse.mjs';
import {
loadIntegrations,
loadLocalIntegration,
+ markProviderConflicts,
} from '../integrations/integrations.mjs';
import {autolinkIntegrations} from '../integrations/autolink.mjs';
import {
@@ -203,10 +204,11 @@ export class Project {
/** @type {ProjectIntegrationIssue[]} */
#issues = [];
/**
- * Package names of integrations whose issues have already been collected
- * (via a discovery method or a direct issues() validation), so issues() can
- * fill in only the ones not yet visited and never double-collect.
- * @type {Set<string>}
+ * Loaded integrations whose issues have already been collected (via a
+ * discovery method or a direct issues() validation), so issues() can fill in
+ * only the ones not yet visited and never double-collect. Keyed by entry, not
+ * label: two entries can share a package name (an alias at another version).
+ * @type {Set<object>}
*/
#visitedIssues = new Set();
@@ -277,6 +279,8 @@ export class Project {
loadedIntegrations = await loadIntegrations(integrations, {
cwd: projectDir,
fresh,
+ // Provider identity is resolved once, below, over the final set.
+ resolveProviders: false,
});
}
@@ -310,6 +314,10 @@ export class Project {
else loadedIntegrations[existing] = localIntegration;
}
+ // Autolinked and local packages can claim a provider ID that a configured
+ // package already holds, so identity is resolved once over the final set.
+ loadedIntegrations = markProviderConflicts(loadedIntegrations);
+
// The debug recorder resolves its settings synchronously, long before any
// command gets here, so this is where a project's `debug` block gets a
// turn. The event is not written until process exit, so settings applied
@@ -436,6 +444,13 @@ export class Project {
* @returns {string}
*/
#pkgLabel(integration) {
+ // A set-aside package is labelled name@version, so its issue never reads as
+ // the winner's, even when both share a package name.
+ if (integration?.__providerConflict) {
+ return integration.version
+ ? `${integration.name}@${integration.version}`
+ : (integration.__spec ?? integration.name);
+ }
return integration?.name ?? integration?.__spec ?? '(integration)';
}
@@ -463,8 +478,8 @@ export class Project {
*/
async #collectIssues(integration) {
const pkg = this.#pkgLabel(integration);
- if (this.#visitedIssues.has(pkg)) return;
- this.#visitedIssues.add(pkg);
+ if (this.#visitedIssues.has(integration)) return;
+ this.#visitedIssues.add(integration);
// A manifest that failed to load (throwing import / invalid shape) is
// recorded as a marker by loadIntegrations — surface it as an issue and
// skip validation (there's no manifest to validate).
diff --git a/packages/cli/foundation/discovery/authoring-self-docs.mjs b/packages/cli/foundation/discovery/authoring-self-docs.mjs
new file mode 100644
index 0000000000..43f1aa22ef
--- /dev/null
+++ b/packages/cli/foundation/discovery/authoring-self-docs.mjs
@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The authoring self-docs, and the `authoring` topic built from them.
+ *
+ * @input The SchemaDoc each authoring module colocates as `*.doc.mjs` under
+ * packages/cli/authoring.
+ * @output {@link AUTHORING_SELF_DOCS} (every self-doc, in reading order), the
+ * `authoring` reference topic with one section per self-doc, and an audit
+ * naming any self-doc the topic cannot reach, any that fails to load, and any
+ * section over the docs output budget.
+ * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
+ * (the audit). Lives in foundation because authoring/ holds only contracts.
+ * A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
+ * the self-doc tests fail.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {CLI_ROOT} from '../fs/paths.mjs';
+import {
+ DOC_OUTPUT_BUDGET_BYTES,
+ oversizedDocSections,
+} from './docs-output-budget.mjs';
+
+/** The directory the self-docs live under. */
+export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
+
+/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
+export const AUTHORING_SELF_DOCS = [
+ 'integration/integration.doc.mjs',
+ 'config/config.doc.mjs',
+ 'codemod/codemod.doc.mjs',
+ 'identity/identity.doc.mjs',
+ 'doctypes/base/graph-fields.doc.mjs',
+ 'doctypes/component/component.doc.mjs',
+ 'doctypes/hook/hook.doc.mjs',
+ 'doctypes/function/function.doc.mjs',
+ 'doctypes/command/command.doc.mjs',
+ 'doctypes/enum/enum.doc.mjs',
+ 'doctypes/namespace/namespace.doc.mjs',
+ 'doctypes/reference/reference.doc.mjs',
+ 'doctypes/schema/schema.doc.mjs',
+ 'doctypes/template/template.doc.mjs',
+];
+
+/** Blocks a self-doc note may carry that a topic section can render. */
+const TOPIC_BLOCKS = new Set(['prose', 'list', 'code', 'heading', 'table']);
+
+/**
+ * Every `*.doc.mjs` under `root`, relative and sorted.
+ * @param {string} [root]
+ * @returns {string[]}
+ */
+export function discoverAuthoringSelfDocSources(root = AUTHORING_ROOT) {
+ /** @type {string[]} */
+ const found = [];
+ /** @param {string} dir */
+ const walk = dir => {
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+ if (entry.name === 'node_modules' || entry.name.startsWith('__')) continue;
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) walk(full);
+ else if (entry.name.endsWith('.doc.mjs')) {
+ found.push(path.relative(root, full).split(path.sep).join('/'));
+ }
+ }
+ };
+ walk(root);
+ return found.sort();
+}
+
+/**
+ * Import each self-doc. One that fails is reported, never thrown, so one bad
+ * file cannot take the rest of the topic down with it.
+ * @param {string[]} [sources]
+ * @param {string} [root]
+ * @returns {Promise<{loaded: {source: string, doc: any}[], failed: {source: string, error: string}[]}>}
+ */
+export async function loadAuthoringSelfDocs(
+ sources = AUTHORING_SELF_DOCS,
+ root = AUTHORING_ROOT,
+) {
+ const loaded = [];
+ const failed = [];
+ for (const source of sources) {
+ try {
+ const mod = await import(pathToFileURL(path.join(root, source)).href);
+ const doc = mod.doc ?? mod.docs ?? mod.default;
+ if (typeof doc?.name !== 'string' || typeof doc?.description !== 'string') {
+ throw new Error('exports no doc with a name and a description');
+ }
+ loaded.push({source, doc});
+ } catch (error) {
+ failed.push({
+ source,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ }
+ }
+ return {loaded, failed};
+}
+
+/**
+ * @param {any[]} fields
+ * @returns {string[][]}
+ */
+function fieldRows(fields) {
+ return fields.flatMap(field => [
+ [
+ String(field.name),
+ String(field.type ?? ''),
+ field.required ? 'yes' : 'no',
+ [
+ field.description,
+ field.default != null ? `Default: ${field.default}.` : null,
+ field.example != null ? `Example: ${field.example}.` : null,
+ ]
+ .filter(Boolean)
+ .join(' '),
+ ],
+ ...fieldRows(field.fields ?? []),
+ ]);
+}
+
+/**
+ * One self-doc as a topic section, keyed by the doc's own name.
+ * @param {any} doc
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
+ */
+function selfDocSection(doc) {
+ /** @type {any[]} */
+ const content = [{type: 'prose', text: doc.description}];
+ 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,
+ });
+ }
+ for (const example of doc.examples ?? []) {
+ if (typeof example?.code !== 'string' || example.code.trim() === '') continue;
+ content.push({
+ type: 'code',
+ lang: example.lang ?? 'js',
+ ...(example.label ? {label: example.label} : {}),
+ code: example.code,
+ });
+ }
+ for (const note of doc.notes ?? []) {
+ if (TOPIC_BLOCKS.has(note?.type)) content.push(note);
+ }
+ return {id: doc.name, title: doc.displayName ?? doc.name, content};
+}
+
+/**
+ * The `authoring` topic: one section per self-doc, in the order given.
+ * @param {any[]} docs
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceDoc}
+ */
+export function buildAuthoringReferenceDoc(docs) {
+ return /** @type {any} */ ({
+ name: 'authoring',
+ title: 'Authoring Reference',
+ category: 'guide',
+ description:
+ 'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+ sections: docs.map(selfDocSection),
+ });
+}
+
+/**
+ * The `authoring` topic from every self-doc that loads. One that fails is left
+ * out here and reported by {@link auditAuthoringSelfDocs}.
+ * @returns {Promise<import('../../authoring/doctypes/reference/type').ReferenceDoc>}
+ */
+export async function buildAuthoringTopic() {
+ const {loaded} = await loadAuthoringSelfDocs();
+ return buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
+}
+
+/**
+ * What stands between a self-doc and a reader of `astryx docs authoring`.
+ * @param {{root?: string, sources?: string[], budget?: number}} [options]
+ * @returns {Promise<{
+ * sections: number,
+ * unreachable: string[],
+ * failed: {source: string, error: string}[],
+ * oversized: {key: string, title: string, bytes: number}[],
+ * }>}
+ */
+export async function auditAuthoringSelfDocs({
+ root = AUTHORING_ROOT,
+ sources = AUTHORING_SELF_DOCS,
+ budget = DOC_OUTPUT_BUDGET_BYTES,
+} = {}) {
+ const listed = new Set(sources);
+ const unreachable = discoverAuthoringSelfDocSources(root).filter(
+ source => !listed.has(source),
+ );
+ const {loaded, failed} = await loadAuthoringSelfDocs(sources, root);
+ const topic = buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
+ return {
+ sections: topic.sections.length,
+ unreachable,
+ failed,
+ oversized: oversizedDocSections(topic.sections, budget),
+ };
+}
diff --git a/packages/cli/foundation/discovery/authoring-self-docs.test.mjs b/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
new file mode 100644
index 0000000000..58233f23cd
--- /dev/null
+++ b/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+ AUTHORING_SELF_DOCS,
+ auditAuthoringSelfDocs,
+ buildAuthoringTopic,
+ discoverAuthoringSelfDocSources,
+} from './authoring-self-docs.mjs';
+import {problemsInTopic} from './docs-discovery.mjs';
+import {docs} from '../../api/docs/docs.mjs';
+
+const SLOW = 60_000;
+
+describe('authoring self-docs', () => {
+ it('lists every self-doc on disk exactly once', () => {
+ expect([...AUTHORING_SELF_DOCS].sort()).toEqual(
+ discoverAuthoringSelfDocSources(),
+ );
+ expect(new Set(AUTHORING_SELF_DOCS).size).toBe(AUTHORING_SELF_DOCS.length);
+ });
+
+ it('audits clean: every self-doc loads, is reachable, and fits one read', async () => {
+ expect(await auditAuthoringSelfDocs()).toEqual({
+ sections: AUTHORING_SELF_DOCS.length,
+ unreachable: [],
+ failed: [],
+ oversized: [],
+ });
+ });
+
+ it('builds a valid topic with one section per self-doc', async () => {
+ const topic = await buildAuthoringTopic();
+ expect(problemsInTopic(topic)).toEqual([]);
+ expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
+ });
+
+ it('is readable progressively through the docs API', async () => {
+ const index = await docs('authoring', undefined, {index: true});
+ expect(index.type).toBe('docs.index');
+ expect(index.data.sections.map(s => s.id)).toContain('integration');
+ const section = await docs('authoring', 'integration');
+ expect(section.data.title).toBe('Astryx Integration');
+ expect(section.data.content.some(block => block.type === 'table')).toBe(true);
+ }, SLOW);
+});
+
+describe('auditAuthoringSelfDocs', () => {
+ let root;
+
+ beforeEach(() => {
+ root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-self-docs-'));
+ fs.mkdirSync(path.join(root, 'kept'));
+ fs.writeFileSync(
+ path.join(root, 'kept', 'kept.doc.mjs'),
+ "export const doc = {type: 'schema', name: 'kept', displayName: 'Kept', description: 'Listed.', fields: []};\n",
+ );
+ });
+
+ afterEach(() => {
+ fs.rmSync(root, {recursive: true, force: true});
+ });
+
+ it('names a self-doc on disk that the list leaves out', async () => {
+ fs.writeFileSync(
+ path.join(root, 'kept', 'forgotten.doc.mjs'),
+ "export const doc = {name: 'forgotten', description: 'Not listed.'};\n",
+ );
+ const audit = await auditAuthoringSelfDocs({root, sources: ['kept/kept.doc.mjs']});
+ expect(audit.unreachable).toEqual(['kept/forgotten.doc.mjs']);
+ });
+
+ it('reports a self-doc that fails to load instead of throwing', async () => {
+ fs.writeFileSync(path.join(root, 'kept', 'broken.doc.mjs'), 'export const doc = {;\n');
+ const audit = await auditAuthoringSelfDocs({
+ root,
+ sources: ['kept/kept.doc.mjs', 'kept/broken.doc.mjs'],
+ });
+ expect(audit.failed.map(entry => entry.source)).toEqual(['kept/broken.doc.mjs']);
+ expect(audit.sections).toBe(1);
+ });
+
+ it('names a section over the budget', async () => {
+ const audit = await auditAuthoringSelfDocs({
+ root,
+ sources: ['kept/kept.doc.mjs'],
+ budget: 10,
+ });
+ expect(audit.oversized).toEqual([
+ expect.objectContaining({key: 'kept', title: 'Kept'}),
+ ]);
+ });
+});
diff --git a/packages/cli/foundation/discovery/component-discovery.mjs b/packages/cli/foundation/discovery/component-discovery.mjs
index d62e7d050a..85aa9c3655 100644
--- a/packages/cli/foundation/discovery/component-discovery.mjs
+++ b/packages/cli/foundation/discovery/component-discovery.mjs
@@ -7,11 +7,12 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
import {existsCaseExact} from '../fs/paths.mjs';
+import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);
/** The owner package name for built-in (core) components. */
-export const CORE_PACKAGE = '@astryxdesign/core';
+export const CORE_PACKAGE = CORE_PROVIDER_ID;
/** Conventional doc-file suffixes for integration components (same-stem). */
const INTEGRATION_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
diff --git a/packages/cli/foundation/discovery/docs-discovery.mjs b/packages/cli/foundation/discovery/docs-discovery.mjs
index 27efee64f7..59af1b7d71 100644
--- a/packages/cli/foundation/discovery/docs-discovery.mjs
+++ b/packages/cli/foundation/discovery/docs-discovery.mjs
@@ -33,7 +33,16 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import {CLI_ROOT} from '../fs/paths.mjs';
import {importUserModule} from '../fs/module-loader.mjs';
+import {CLI_PROVIDER_ID} from '../identity/providers.mjs';
import {parseDoc} from '../../authoring/doctypes/parse.mjs';
+import {
+ sectionKey,
+ sectionKeyProblems,
+ sourceTitle,
+ withSourceTitle,
+} from './docs-section-key.mjs';
+
+export {withSourceTitle};
/** Where the CLI's own topics live. */
const BUILTIN_DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');
@@ -43,7 +52,7 @@ const BUILTIN_DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');
* (assets/docs), not in @astryxdesign/core, so this is the CLI's own name —
* unlike component discovery, whose built-ins belong to core.
*/
-export const BUILTIN_DOCS_PACKAGE = '@astryxdesign/cli';
+export const BUILTIN_DOCS_PACKAGE = CLI_PROVIDER_ID;
/**
* A built-in topic file: `{topic}.doc.mjs`. Anchored at both ends so a
@@ -128,12 +137,18 @@ const BLOCK_FIELDS = {
'token-ref': ['topic', 'section'],
};
+/** Blocks that are valid authoring but require the compiled graph renderer. */
+const GRAPH_BLOCK_TYPES = new Set(['workflow', 'collection', 'reference']);
+
/**
* Fields a block kind may carry but does not need. Kept per kind rather than
* globally: only a code block renders a `label`, so allowing it everywhere
* would wave through the misspellings this check exists to catch.
*/
-const OPTIONAL_BLOCK_FIELDS = {code: ['label']};
+/** @type {Record<string, string[]>} */
+const OPTIONAL_BLOCK_FIELDS = {
+ code: ['label'],
+};
/**
* Fields whose value has to be one of a set, because the renderer indexes on
@@ -147,7 +162,7 @@ const BLOCK_FIELD_VALUES = {
};
/** Keys a section may carry. */
-const SECTION_FIELDS = ['title', 'category', 'content', 'previewType'];
+const SECTION_FIELDS = ['id', 'title', 'category', 'content', 'previewType'];
/**
* Check the fields the docs surfaces actually read. `parseDoc` is the outer
@@ -173,83 +188,119 @@ export function problemsInTopic(doc) {
`name: "${doc.name}" is not URL-safe. A topic name is its CLI argument and its docsite path, so it may hold only letters, digits, "_" and "-".`,
);
}
+ for (const field of ['placement', 'aliases', 'audience']) {
+ if (doc?.[field] != null) {
+ problems.push(
+ `${field}: requires the compiled graph reader and is not supported by legacy topic readers`,
+ );
+ }
+ }
if (!Array.isArray(doc?.sections) || doc.sections.length === 0) {
problems.push('sections: expected at least one section');
return problems;
}
- doc.sections.forEach((/** @type {any} */ section, /** @type {number} */ s) => {
- const at = `sections[${s}]`;
- if (typeof section?.title !== 'string' || section.title === '') {
- problems.push(`${at}.title: expected a non-empty string`);
- }
- for (const key of Object.keys(section ?? {})) {
- if (!SECTION_FIELDS.includes(key)) {
- problems.push(`${at}.${key}: not a field of a section`);
+ doc.sections.forEach(
+ (/** @type {any} */ section, /** @type {number} */ s) => {
+ const at = `sections[${s}]`;
+ if (typeof section?.title !== 'string' || section.title === '') {
+ problems.push(`${at}.title: expected a non-empty string`);
}
- }
- if (!Array.isArray(section?.content)) {
- problems.push(`${at}.content: expected an array of blocks`);
- return;
- }
- section.content.forEach((/** @type {any} */ block, /** @type {number} */ b) => {
- const blockAt = `${at}.content[${b}]`;
- const fields = /** @type {Record<string, string[]>} */ (BLOCK_FIELDS)[block?.type];
- if (fields == null) {
- problems.push(
- `${blockAt}.type: ${JSON.stringify(block?.type)} is not one of ${Object.keys(BLOCK_FIELDS).join(', ')}`,
- );
- return;
- }
- for (const field of fields) {
- const value = block[field];
- // Empty counts as missing, the way it does for the doc's own title: a
- // block whose text is '' passes every other check and renders as a gap.
- if (value == null) {
- problems.push(`${blockAt}.${field}: required for a ${block.type} block`);
- } else if (typeof value === 'string' && value.trim() === '') {
- problems.push(`${blockAt}.${field}: expected a non-empty string`);
- } else if (Array.isArray(value) && value.length === 0) {
- problems.push(`${blockAt}.${field}: expected a non-empty array`);
+ for (const key of Object.keys(section ?? {})) {
+ if (!SECTION_FIELDS.includes(key)) {
+ problems.push(`${at}.${key}: not a field of a section`);
}
}
- const allowedValues =
- /** @type {Record<string, Record<string, unknown[]>>} */ (BLOCK_FIELD_VALUES)[block.type] ?? {};
- for (const [field, values] of Object.entries(allowedValues)) {
- const value = block[field];
- if (value != null && !values.includes(value)) {
- problems.push(
- `${blockAt}.${field}: ${JSON.stringify(value)} is not one of ${values.join(', ')}`,
- );
- }
+ if (!Array.isArray(section?.content)) {
+ problems.push(`${at}.content: expected an array of blocks`);
+ return;
}
- // A table's cells are read by column index, so a short row renders blank
- // cells and a long one drops its tail — both silently.
- if (block.type === 'table' && Array.isArray(block.headers) && Array.isArray(block.rows)) {
- block.rows.forEach((/** @type {any} */ row, /** @type {number} */ r) => {
- if (!Array.isArray(row)) {
- problems.push(`${blockAt}.rows[${r}]: expected an array of cells`);
- } else if (row.length !== block.headers.length) {
- problems.push(
- `${blockAt}.rows[${r}]: has ${row.length} cells but the table has ${block.headers.length} headers`,
+ section.content.forEach(
+ (/** @type {any} */ block, /** @type {number} */ b) => {
+ const blockAt = `${at}.content[${b}]`;
+ const fields = /** @type {Record<string, string[]>} */ (BLOCK_FIELDS)[
+ block?.type
+ ];
+ if (fields == null) {
+ if (GRAPH_BLOCK_TYPES.has(block?.type)) {
+ problems.push(
+ `${blockAt}.type: ${JSON.stringify(block.type)} requires the compiled graph renderer and is not supported by legacy topic readers`,
+ );
+ } else {
+ problems.push(
+ `${blockAt}.type: ${JSON.stringify(block?.type)} is not one of ${Object.keys(BLOCK_FIELDS).join(', ')}`,
+ );
+ }
+ return;
+ }
+ for (const field of fields) {
+ const value = block[field];
+ // Empty counts as missing, the way it does for the doc's own title: a
+ // block whose text is '' passes every other check and renders as a gap.
+ if (value == null) {
+ problems.push(
+ `${blockAt}.${field}: required for a ${block.type} block`,
+ );
+ } else if (typeof value === 'string' && value.trim() === '') {
+ problems.push(`${blockAt}.${field}: expected a non-empty string`);
+ } else if (Array.isArray(value) && value.length === 0) {
+ problems.push(`${blockAt}.${field}: expected a non-empty array`);
+ }
+ }
+ const allowedValues =
+ /** @type {Record<string, Record<string, unknown[]>>} */ (
+ BLOCK_FIELD_VALUES
+ )[block.type] ?? {};
+ for (const [field, values] of Object.entries(allowedValues)) {
+ const value = block[field];
+ if (value != null && !values.includes(value)) {
+ problems.push(
+ `${blockAt}.${field}: ${JSON.stringify(value)} is not one of ${values.join(', ')}`,
+ );
+ }
+ }
+ // A table's cells are read by column index, so a short row renders blank
+ // cells and a long one drops its tail — both silently.
+ if (
+ block.type === 'table' &&
+ Array.isArray(block.headers) &&
+ Array.isArray(block.rows)
+ ) {
+ block.rows.forEach(
+ (/** @type {any} */ row, /** @type {number} */ r) => {
+ if (!Array.isArray(row)) {
+ problems.push(
+ `${blockAt}.rows[${r}]: expected an array of cells`,
+ );
+ } else if (row.length !== block.headers.length) {
+ problems.push(
+ `${blockAt}.rows[${r}]: has ${row.length} cells but the table has ${block.headers.length} headers`,
+ );
+ }
+ },
);
}
- });
- }
- // An unknown key is almost always a misspelled required one, and it
- // would otherwise reach a reader as a block that renders nothing.
- const allowed = [
- 'type',
- ...fields,
- ...(/** @type {Record<string, string[]>} */ (OPTIONAL_BLOCK_FIELDS)[block.type] ?? []),
- ];
- for (const key of Object.keys(block)) {
- if (!allowed.includes(key)) {
- problems.push(`${blockAt}.${key}: not a field of a ${block.type} block`);
- }
- }
- });
- });
+ // An unknown key is almost always a misspelled required one, and it
+ // would otherwise reach a reader as a block that renders nothing.
+ const allowed = [
+ 'type',
+ ...fields,
+ ...(OPTIONAL_BLOCK_FIELDS[block.type] ?? []),
+ ];
+ for (const key of Object.keys(block)) {
+ if (!allowed.includes(key)) {
+ problems.push(
+ `${blockAt}.${key}: not a field of a ${block.type} block`,
+ );
+ }
+ }
+ },
+ );
+ },
+ );
+ // Readers address a section by its key, so two sections sharing one would
+ // make one of them unreachable.
+ problems.push(...sectionKeyProblems(doc.sections));
return problems;
}
@@ -283,7 +334,9 @@ export async function discoverIntegrationDocs(integration) {
const full = path.join(dirPath, entry.name);
if (entry.isDirectory()) {
scanDir(full);
- } else if (INTEGRATION_DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+ } else if (
+ INTEGRATION_DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))
+ ) {
files.push(full);
}
}
@@ -298,7 +351,11 @@ export async function discoverIntegrationDocs(integration) {
try {
doc = parseDoc(await loadTopicModule(file), path.basename(file));
} catch (err) {
- errors.push(new Error(`${path.relative(docsDir, file)}: ${/** @type {any} */ (err).message}`));
+ errors.push(
+ new Error(
+ `${path.relative(docsDir, file)}: ${/** @type {any} */ (err).message}`,
+ ),
+ );
continue;
}
const problems = problemsInTopic(doc);
@@ -315,7 +372,8 @@ export async function discoverIntegrationDocs(integration) {
const parsed = /** @type {any} */ (doc);
// Two files claiming one name would collapse into a single entry, and the
// one that lost would never be reachable. Named here, where both files are.
- const previous = seen.get(parsed.name);
+ const topicKey = parsed.name.toLowerCase();
+ const previous = seen.get(topicKey);
if (previous) {
errors.push(
new Error(
@@ -324,7 +382,7 @@ export async function discoverIntegrationDocs(integration) {
);
continue;
}
- seen.set(parsed.name, path.relative(docsDir, file));
+ seen.set(topicKey, path.relative(docsDir, file));
if (parsed.replaces != null && parsed.extends != null) {
errors.push(
new Error(
@@ -349,9 +407,10 @@ export async function discoverIntegrationDocs(integration) {
}
/**
- * Merge an extension onto a base topic: a section whose title matches one in
- * the base replaces it, a section the base does not have is appended, and the
- * title/description are taken from the extension when it states them.
+ * Merge an extension onto a base topic: a section with a stable `id` replaces
+ * the base section with the same `id`; legacy sections without IDs fall back to
+ * title matching. A section with no match is appended, and title/description
+ * are taken from the extension when it states them.
*
* Keyed by section TITLE rather than by position, the way the localization
* overlays are — position keying grafts an overlay onto whichever section
@@ -365,9 +424,18 @@ export async function discoverIntegrationDocs(integration) {
export function mergeTopic(base, overlay) {
const sections = [...(base.sections ?? [])];
for (const section of overlay.sections ?? []) {
- const at = sections.findIndex((/** @type {any} */ s) => s.title === section.title);
- if (at === -1) sections.push(section);
- else sections[at] = section;
+ const at = findMergeTarget(sections, section);
+ if (at === -1) {
+ sections.push(section);
+ } else {
+ // A legacy extension that replaces a section which has since gained a
+ // stable ID keeps that ID, so readers addressing it keep working.
+ const replaced = sections[at];
+ sections[at] =
+ section.id == null && replaced.id != null
+ ? withSourceTitle({...section, id: replaced.id}, sourceTitle(section))
+ : section;
+ }
}
return {
...base,
@@ -377,6 +445,41 @@ export function mergeTopic(base, overlay) {
};
}
+/**
+ * The base section an extension section replaces. A stable ID matches first.
+ * Otherwise the exact title matches when at least one side has no ID: the
+ * migration window in which the base or the extension adopts stable IDs
+ * before the other does. Two different authored IDs stay distinct even under
+ * one title.
+ *
+ * @param {any[]} sections
+ * @param {any} section
+ * @returns {number}
+ */
+function findMergeTarget(sections, section) {
+ const title = sourceTitle(section);
+ const key = sectionKey(section);
+ // A section is addressed by its key: an authored id, or the key its title
+ // derives, which is the key the topic's index shows. Matching on it means an
+ // extension never appends a second section under a key already in use.
+ const byKey = () =>
+ sections.findIndex(candidate => sectionKey(candidate) === key);
+ const legacyTitleMatch = () =>
+ sections.findIndex(
+ candidate => candidate.id == null && sourceTitle(candidate) === title,
+ );
+ if (section.id != null) {
+ const byId = byKey();
+ return byId === -1 ? legacyTitleMatch() : byId;
+ }
+ const legacy = legacyTitleMatch();
+ if (legacy !== -1) return legacy;
+ const sameTitle = sections.findIndex(
+ candidate => sourceTitle(candidate) === title,
+ );
+ return sameTitle === -1 ? byKey() : sameTitle;
+}
+
/**
* Every topic a project can read, and the relationships between them.
*
@@ -399,7 +502,7 @@ export class DocsCatalog {
static fromBuiltins(builtins = discoverBuiltinTopics()) {
const catalog = new DocsCatalog();
for (const [name, file] of Object.entries(builtins)) {
- catalog.#topics.set(name, {
+ catalog.#topics.set(name.toLowerCase(), {
name,
package: BUILTIN_DOCS_PACKAGE,
path: file,
@@ -455,7 +558,9 @@ export class DocsCatalog {
// The replacement takes the base topic's slot, so a reader that opens
// the first topic (or the nth) sees the same one it did before.
const replaced = target.name;
- this.#replaceAt(replaced, {
+ const replacedKey = replaced.toLowerCase();
+ const replacementKey = record.name.toLowerCase();
+ this.#replaceAt(replacedKey, {
name: record.name,
package: record.package,
path: record.path,
@@ -466,17 +571,18 @@ export class DocsCatalog {
// Extensions were authored against the content that just went away.
extensions: [],
});
- if (record.name !== replaced) {
- this.#aliases.set(replaced, record.name);
+ if (replacementKey !== replacedKey) {
+ this.#aliases.set(replacedKey, replacementKey);
// A topic renamed twice keeps every name it has ever answered to.
for (const [from, to] of this.#aliases) {
- if (to === replaced) this.#aliases.set(from, record.name);
+ if (to === replacedKey) this.#aliases.set(from, replacementKey);
}
}
return warning;
}
- const existing = this.#topics.get(record.name);
+ const topicKey = record.name.toLowerCase();
+ const existing = this.#topics.get(topicKey);
if (existing) {
return {
code: 'invalid_doc',
@@ -484,7 +590,7 @@ export class DocsCatalog {
message: `Topic "${record.name}" is already provided by ${existing.package}. Give it another name, or declare \`replaces: '${record.name}'\` to take its place.`,
};
}
- this.#topics.set(record.name, {
+ this.#topics.set(topicKey, {
name: record.name,
package: record.package,
path: record.path,
@@ -519,7 +625,7 @@ export class DocsCatalog {
/** @returns {string[]} every topic name, in read order */
names() {
- return [...this.#topics.keys()];
+ return [...this.#topics.values()].map(entry => entry.name);
}
/** @returns {DocsTopicEntry[]} every topic, in read order */
@@ -536,7 +642,7 @@ export class DocsCatalog {
/** @type {Map<string, DocsTopicEntry>} */
const next = new Map();
for (const [key, value] of this.#topics) {
- if (key === name) next.set(entry.name, entry);
+ if (key === name.toLowerCase()) next.set(entry.name.toLowerCase(), entry);
else next.set(key, value);
}
this.#topics = next;
diff --git a/packages/cli/foundation/discovery/docs-discovery.test.mjs b/packages/cli/foundation/discovery/docs-discovery.test.mjs
index 99098a3ae2..afdc71814e 100644
--- a/packages/cli/foundation/discovery/docs-discovery.test.mjs
+++ b/packages/cli/foundation/discovery/docs-discovery.test.mjs
@@ -31,7 +31,9 @@ function topic(fields) {
name: 'deploying',
title: 'Deploying',
description: 'How to ship it.',
- sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}],
+ sections: [
+ {title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]},
+ ],
...fields,
};
}
@@ -97,7 +99,9 @@ describe('discoverIntegrationDocs', () => {
}),
);
expect(errors).toEqual([]);
- expect(records.map(r => [r.name, r.package, r.replaces, r.extendsTopic])).toEqual([
+ expect(
+ records.map(r => [r.name, r.package, r.replaces, r.extendsTopic]),
+ ).toEqual([
['deploying', '@acme/widgets', undefined, undefined],
['getting-started', '@acme/widgets', 'getting-started', undefined],
['theme-extra', '@acme/widgets', undefined, 'theme'],
@@ -126,7 +130,9 @@ describe('discoverIntegrationDocs', () => {
it('reports a doc that exports nothing, rather than skipping it silently', async () => {
const {records, errors} = await discoverIntegrationDocs(
- integration('@acme/empty', {'deploying.doc.mjs': 'export const nope = 1;\n'}),
+ integration('@acme/empty', {
+ 'deploying.doc.mjs': 'export const nope = 1;\n',
+ }),
);
expect(records).toEqual([]);
expect(errors).toHaveLength(1);
@@ -153,6 +159,29 @@ describe('discoverIntegrationDocs', () => {
expect(records).toEqual([]);
expect(errors[0].message).toContain('declares both');
});
+
+ it('rejects graph blocks at the legacy topic-reader boundary', async () => {
+ const {records, errors} = await discoverIntegrationDocs(
+ integration('@acme/graph-block', {
+ 'deploying.doc.mjs': topic({
+ sections: [
+ {
+ id: 'steps',
+ title: 'Steps',
+ content: [
+ {
+ type: 'workflow',
+ steps: [{title: 'Install', description: 'Run install.'}],
+ },
+ ],
+ },
+ ],
+ }),
+ }),
+ );
+ expect(records).toEqual([]);
+ expect(errors[0].message).toContain('requires the compiled graph renderer');
+ });
});
describe('problemsInTopic', () => {
@@ -170,7 +199,11 @@ describe('problemsInTopic', () => {
// A misspelled required field: the block renders nothing at all.
expect(
problemsInTopic(
- topic({sections: [{title: 'Overview', content: [{type: 'prose', txt: 'oops'}]}]}),
+ topic({
+ sections: [
+ {title: 'Overview', content: [{type: 'prose', txt: 'oops'}]},
+ ],
+ }),
),
).toEqual([
'sections[0].content[0].text: required for a prose block',
@@ -180,7 +213,12 @@ describe('problemsInTopic', () => {
expect(
problemsInTopic(
topic({
- sections: [{title: 'Overview', content: [{type: 'heading', level: 2, text: 'x'}]}],
+ sections: [
+ {
+ title: 'Overview',
+ content: [{type: 'heading', level: 2, text: 'x'}],
+ },
+ ],
}),
),
).toContain('sections[0].content[0].level: 2 is not one of 3, 4, 5, 6');
@@ -196,11 +234,27 @@ describe('problemsInTopic', () => {
],
}),
),
- ).toContain('sections[0].content[0].rows[0]: has 1 cells but the table has 2 headers');
+ ).toContain(
+ 'sections[0].content[0].rows[0]: has 1 cells but the table has 2 headers',
+ );
+ });
+
+ it('rejects graph metadata at the legacy topic-reader boundary', () => {
+ for (const fields of [
+ {placement: {parent: 'namespace:cli'}},
+ {aliases: ['setup']},
+ {audience: 'internal'},
+ ]) {
+ expect(problemsInTopic(topic(fields)).join('\n')).toContain(
+ 'requires the compiled graph reader',
+ );
+ }
});
it('rejects a name that is not URL-safe', () => {
- expect(problemsInTopic(topic({name: 'not a topic'})).join('\n')).toContain('URL-safe');
+ expect(problemsInTopic(topic({name: 'not a topic'})).join('\n')).toContain(
+ 'URL-safe',
+ );
});
});
@@ -228,11 +282,23 @@ describe('DocsCatalog', () => {
expect(catalog.resolve('deploying').package).toBe('@acme/widgets');
});
+ it('treats topic identities case-insensitively without losing display case', () => {
+ const catalog = DocsCatalog.fromBuiltins();
+ expect(catalog.add(record({name: 'Deploying'}))).toBeNull();
+ expect(catalog.resolve('deploying').name).toBe('Deploying');
+ expect(catalog.resolve('DEPLOYING').name).toBe('Deploying');
+
+ const issue = catalog.add(
+ record({name: 'deploying', package: '@acme/duplicate'}),
+ );
+ expect(issue).toMatchObject({code: 'invalid_doc', severity: 'error'});
+ });
+
it('refuses to shadow an existing topic by name alone', () => {
const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
const issue = catalog.add(record({name: 'tokens'}));
expect(issue).toMatchObject({code: 'invalid_doc', severity: 'error'});
- expect(issue.message).toContain("already provided by @astryxdesign/cli");
+ expect(issue.message).toContain('already provided by @astryxdesign/cli');
expect(issue.message).toContain("replaces: 'tokens'");
// The built-in topic is untouched.
expect(catalog.resolve('tokens').package).toBe(BUILTIN_DOCS_PACKAGE);
@@ -244,7 +310,9 @@ describe('DocsCatalog', () => {
tokens: '/cli/tokens.doc.mjs',
});
expect(
- catalog.add(record({name: 'getting-started', replaces: 'getting-started'})),
+ catalog.add(
+ record({name: 'getting-started', replaces: 'getting-started'}),
+ ),
).toBeNull();
expect(catalog.names()).toEqual(['getting-started', 'tokens']);
const entry = catalog.resolve('getting-started');
@@ -276,12 +344,16 @@ describe('DocsCatalog', () => {
it('warns, and lets the later package win, when two replace one topic', () => {
const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
- expect(catalog.add(record({name: 'tokens', replaces: 'tokens'}))).toBeNull();
+ expect(
+ catalog.add(record({name: 'tokens', replaces: 'tokens'})),
+ ).toBeNull();
const issue = catalog.add(
record({name: 'tokens', package: '@acme/later', replaces: 'tokens'}),
);
expect(issue).toMatchObject({code: 'duplicate_doc', severity: 'warning'});
- expect(issue.message).toContain('@acme/later is configured later, so it wins');
+ expect(issue.message).toContain(
+ '@acme/later is configured later, so it wins',
+ );
expect(catalog.resolve('tokens').package).toBe('@acme/later');
});
@@ -327,15 +399,173 @@ describe('mergeTopic', () => {
{title: 'Internal', content: [{type: 'prose', text: 'the meta way'}]},
],
});
- expect(merged.sections.map(s => s.title)).toEqual(['Install', 'Tokens', 'Internal']);
+ expect(merged.sections.map(s => s.title)).toEqual([
+ 'Install',
+ 'Tokens',
+ 'Internal',
+ ]);
expect(merged.sections[0].content[0].text).toBe('yarn add');
expect(merged.sections[1].content[0].text).toBe('use tokens');
// The base is untouched.
expect(base.sections[0].content[0].text).toBe('npm i');
});
+ it('replaces a section by stable ID even when its title changes', () => {
+ const merged = mergeTopic(
+ {
+ ...base,
+ sections: [
+ {id: 'install', title: 'Install', content: []},
+ {id: 'tokens', title: 'Tokens', content: []},
+ ],
+ },
+ {
+ sections: [{id: 'install', title: 'Setup', content: []}],
+ },
+ );
+ expect(merged.sections.map(section => [section.id, section.title])).toEqual(
+ [
+ ['install', 'Setup'],
+ ['tokens', 'Tokens'],
+ ],
+ );
+ });
+
+ it('migrates a legacy section to a stable ID without duplicating it', () => {
+ const merged = mergeTopic(base, {
+ sections: [
+ {
+ id: 'install',
+ title: 'Install',
+ content: [{type: 'prose', text: 'yarn add'}],
+ },
+ ],
+ });
+ expect(
+ merged.sections.map(section => [section.id ?? null, section.title]),
+ ).toEqual([
+ ['install', 'Install'],
+ [null, 'Tokens'],
+ ]);
+ expect(merged.sections[0].content[0].text).toBe('yarn add');
+ });
+
+ it('lets a legacy extension replace a section that has since gained an ID', () => {
+ const merged = mergeTopic(
+ {
+ ...base,
+ sections: [
+ {id: 'setup-steps', title: 'Install', content: []},
+ {title: 'Tokens', content: []},
+ ],
+ },
+ {
+ sections: [
+ {title: 'Install', content: [{type: 'prose', text: 'yarn add'}]},
+ ],
+ },
+ );
+ expect(
+ merged.sections.map(section => [section.id ?? null, section.title]),
+ ).toEqual([
+ ['setup-steps', 'Install'],
+ [null, 'Tokens'],
+ ]);
+ expect(merged.sections[0].content[0].text).toBe('yarn add');
+ });
+
+ it('keeps two different authored IDs distinct under one title', () => {
+ const merged = mergeTopic(
+ {...base, sections: [{id: 'install', title: 'Install', content: []}]},
+ {sections: [{id: 'install-yarn', title: 'Install', content: []}]},
+ );
+ expect(merged.sections.map(section => section.id)).toEqual([
+ 'install',
+ 'install-yarn',
+ ]);
+ });
+
it('takes the title and description only when the overlay states them', () => {
expect(mergeTopic(base, {sections: []}).title).toBe('Theme');
- expect(mergeTopic(base, {title: 'Theming', sections: []}).title).toBe('Theming');
+ expect(mergeTopic(base, {title: 'Theming', sections: []}).title).toBe(
+ 'Theming',
+ );
+ });
+});
+
+describe('problemsInTopic section keys', () => {
+ /** @param {object[]} sections */
+ const doc = sections => ({
+ type: 'generic',
+ name: 'keys',
+ title: 'Keys',
+ description: 'Section keys.',
+ sections: sections.map(s => ({content: [{type: 'prose', text: 'x'}], ...s})),
+ });
+
+ it('rejects two sections that derive the same key', () => {
+ expect(
+ problemsInTopic(doc([{title: 'Quick Start'}, {title: 'Quick-start'}])),
+ ).toEqual([
+ expect.stringContaining('"quick-start" is already used by sections[0]'),
+ ]);
+ });
+
+ it('rejects an unsafe id', () => {
+ expect(problemsInTopic(doc([{id: 'Quick Start', title: 'Quick Start'}]))).toEqual(
+ [expect.stringContaining('is not a stable key')],
+ );
+ });
+
+ it('rejects a title no key derives from, unless it has an id', () => {
+ expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([
+ expect.stringContaining('Give the section an id'),
+ ]);
+ expect(problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}]))).toEqual(
+ [],
+ );
+ });
+});
+
+describe('mergeTopic by section key', () => {
+ const base = {
+ title: 'Theme',
+ sections: [
+ {title: 'Quick Start', content: [{type: 'prose', text: 'base'}]},
+ {title: 'Light/Dark Mode', content: [{type: 'prose', text: 'base'}]},
+ ],
+ };
+ const titles = doc => doc.sections.map(s => [s.id ?? null, s.title, s.content[0].text]);
+
+ it('replaces the section whose derived key an extension id names', () => {
+ const merged = mergeTopic(base, {
+ sections: [
+ {id: 'quick-start', title: 'Quick Start with Acme', content: [{type: 'prose', text: 'acme'}]},
+ ],
+ });
+ expect(titles(merged)).toEqual([
+ ['quick-start', 'Quick Start with Acme', 'acme'],
+ [null, 'Light/Dark Mode', 'base'],
+ ]);
+ });
+
+ it('replaces the section a title variant derives the same key as', () => {
+ const merged = mergeTopic(base, {
+ sections: [{title: 'Light-Dark Mode', content: [{type: 'prose', text: 'acme'}]}],
+ });
+ expect(titles(merged)).toEqual([
+ [null, 'Quick Start', 'base'],
+ [null, 'Light-Dark Mode', 'acme'],
+ ]);
+ });
+
+ it('prefers the key over a legacy title for an extension with an id', () => {
+ const merged = mergeTopic(base, {
+ sections: [{id: 'light-dark-mode', title: 'Quick Start', content: [{type: 'prose', text: 'acme'}]}],
+ });
+ expect(titles(merged)).toEqual([
+ [null, 'Quick Start', 'base'],
+ ['light-dark-mode', 'Quick Start', 'acme'],
+ ]);
});
});
diff --git a/packages/cli/foundation/discovery/docs-output-budget.mjs b/packages/cli/foundation/discovery/docs-output-budget.mjs
new file mode 100644
index 0000000000..dc9f2cfaa9
--- /dev/null
+++ b/packages/cli/foundation/discovery/docs-output-budget.mjs
@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The most one progressive docs read may return.
+ *
+ * @input Docs payloads: one topic's section index, or one section.
+ * @output Their size in bytes as `--json` prints them, and the sections over
+ * the budget.
+ * @position Shared by Doctor's docs checks and the authoring self-doc audit, so
+ * both hold every read to the same limit.
+ */
+
+import {sectionKey} from './docs-section-key.mjs';
+
+/** The most one index or one section read may return, in bytes. */
+export const DOC_OUTPUT_BUDGET_BYTES = 32 * 1024;
+
+/**
+ * A payload's size as `--json` prints it: the envelope data, two-space
+ * indented, in UTF-8 bytes.
+ * @param {unknown} payload
+ * @returns {number}
+ */
+export function docPayloadBytes(payload) {
+ return Buffer.byteLength(JSON.stringify(payload, null, 2), 'utf8');
+}
+
+/**
+ * @param {import('../../api/docs/docs.type.mjs').DocsIndex} index
+ * @returns {number}
+ */
+export function docsIndexBytes(index) {
+ return docPayloadBytes({type: 'docs.index', data: index});
+}
+
+/**
+ * The sections a single read would return more than `budget` bytes for.
+ * @param {any[]} sections
+ * @param {number} [budget]
+ * @returns {{key: string, title: string, bytes: number}[]}
+ */
+export function oversizedDocSections(sections, budget = DOC_OUTPUT_BUDGET_BYTES) {
+ return sections
+ .map(section => ({
+ key: sectionKey(section),
+ title: section.title,
+ bytes: docPayloadBytes({type: 'docs.detail.section', data: section}),
+ }))
+ .filter(entry => entry.bytes > budget);
+}
diff --git a/packages/cli/foundation/discovery/docs-section-key.mjs b/packages/cli/foundation/discovery/docs-section-key.mjs
new file mode 100644
index 0000000000..a802bcf021
--- /dev/null
+++ b/packages/cli/foundation/discovery/docs-section-key.mjs
@@ -0,0 +1,221 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stable section keys, section lookup, and the topic index.
+ *
+ * @input Reference-doc sections, each with an optional authored `id`.
+ * @output The key a section is addressed by (its `id`, else a kebab-case key
+ * derived from its authored title), lookup by key or title, and the compact
+ * index a topic-only docs read returns.
+ * @position Shared by docs discovery (which rejects colliding keys before a
+ * reader sees them), the docs leaves (index, section, detail), and Doctor
+ * (output budgets). Imports nothing from discovery, so both can use it.
+ */
+
+/** A stable key: lowercase letters and digits, joined by single hyphens. */
+export const SECTION_KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The longest summary an index entry carries, in characters. */
+export const SECTION_SUMMARY_MAX = 240;
+
+/**
+ * A section's authored title. A `--zh`/`--dense` overlay replaces the visible
+ * title, but extensions are written against the authored one and keys derive
+ * from it, so both stay the same in every language.
+ */
+const SOURCE_TITLE = Symbol('astryx.docs.sourceTitle');
+
+/**
+ * Record the authored title of a section whose visible title a translation
+ * overlay replaces.
+ * @template {object} T
+ * @param {T} section
+ * @param {string} title
+ * @returns {T}
+ */
+export function withSourceTitle(section, title) {
+ Object.defineProperty(section, SOURCE_TITLE, {value: title, configurable: true});
+ return section;
+}
+
+/**
+ * @param {any} section
+ * @returns {string}
+ */
+export function sourceTitle(section) {
+ return section?.[SOURCE_TITLE] ?? section?.title;
+}
+
+/**
+ * The key a title derives: accents folded, `&` spelled out, and every other
+ * run of non-alphanumerics collapsed to one hyphen. Empty when the title has
+ * no Latin letters or digits to derive from.
+ * @param {unknown} title
+ * @returns {string}
+ */
+export function sectionTitleKey(title) {
+ if (typeof title !== 'string') return '';
+ return title
+ .normalize('NFKD')
+ .replace(/[\u0300-\u036f]/g, '')
+ .toLowerCase()
+ .replace(/&/g, ' and ')
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * The key a section is addressed by: its authored `id`, else the key its
+ * authored title derives.
+ * @param {any} section
+ * @returns {string}
+ */
+export function sectionKey(section) {
+ return typeof section?.id === 'string'
+ ? section.id
+ : sectionTitleKey(sourceTitle(section));
+}
+
+/**
+ * Problems with the keys of a topic's sections: an authored id that is not a
+ * stable key, a title no key derives from, and two sections sharing a key.
+ * Keys are never suffixed to make them unique, because readers link to them.
+ * @param {any[]} sections
+ * @returns {string[]}
+ */
+export function sectionKeyProblems(sections) {
+ /** @type {string[]} */
+ const problems = [];
+ /** @type {Map<string, number>} */
+ const seen = new Map();
+ sections.forEach((section, s) => {
+ const at = `sections[${s}]`;
+ // A missing title is reported where titles are checked; no key to judge.
+ if (
+ section?.id == null &&
+ (typeof section?.title !== 'string' || section.title === '')
+ ) {
+ return;
+ }
+ if (
+ section?.id != null &&
+ (typeof section.id !== 'string' || !SECTION_KEY_RE.test(section.id))
+ ) {
+ problems.push(
+ `${at}.id: ${JSON.stringify(section.id)} is not a stable key. Use lowercase letters and digits joined by single hyphens.`,
+ );
+ return;
+ }
+ const key = sectionKey(section);
+ if (key === '') {
+ problems.push(
+ `${at}: no key derives from the title ${JSON.stringify(section?.title)}. Give the section an id.`,
+ );
+ return;
+ }
+ const first = seen.get(key);
+ if (first != null) {
+ problems.push(
+ `${at}: the key "${key}" is already used by sections[${first}]. Give one of them a distinct id or title.`,
+ );
+ return;
+ }
+ seen.set(key, s);
+ });
+ return problems;
+}
+
+/**
+ * Stamp every section with the key it is addressed by. Runs only after
+ * extensions merge: a derived key must never take part in merge matching.
+ * @template {{sections: any[]}} T
+ * @param {T} doc
+ * @returns {T}
+ */
+export function withSectionKeys(doc) {
+ return {
+ ...doc,
+ sections: doc.sections.map(section =>
+ section.id != null
+ ? section
+ : withSourceTitle(
+ {...section, id: sectionKey(section)},
+ sourceTitle(section),
+ ),
+ ),
+ };
+}
+
+/**
+ * Find the section a reader asked for: by key, then by exact title (or the
+ * key the query derives), then by a title that contains the query. More than
+ * one match is refused rather than guessed.
+ * @param {any[]} sections
+ * @param {string} query
+ * @returns {{section: any | null, candidates: any[]}} `candidates` lists the
+ * matches when the query is ambiguous, and is empty when nothing matches
+ */
+export function findDocSection(sections, query) {
+ const wanted = query.trim();
+ const byKey = sections.find(section => sectionKey(section) === wanted);
+ if (byKey) return {section: byKey, candidates: []};
+
+ const lower = wanted.toLowerCase();
+ const derived = sectionTitleKey(wanted);
+ const exact = sections.filter(
+ section =>
+ section.title.toLowerCase() === lower ||
+ (derived !== '' && sectionTitleKey(sourceTitle(section)) === derived),
+ );
+ if (exact.length === 1) return {section: exact[0], candidates: []};
+ if (exact.length > 1) return {section: null, candidates: exact};
+
+ const partial = sections.filter(section =>
+ section.title.toLowerCase().includes(lower),
+ );
+ if (partial.length === 1) return {section: partial[0], candidates: []};
+ return {section: null, candidates: partial};
+}
+
+/**
+ * One line that says what a section holds: its first prose or list text,
+ * whitespace collapsed, cut at a word boundary.
+ * @param {any} section
+ * @param {number} [max]
+ * @returns {string}
+ */
+export function sectionSummary(section, max = SECTION_SUMMARY_MAX) {
+ const first = (section?.content ?? []).find(
+ (/** @type {any} */ block) =>
+ (block?.type === 'prose' && typeof block.text === 'string') ||
+ (block?.type === 'list' && Array.isArray(block.items)),
+ );
+ const raw =
+ first == null ? '' : first.type === 'prose' ? first.text : first.items[0];
+ const text = String(raw ?? '')
+ .replace(/\s+/g, ' ')
+ .trim();
+ if (text.length <= max) return text;
+ const cut = text.slice(0, max - 1);
+ const space = cut.lastIndexOf(' ');
+ return `${(space > max / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
+/**
+ * The index a topic-only read returns: what the topic is, and one entry per
+ * section with the key to read it by.
+ * @param {{name: string, title: string, description: string, sections: any[]}} doc
+ * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ */
+export function buildDocsIndexData(doc) {
+ return {
+ name: doc.name,
+ title: doc.title,
+ description: doc.description,
+ sections: doc.sections.map(section => ({
+ id: sectionKey(section),
+ title: section.title,
+ summary: sectionSummary(section),
+ })),
+ };
+}
diff --git a/packages/cli/foundation/discovery/docs-section-key.test.mjs b/packages/cli/foundation/discovery/docs-section-key.test.mjs
new file mode 100644
index 0000000000..543c938cf8
--- /dev/null
+++ b/packages/cli/foundation/discovery/docs-section-key.test.mjs
@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+ SECTION_KEY_RE,
+ SECTION_SUMMARY_MAX,
+ buildDocsIndexData,
+ findDocSection,
+ sectionKey,
+ sectionKeyProblems,
+ sectionSummary,
+ sectionTitleKey,
+ sourceTitle,
+ withSectionKeys,
+ withSourceTitle,
+} from './docs-section-key.mjs';
+
+/** @param {string} title @param {object} [fields] */
+const section = (title, fields = {}) => ({title, content: [], ...fields});
+
+describe('sectionTitleKey', () => {
+ it.each([
+ ['Quick Start', 'quick-start'],
+ ['Light/Dark Mode', 'light-dark-mode'],
+ ["Do & Don't", 'do-and-don-t'],
+ [' Café Crème ', 'cafe-creme'],
+ ['useTheme()', 'usetheme'],
+ ['--- Tokens ---', 'tokens'],
+ ['亮/暗模式', ''],
+ ['', ''],
+ ])('%j derives %j', (title, key) => {
+ expect(sectionTitleKey(title)).toBe(key);
+ });
+
+ it('derives only stable keys', () => {
+ for (const title of ['A B', 'x__y', 'Élan 2.0', 'a-b-', '-a']) {
+ expect(sectionTitleKey(title)).toMatch(SECTION_KEY_RE);
+ }
+ });
+
+ it('derives nothing from a non-string', () => {
+ expect(sectionTitleKey(undefined)).toBe('');
+ expect(sectionTitleKey(42)).toBe('');
+ });
+});
+
+describe('sectionKey', () => {
+ it('prefers the authored id', () => {
+ expect(sectionKey(section('Quick Start', {id: 'start'}))).toBe('start');
+ });
+
+ it('derives from the authored title, not a translated one', () => {
+ const translated = withSourceTitle(section('快速开始'), 'Quick Start');
+ expect(sectionKey(translated)).toBe('quick-start');
+ });
+});
+
+describe('sectionKeyProblems', () => {
+ it('accepts distinct keys', () => {
+ expect(
+ sectionKeyProblems([section('Install'), section('Usage', {id: 'use'})]),
+ ).toEqual([]);
+ });
+
+ it('rejects two sections that share a key', () => {
+ const problems = sectionKeyProblems([
+ section('Quick Start'),
+ section('Quick-start'),
+ ]);
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toContain('"quick-start" is already used by sections[0]');
+ });
+
+ it('rejects an authored id that collides with a derived key', () => {
+ expect(
+ sectionKeyProblems([section('Install'), section('Setup', {id: 'install'})]),
+ ).toHaveLength(1);
+ });
+
+ it('rejects an unsafe id and never suffixes one', () => {
+ for (const id of ['Quick Start', 'a_b', 'a--b', '-a', '', 7]) {
+ expect(sectionKeyProblems([section('Install', {id})])[0]).toContain(
+ 'is not a stable key',
+ );
+ }
+ });
+
+ it('rejects a title no key derives from', () => {
+ expect(sectionKeyProblems([section('亮/暗模式')])[0]).toContain(
+ 'Give the section an id',
+ );
+ expect(sectionKeyProblems([section('亮/暗模式', {id: 'light-dark'})])).toEqual(
+ [],
+ );
+ });
+
+ it('leaves a missing title to the title check', () => {
+ expect(sectionKeyProblems([{content: []}, section('')])).toEqual([]);
+ });
+});
+
+describe('withSectionKeys', () => {
+ it('stamps derived keys and keeps authored ones', () => {
+ const doc = withSectionKeys({
+ sections: [section('Quick Start'), section('Usage', {id: 'use'})],
+ });
+ expect(doc.sections.map(s => s.id)).toEqual(['quick-start', 'use']);
+ });
+
+ it('keeps the authored title of a translated section', () => {
+ const doc = withSectionKeys({
+ sections: [withSourceTitle(section('快速开始'), 'Quick Start')],
+ });
+ expect(doc.sections[0].id).toBe('quick-start');
+ expect(sourceTitle(doc.sections[0])).toBe('Quick Start');
+ });
+});
+
+describe('findDocSection', () => {
+ const sections = withSectionKeys({
+ sections: [
+ section('Quick Start'),
+ section('Theme Props'),
+ section('Theme Tokens', {id: 'tokens'}),
+ section('Overview', {id: 'overview-a'}),
+ section('Overview', {id: 'overview-b'}),
+ ],
+ }).sections;
+
+ it('finds a section by key first', () => {
+ expect(findDocSection(sections, 'tokens').section.title).toBe(
+ 'Theme Tokens',
+ );
+ });
+
+ it('finds a section by exact title, case-insensitively', () => {
+ expect(findDocSection(sections, 'quick start').section.id).toBe(
+ 'quick-start',
+ );
+ });
+
+ it('finds a section by the key its query derives', () => {
+ expect(findDocSection(sections, 'Quick-Start!').section.id).toBe(
+ 'quick-start',
+ );
+ });
+
+ it('finds a section by a unique part of its title', () => {
+ expect(findDocSection(sections, 'props').section.id).toBe('theme-props');
+ });
+
+ it('refuses an ambiguous exact title and lists the candidates', () => {
+ const {section: match, candidates} = findDocSection(sections, 'Overview');
+ expect(match).toBeNull();
+ expect(candidates.map(s => s.id)).toEqual(['overview-a', 'overview-b']);
+ });
+
+ it('refuses an ambiguous partial title', () => {
+ const {section: match, candidates} = findDocSection(sections, 'theme');
+ expect(match).toBeNull();
+ expect(candidates.map(s => s.id)).toEqual(['theme-props', 'tokens']);
+ });
+
+ it('returns nothing for no match', () => {
+ expect(findDocSection(sections, 'zzz')).toEqual({
+ section: null,
+ candidates: [],
+ });
+ });
+});
+
+describe('sectionSummary', () => {
+ it('uses the first prose or list text, whitespace collapsed', () => {
+ expect(
+ sectionSummary({
+ content: [
+ {type: 'code', lang: 'ts', code: 'x'},
+ {type: 'prose', text: 'Line one.\n\n Line two.'},
+ ],
+ }),
+ ).toBe('Line one. Line two.');
+ expect(
+ sectionSummary({content: [{type: 'list', items: ['First', 'Second']}]}),
+ ).toBe('First');
+ });
+
+ it('is empty when the section has no text', () => {
+ expect(sectionSummary({content: [{type: 'table', headers: [], rows: []}]})).toBe(
+ '',
+ );
+ });
+
+ it('cuts a long summary at a word boundary', () => {
+ const summary = sectionSummary({
+ content: [{type: 'prose', text: 'word '.repeat(200)}],
+ });
+ expect(summary.length).toBeLessThanOrEqual(SECTION_SUMMARY_MAX);
+ expect(summary.endsWith('word…')).toBe(true);
+ });
+});
+
+describe('buildDocsIndexData', () => {
+ it('lists each section by key, title, and summary', () => {
+ expect(
+ buildDocsIndexData({
+ name: 'theme',
+ title: 'Theme',
+ description: 'Theming.',
+ sections: [
+ section('Quick Start', {content: [{type: 'prose', text: 'Start.'}]}),
+ section('Usage', {id: 'use'}),
+ ],
+ }),
+ ).toEqual({
+ name: 'theme',
+ title: 'Theme',
+ description: 'Theming.',
+ sections: [
+ {id: 'quick-start', title: 'Quick Start', summary: 'Start.'},
+ {id: 'use', title: 'Usage', summary: ''},
+ ],
+ });
+ });
+});
diff --git a/packages/cli/foundation/discovery/template-adapter.mjs b/packages/cli/foundation/discovery/template-adapter.mjs
index 43434db2db..dca88b84cb 100644
--- a/packages/cli/foundation/discovery/template-adapter.mjs
+++ b/packages/cli/foundation/discovery/template-adapter.mjs
@@ -27,10 +27,11 @@ import {createJiti} from 'jiti';
import {loadModuleWithParser} from '../fs/module-loader.mjs';
import {parseTemplate} from '../../authoring/doctypes/template/parse.mjs';
import {CLI_ROOT, discoverExternalPackages} from '../fs/paths.mjs';
+import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
import {Project} from '../config/project.mjs';
/** Identity used for core (built-in) templates in package-scoped listings. */
-const CORE_PACKAGE = '@astryxdesign/core';
+const CORE_PACKAGE = CORE_PROVIDER_ID;
/**
* Identity for a template in package-scoped views. Core (built-in) templates
diff --git a/packages/cli/foundation/identity/provider-identity.mjs b/packages/cli/foundation/identity/provider-identity.mjs
new file mode 100644
index 0000000000..2ec142764f
--- /dev/null
+++ b/packages/cli/foundation/identity/provider-identity.mjs
@@ -0,0 +1,320 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Canonical provider, artifact, and immutable-instance identity helpers.
+ *
+ * IDs use versioned, RFC 3986-escaped path segments. Provider package names are
+ * case-insensitive and normalize to lowercase. Artifact names preserve case and
+ * normalize Unicode to NFC.
+ */
+
+/** @typedef {import('../../authoring/identity/type').ArtifactId} ArtifactId */
+/** @typedef {import('../../authoring/identity/type').ArtifactIdentity} ArtifactIdentity */
+/** @typedef {import('../../authoring/identity/type').AuthoredDoc} AuthoredDoc */
+/** @typedef {import('../../authoring/identity/type').AuthoredDocEntry} AuthoredDocEntry */
+/** @typedef {import('../../authoring/doctypes/base/type').AuthoredDocKind} AuthoredDocKind */
+/** @typedef {import('../../authoring/identity/type').ContentDigest} ContentDigest */
+/** @typedef {import('../../authoring/identity/type').ContributionKind} ContributionKind */
+/** @typedef {import('../../authoring/identity/type').DocId} DocId */
+/** @typedef {import('../../authoring/identity/type').ProviderId} ProviderId */
+/** @typedef {import('../../authoring/identity/type').ProviderInstance} ProviderInstance */
+/** @typedef {import('../../authoring/identity/type').ProviderInstanceId} ProviderInstanceId */
+
+const ARTIFACT_PREFIX = 'astryx:artifact:v1/';
+const PROVIDER_INSTANCE_PREFIX = 'astryx:provider-instance:v1/';
+const PACKAGE_NAME_RE =
+ /^(?:@[a-z0-9][a-z0-9._~!*'()-]*\/)?[a-z0-9][a-z0-9._~!*'()-]*$/u;
+const SHA256_RE = /^sha256:[0-9a-f]{64}$/u;
+
+/** @type {ReadonlySet<ContributionKind>} */
+const CONTRIBUTION_KINDS = new Set([
+ 'component',
+ 'function',
+ 'generic',
+ 'page',
+ 'block',
+ 'schema',
+ 'command',
+ 'enum',
+ 'namespace',
+ 'theme',
+ 'codemod',
+ 'agent-doc',
+]);
+
+/** @type {ReadonlySet<AuthoredDocKind>} */
+const DOC_KINDS = new Set([
+ 'component',
+ 'function',
+ 'generic',
+ 'page',
+ 'block',
+ 'schema',
+ 'command',
+ 'enum',
+ 'namespace',
+]);
+
+/** RFC 3986 path-segment encoding with uppercase escapes. */
+/** @param {string} value @returns {string} */
+function encodeSegment(value) {
+ return encodeURIComponent(value).replace(
+ /[!'()*]/gu,
+ character => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+ );
+}
+
+/** Decode one identity segment or throw a stable, readable error. */
+/** @param {string} value @param {string} label @returns {string} */
+function decodeSegment(value, label) {
+ try {
+ return decodeURIComponent(value);
+ } catch {
+ throw new Error(`${label} contains invalid percent escaping.`);
+ }
+}
+
+/** Normalize a required identity string without changing meaningful case. */
+/** @param {unknown} value @param {string} label @returns {string} */
+function normalizeName(value, label) {
+ if (typeof value !== 'string' || value.trim() === '') {
+ throw new Error(`${label} must be a non-empty string.`);
+ }
+ return value.trim().normalize('NFC');
+}
+
+/**
+ * Normalize an npm package name into a ProviderId.
+ * @param {string} packageName
+ * @returns {ProviderId}
+ */
+export function normalizeProviderId(packageName) {
+ const normalized = normalizeName(packageName, 'Provider ID').toLowerCase();
+ if (!PACKAGE_NAME_RE.test(normalized)) {
+ throw new Error(
+ `Provider ID "${packageName}" must be a bare npm package name.`,
+ );
+ }
+ return /** @type {ProviderId} */ (normalized);
+}
+
+/**
+ * Normalize a SHA-256 digest.
+ * @param {string} digest
+ * @returns {ContentDigest}
+ */
+export function normalizeContentDigest(digest) {
+ const normalized = normalizeName(digest, 'Content digest').toLowerCase();
+ if (!SHA256_RE.test(normalized)) {
+ throw new Error(
+ 'Content digest must use sha256:<64 lowercase hex characters>.',
+ );
+ }
+ return /** @type {ContentDigest} */ (normalized);
+}
+
+/**
+ * Build a stable provider + contribution kind + artifact-name ID.
+ * @param {string} provider
+ * @param {ContributionKind} kind
+ * @param {string} name
+ * @returns {ArtifactId}
+ */
+export function createArtifactId(provider, kind, name) {
+ const providerId = normalizeProviderId(provider);
+ if (!CONTRIBUTION_KINDS.has(kind)) {
+ throw new Error(`Unknown contribution kind "${String(kind)}".`);
+ }
+ const stableName = normalizeName(name, 'Artifact name');
+ return /** @type {ArtifactId} */ (
+ `${ARTIFACT_PREFIX}${encodeSegment(providerId)}/${kind}/${encodeSegment(stableName)}`
+ );
+}
+
+/**
+ * Build a stable document ID from provider + authored kind + stable name.
+ * @param {string} provider
+ * @param {AuthoredDocKind} kind
+ * @param {string} name
+ * @returns {DocId}
+ */
+export function createDocId(provider, kind, name) {
+ if (!DOC_KINDS.has(kind)) {
+ throw new Error(`Unknown authored doc kind "${String(kind)}".`);
+ }
+ return /** @type {DocId} */ (createArtifactId(provider, kind, name));
+}
+
+/**
+ * Build a normalized logical artifact record.
+ * @param {string} provider
+ * @param {ContributionKind} kind
+ * @param {string} name
+ * @returns {ArtifactIdentity}
+ */
+export function createArtifactIdentity(provider, kind, name) {
+ const providerId = normalizeProviderId(provider);
+ const stableName = normalizeName(name, 'Artifact name');
+ return Object.freeze({
+ id: createArtifactId(providerId, kind, stableName),
+ providerId,
+ kind,
+ name: stableName,
+ });
+}
+
+/**
+ * Parse and canonicalize an ArtifactId.
+ * @param {string} value
+ * @returns {ArtifactIdentity}
+ */
+export function parseArtifactId(value) {
+ if (typeof value !== 'string' || !value.startsWith(ARTIFACT_PREFIX)) {
+ throw new Error(`Artifact ID must start with "${ARTIFACT_PREFIX}".`);
+ }
+ const segments = value.slice(ARTIFACT_PREFIX.length).split('/');
+ if (segments.length !== 3) {
+ throw new Error(
+ 'Artifact ID must contain provider, kind, and name segments.',
+ );
+ }
+ const provider = decodeSegment(segments[0], 'Artifact provider');
+ const kind = decodeSegment(segments[1], 'Artifact kind');
+ const name = decodeSegment(segments[2], 'Artifact name');
+ if (!CONTRIBUTION_KINDS.has(/** @type {ContributionKind} */ (kind))) {
+ throw new Error(`Unknown contribution kind "${kind}".`);
+ }
+ const identity = createArtifactIdentity(
+ provider,
+ /** @type {ContributionKind} */ (kind),
+ name,
+ );
+ if (identity.id !== value) {
+ throw new Error('Artifact ID is not in canonical serialized form.');
+ }
+ return identity;
+}
+
+/**
+ * Build one immutable provider instance.
+ * @param {{providerId: string, packageName: string, packageVersion: string, sourceDigest: string}} input
+ * @returns {ProviderInstance}
+ */
+export function createProviderInstance(input) {
+ const providerId = normalizeProviderId(input.providerId);
+ const packageName = normalizeProviderId(input.packageName);
+ const packageVersion = normalizeName(input.packageVersion, 'Package version');
+ const sourceDigest = normalizeContentDigest(input.sourceDigest);
+ const id = /** @type {ProviderInstanceId} */ (
+ `${PROVIDER_INSTANCE_PREFIX}${encodeSegment(providerId)}/${encodeSegment(packageName)}/${encodeSegment(packageVersion)}/${encodeSegment(sourceDigest)}`
+ );
+ return Object.freeze({
+ id,
+ providerId,
+ packageName,
+ packageVersion,
+ sourceDigest,
+ });
+}
+
+/** Normalize a package-relative source path to forward slashes. */
+/** @param {unknown} value @returns {string} */
+function normalizeSourcePath(value) {
+ const normalized = normalizeName(value, 'Source path').replaceAll('\\', '/');
+ const segments = normalized.split('/');
+ if (
+ normalized.startsWith('/') ||
+ /^[A-Za-z]:\//u.test(normalized) ||
+ segments.some(
+ segment => segment === '' || segment === '.' || segment === '..',
+ )
+ ) {
+ throw new Error('Source path must be a normalized package-relative path.');
+ }
+ return normalized;
+}
+
+/** Infer an unstamped legacy document's kind from its required shape. */
+/** @param {AuthoredDoc} authored @returns {AuthoredDocKind} */
+function authoredKindOf(authored) {
+ if (authored.type != null) return authored.type;
+ if ('params' in authored && 'returns' in authored) return 'function';
+ if (
+ 'props' in authored ||
+ 'components' in authored ||
+ 'subComponentOf' in authored
+ ) {
+ return 'component';
+ }
+ if ('sections' in authored && 'title' in authored) return 'generic';
+ throw new Error('Cannot infer the kind of an unstamped authored document.');
+}
+
+/** Clone and recursively freeze plain authored data. */
+/** @template T @param {T} value @returns {T} */
+function frozenClone(value) {
+ const clone = structuredClone(value);
+ const seen = new WeakSet();
+ /** @param {unknown} current */
+ const freeze = current => {
+ if (
+ current == null ||
+ typeof current !== 'object' ||
+ Object.isFrozen(current) ||
+ seen.has(current)
+ ) {
+ return;
+ }
+ seen.add(current);
+ for (const nested of Object.values(current)) freeze(nested);
+ Object.freeze(current);
+ };
+ freeze(clone);
+ return clone;
+}
+
+/**
+ * Bind one validated authored document to immutable provider and source
+ * provenance. Runtime lifecycle state is intentionally absent.
+ * @param {{
+ * provider: ProviderInstance,
+ * kind: AuthoredDocKind,
+ * stableName: string,
+ * source: {group: string, path: string, digest: string},
+ * authored: AuthoredDoc,
+ * }} input
+ * @returns {AuthoredDocEntry}
+ */
+export function createAuthoredDocEntry(input) {
+ const stableName = normalizeName(input.stableName, 'Stable document name');
+ const group = normalizeName(input.source.group, 'Source group');
+ const sourcePath = normalizeSourcePath(input.source.path);
+ const digest = normalizeContentDigest(input.source.digest);
+ const authoredKind = authoredKindOf(input.authored);
+ if (authoredKind !== input.kind) {
+ throw new Error(
+ `Document kind "${input.kind}" does not match authored type "${authoredKind}".`,
+ );
+ }
+
+ const provider = createProviderInstance({
+ providerId: input.provider.providerId,
+ packageName: input.provider.packageName,
+ packageVersion: input.provider.packageVersion,
+ sourceDigest: input.provider.sourceDigest,
+ });
+ if (provider.id !== input.provider.id) {
+ throw new Error(
+ 'Provider instance ID does not match its immutable fields.',
+ );
+ }
+
+ return Object.freeze({
+ id: createDocId(provider.providerId, input.kind, stableName),
+ provider,
+ kind: input.kind,
+ stableName,
+ source: Object.freeze({group, path: sourcePath, digest}),
+ authored: frozenClone(input.authored),
+ });
+}
diff --git a/packages/cli/foundation/identity/provider-identity.test.mjs b/packages/cli/foundation/identity/provider-identity.test.mjs
new file mode 100644
index 0000000000..6ef25b57cd
--- /dev/null
+++ b/packages/cli/foundation/identity/provider-identity.test.mjs
@@ -0,0 +1,254 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+ createArtifactId,
+ createArtifactIdentity,
+ createAuthoredDocEntry,
+ createDocId,
+ createProviderInstance,
+ normalizeContentDigest,
+ normalizeProviderId,
+ parseArtifactId,
+} from './provider-identity.mjs';
+import {CLI_PROVIDER_ID, CORE_PROVIDER_ID} from './providers.mjs';
+
+const DIGEST_A = `sha256:${'a'.repeat(64)}`;
+const DIGEST_B = `sha256:${'b'.repeat(64)}`;
+
+describe('provider identity', () => {
+ it('uses the same canonical model for built-in providers', () => {
+ expect(CORE_PROVIDER_ID).toBe('@astryxdesign/core');
+ expect(CLI_PROVIDER_ID).toBe('@astryxdesign/cli');
+ });
+
+ it('normalizes npm package identity once', () => {
+ expect(normalizeProviderId(' @AstryxDesign/CLI ')).toBe(
+ '@astryxdesign/cli',
+ );
+ expect(() => normalizeProviderId('../cli')).toThrow(
+ /bare npm package name/u,
+ );
+ });
+
+ it('normalizes content digests', () => {
+ expect(normalizeContentDigest(DIGEST_A.toUpperCase())).toBe(DIGEST_A);
+ expect(() => normalizeContentDigest('sha256:nope')).toThrow(/sha256/u);
+ });
+
+ it('keeps provider, kind, and case-sensitive artifact name in the ID', () => {
+ const component = createArtifactId('@acme/ui', 'component', 'Button');
+ expect(component).not.toBe(
+ createArtifactId('@acme/ui', 'component', 'button'),
+ );
+ expect(component).not.toBe(
+ createArtifactId('@acme/ui', 'schema', 'Button'),
+ );
+ expect(component).not.toBe(
+ createArtifactId('@other/ui', 'component', 'Button'),
+ );
+ });
+
+ it('escapes segments canonically and round-trips without collisions', () => {
+ const identity = createArtifactIdentity(
+ '@acme/ui',
+ 'generic',
+ 'Deploy / 100%',
+ );
+ expect(identity.id).toContain('Deploy%20%2F%20100%25');
+ expect(parseArtifactId(identity.id)).toEqual(identity);
+ expect(() => parseArtifactId(identity.id.replace('%2F', '%2f'))).toThrow(
+ /canonical/u,
+ );
+ });
+
+ it('uses the same stable ID across immutable provider instances', () => {
+ const docId = createDocId('@acme/ui', 'schema', 'integration');
+ const first = createProviderInstance({
+ providerId: '@acme/ui',
+ packageName: '@acme/ui',
+ packageVersion: '1.0.0',
+ sourceDigest: DIGEST_A,
+ });
+ const second = createProviderInstance({
+ providerId: '@acme/ui',
+ packageName: '@acme/ui',
+ packageVersion: '1.0.1',
+ sourceDigest: DIGEST_B,
+ });
+ expect(first.id).not.toBe(second.id);
+ expect(createDocId(first.providerId, 'schema', 'integration')).toBe(docId);
+ expect(createDocId(second.providerId, 'schema', 'integration')).toBe(docId);
+ });
+
+ it('supports an explicit stable provider ID across a package rename', () => {
+ const instance = createProviderInstance({
+ providerId: '@acme/ui',
+ packageName: '@acme/design-system',
+ packageVersion: '2.0.0',
+ sourceDigest: DIGEST_A,
+ });
+ expect(instance.providerId).toBe('@acme/ui');
+ expect(instance.packageName).toBe('@acme/design-system');
+ });
+
+ it('binds a doc to stable identity and immutable source provenance', () => {
+ const provider = createProviderInstance({
+ providerId: '@acme/ui',
+ packageName: '@acme/ui',
+ packageVersion: '1.0.0',
+ sourceDigest: DIGEST_A,
+ });
+ const authored = {
+ type: 'schema',
+ name: 'integration',
+ displayName: 'Integration',
+ description: 'The integration manifest.',
+ fields: [],
+ };
+
+ const entry = createAuthoredDocEntry({
+ provider,
+ kind: 'schema',
+ stableName: 'integration',
+ source: {
+ group: 'cli-api',
+ path: 'authoring/integration/integration.doc.mjs',
+ digest: DIGEST_B,
+ },
+ authored,
+ });
+
+ expect(entry.id).toBe(createDocId('@acme/ui', 'schema', 'integration'));
+ expect(entry.provider).toEqual(provider);
+ expect(entry.stableName).toBe('integration');
+ expect(entry.source.digest).toBe(DIGEST_B);
+ expect(Object.isFrozen(entry)).toBe(true);
+ expect(Object.isFrozen(entry.provider)).toBe(true);
+ expect(Object.isFrozen(entry.source)).toBe(true);
+ expect(Object.isFrozen(entry.authored)).toBe(true);
+
+ authored.name = 'mutated';
+ expect(entry.authored.name).toBe('integration');
+ });
+
+ it('uses a discovery-owned stable name when authored display names collide', () => {
+ const provider = createProviderInstance({
+ providerId: '@astryxdesign/core',
+ packageName: '@astryxdesign/core',
+ packageVersion: '1.0.0',
+ sourceDigest: DIGEST_A,
+ });
+ const authored = {
+ type: 'block',
+ name: 'Banner — Statuses',
+ description: 'A template.',
+ };
+ const makeEntry = stableName =>
+ createAuthoredDocEntry({
+ provider,
+ kind: 'block',
+ stableName,
+ source: {
+ group: 'templates',
+ path: `templates/${stableName}.doc.mjs`,
+ digest: DIGEST_B,
+ },
+ authored,
+ });
+
+ expect(makeEntry('BannerShowcase').id).not.toBe(
+ makeEntry('BannerStatuses').id,
+ );
+ });
+
+ it('correlates an unstamped legacy reference doc with generic identity', () => {
+ const provider = createProviderInstance({
+ providerId: '@acme/ui',
+ packageName: '@acme/ui',
+ packageVersion: '1.0.0',
+ sourceDigest: DIGEST_A,
+ });
+ const entry = createAuthoredDocEntry({
+ provider,
+ kind: 'generic',
+ stableName: 'theming',
+ source: {group: 'guides', path: 'docs/theming.doc.mjs', digest: DIGEST_B},
+ authored: {
+ name: 'theming',
+ title: 'Theming',
+ description: 'How theming works.',
+ sections: [],
+ },
+ });
+ expect(entry.kind).toBe('generic');
+ });
+
+ it('rejects doc-entry identity that disagrees with stamped or legacy content', () => {
+ const provider = createProviderInstance({
+ providerId: '@acme/ui',
+ packageName: '@acme/ui',
+ packageVersion: '1.0.0',
+ sourceDigest: DIGEST_A,
+ });
+ const source = {
+ group: 'cli-api',
+ path: 'integration.doc.mjs',
+ digest: DIGEST_B,
+ };
+
+ expect(() =>
+ createAuthoredDocEntry({
+ provider,
+ kind: 'command',
+ stableName: 'integration',
+ source,
+ authored: {
+ type: 'schema',
+ name: 'integration',
+ displayName: 'Integration',
+ description: 'The integration manifest.',
+ fields: [],
+ },
+ }),
+ ).toThrow(/does not match authored type/u);
+
+ expect(() =>
+ createAuthoredDocEntry({
+ provider,
+ kind: 'enum',
+ stableName: 'Button',
+ source,
+ authored: {name: 'Button', props: []},
+ }),
+ ).toThrow(/does not match authored type "component"/u);
+ });
+
+ it('rejects source paths that escape the provider package', () => {
+ const provider = createProviderInstance({
+ providerId: '@acme/ui',
+ packageName: '@acme/ui',
+ packageVersion: '1.0.0',
+ sourceDigest: DIGEST_A,
+ });
+ expect(() =>
+ createAuthoredDocEntry({
+ provider,
+ kind: 'schema',
+ stableName: 'integration',
+ source: {
+ group: 'cli-api',
+ path: '../outside.doc.mjs',
+ digest: DIGEST_B,
+ },
+ authored: {
+ type: 'schema',
+ name: 'integration',
+ displayName: 'Integration',
+ description: 'The integration manifest.',
+ fields: [],
+ },
+ }),
+ ).toThrow(/package-relative path/u);
+ });
+});
diff --git a/packages/cli/foundation/identity/providers.mjs b/packages/cli/foundation/identity/providers.mjs
new file mode 100644
index 0000000000..cb9b94b922
--- /dev/null
+++ b/packages/cli/foundation/identity/providers.mjs
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Canonical identities for Astryx's built-in providers.
+ * @input Stable npm package names owned by Astryx.
+ * @output Branded ProviderId values shared by discovery and compilation.
+ * @position foundation/identity — built-in provider identity boundary.
+ */
+
+import {normalizeProviderId} from './provider-identity.mjs';
+
+/** Core owns built-in components and templates. */
+export const CORE_PROVIDER_ID = normalizeProviderId('@astryxdesign/core');
+
+/** The CLI owns built-in topic docs and CLI-authored contributions. */
+export const CLI_PROVIDER_ID = normalizeProviderId('@astryxdesign/cli');
diff --git a/packages/cli/foundation/integrations/autolink.mjs b/packages/cli/foundation/integrations/autolink.mjs
index cd81a722cb..6246e7d228 100644
--- a/packages/cli/foundation/integrations/autolink.mjs
+++ b/packages/cli/foundation/integrations/autolink.mjs
@@ -234,7 +234,13 @@ export async function autolinkIntegrations({
/** @type {import('./integrations.mjs').LoadedIntegration[]} */
const autolinked = [];
- const names = new Set(loaded.map(integration => integration.name));
+ // One package reached twice (an alias beside the package it aliases, at the
+ // same version) loads once. The same name at another version is kept, so the
+ // provider-identity pass in Project.load reports it instead of dropping it.
+ /** @param {{name: string, version?: string}} integration */
+ const identity = integration =>
+ `${integration.name}\u0000${integration.version ?? ''}`;
+ const seen = new Set(loaded.map(identity));
for (const candidate of candidates) {
/** @type {import('./integrations.mjs').LoadedIntegration|undefined} */
@@ -250,10 +256,11 @@ export async function autolinkIntegrations({
continue;
}
if (!integration || integration.__loadError) continue;
- // Identity is the resolved package's own name, so an alias and the package
- // it aliases collapse here even when they are two directories on disk.
- if (names.has(integration.name)) continue;
- names.add(integration.name);
+ // Identity is the resolved package's own name and version, so an alias and
+ // the package it aliases collapse here even when they are two directories
+ // on disk.
+ if (seen.has(identity(integration))) continue;
+ seen.add(identity(integration));
autolinked.push({
...integration,
__autolinked: true,
diff --git a/packages/cli/foundation/integrations/integration-warnings.mjs b/packages/cli/foundation/integrations/integration-warnings.mjs
index 440a851e79..34702ba1d2 100644
--- a/packages/cli/foundation/integrations/integration-warnings.mjs
+++ b/packages/cli/foundation/integrations/integration-warnings.mjs
@@ -41,6 +41,12 @@ export async function warnOnIntegrationIssues(loadedIntegrations, {json = false}
}
for (const integration of loadedIntegrations) {
if (!integration || typeof integration !== 'object') continue;
+ // A package set aside for a provider-ID conflict is fine in isolation,
+ // so `doctor integration validate` would not explain it. Say it here.
+ if (integration.__providerConflict) {
+ console.error(`Warning: ${integration.__providerConflict.message}`);
+ continue;
+ }
let issues;
try {
issues = await validateLoadedIntegration(integration);
diff --git a/packages/cli/foundation/integrations/integrations.mjs b/packages/cli/foundation/integrations/integrations.mjs
index 71afc4dbf2..ec47929311 100644
--- a/packages/cli/foundation/integrations/integrations.mjs
+++ b/packages/cli/foundation/integrations/integrations.mjs
@@ -6,13 +6,19 @@
* Integrations are PACKAGE NAMES listed in astryx.config.{ts,mjs,js}. Each
* package declares a single conventional root manifest sibling to its
* package.json — astryx.integration.{ts,mjs,js} — which contributes
- * components/templates/codemods/docs/themes roots and an optional issuesUrl. Identity
- * (name, version) comes from the package's package.json, not the manifest.
+ * components/templates/codemods/docs/themes roots and an optional issuesUrl.
+ * Stable provider identity and package metadata come from package.json, not the
+ * manifest.
+ *
+ * @input Integration package names, package.json files, and root manifests.
+ * @output LoadedIntegration records with normalized provider identity and roots.
+ * @position foundation/integrations — package contribution loading boundary.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import {assertWithin} from '../fs/path-safety.mjs';
+import {normalizeProviderId} from '../identity/provider-identity.mjs';
// The key census and contribution parsers are internal to the schema module on
// purpose: the public parser still validates the complete authored type, while
// the loader can isolate an invalid optional contribution from valid roots.
@@ -31,6 +37,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
* are internal bookkeeping used by Doctor integration validation and Project.
* @typedef {object} LoadedIntegration
* @property {string} name
+ * @property {import('../../authoring/identity/type').ProviderId} [providerId]
+ * normalized stable provider identity; absent only for a legacy unnamed local
+ * package. Unique among contributing integrations: a later claimant is kept
+ * inert with `__providerConflict` (see {@link markProviderConflicts})
* @property {string} [version]
* @property {string} [components]
* @property {string} [templates]
@@ -49,6 +59,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
* @property {string} __manifestFile
* @property {string} [__loadError] set when the manifest failed to load/validate;
* such an integration contributes nothing and is surfaced via Project.issues()
+ * @property {{providerId: import('../../authoring/identity/type').ProviderId, claimedBy: string, message: string}} [__providerConflict]
+ * set on a package whose provider ID an earlier-loaded package already
+ * claims; it contributes nothing and is reported as a `duplicate_provider`
+ * warning
* @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
* surfaced as a warning; the rest of the manifest still contributes
* @property {boolean} [__autolinked] loaded because the project declares the
@@ -74,6 +88,137 @@ export const MANIFEST_BASENAMES = [
'astryx.integration.js',
];
+/**
+ * Normalize a package-owned provider ID without rejecting legacy unnamed local
+ * packages at this compatibility boundary.
+ * @param {unknown} name
+ * @returns {import('../../authoring/identity/type').ProviderId | undefined}
+ */
+function providerIdForPackage(name) {
+ if (typeof name !== 'string' || name.length === 0) return undefined;
+ try {
+ return normalizeProviderId(name);
+ } catch {
+ return undefined;
+ }
+}
+
+/**
+ * Resolve provider identity across loaded integrations, in precedence order.
+ *
+ * Artifact and document IDs are provider-scoped, so two packages cannot both
+ * contribute under one provider ID. The same package reached twice (an npm
+ * alias beside the package it aliases, with the same name and version) loads
+ * once. Any other later claimant, including the same package at another
+ * version, stays as an inert entry that carries the conflict. The package being
+ * authored claims its ID before precedence order is considered, because the
+ * source being edited is authoritative. The winner still contributes; Project
+ * issues, Doctor, and the per-command warning name the one set aside instead of
+ * dropping it without a word.
+ *
+ * @param {LoadedIntegration[]} integrations in precedence order
+ * @returns {LoadedIntegration[]}
+ */
+export function markProviderConflicts(integrations) {
+ /** @type {Map<string, LoadedIntegration>} */
+ const claims = new Map();
+ for (const integration of integrations) {
+ if (integration?.__local && claimsProvider(integration)) {
+ const providerId = /** @type {string} */ (integration.providerId);
+ if (!claims.has(providerId)) claims.set(providerId, integration);
+ }
+ }
+ /** @type {LoadedIntegration[]} */
+ const resolved = [];
+ for (const integration of integrations) {
+ if (!claimsProvider(integration)) {
+ resolved.push(integration);
+ continue;
+ }
+ const providerId = /** @type {string} */ (integration.providerId);
+ const claimant = claims.get(providerId);
+ if (claimant == null) {
+ claims.set(providerId, integration);
+ resolved.push(integration);
+ } else if (claimant === integration) {
+ resolved.push(integration);
+ } else if (
+ claimant.name !== integration.name ||
+ claimant.version !== integration.version
+ ) {
+ resolved.push(providerConflict(integration, claimant));
+ }
+ }
+ return resolved;
+}
+
+/**
+ * Whether an entry contributes under its provider ID: it has one, its manifest
+ * loaded, and it has not already been set aside.
+ * @param {LoadedIntegration | undefined} integration
+ * @returns {boolean}
+ */
+function claimsProvider(integration) {
+ return (
+ integration?.providerId != null &&
+ integration.__loadError == null &&
+ integration.__providerConflict == null
+ );
+}
+
+/**
+ * @param {LoadedIntegration} integration
+ * @returns {string}
+ */
+function describeIntegration(integration) {
+ const id = integration.version
+ ? `${integration.name}@${integration.version}`
+ : integration.name;
+ return integration.__spec && integration.__spec !== integration.name
+ ? `${id} (from "${integration.__spec}")`
+ : id;
+}
+
+/**
+ * An inert record for a package whose provider ID is already claimed. It keeps
+ * the package's identity and location for reporting, and drops every
+ * contribution root and handler.
+ * @param {LoadedIntegration} integration
+ * @param {LoadedIntegration} claimant
+ * @returns {LoadedIntegration}
+ */
+function providerConflict(integration, claimant) {
+ const providerId =
+ /** @type {import('../../authoring/identity/type').ProviderId} */ (
+ integration.providerId
+ );
+ const winner = describeIntegration(claimant);
+ const setAside = describeIntegration(integration);
+ const reason = claimant.__local
+ ? 'is the package being authored, so it is used'
+ : 'loads first and is used';
+ return {
+ name: integration.name,
+ providerId,
+ version: integration.version,
+ __spec: integration.__spec,
+ __packageDir: integration.__packageDir,
+ __manifestFile: integration.__manifestFile,
+ ...(integration.__local ? {__local: true} : {}),
+ ...(integration.__autolinked
+ ? {__autolinked: true, __dependencyField: integration.__dependencyField}
+ : {}),
+ __providerConflict: {
+ providerId,
+ claimedBy: claimant.name,
+ message:
+ `${setAside} and ${winner} both claim provider ID "${providerId}". ` +
+ `${winner} ${reason}; ${setAside} contributes nothing ` +
+ 'until one package changes its providerId.',
+ },
+ };
+}
+
/**
* Return the conventional root manifest paths present in `dir`, in
* load-precedence order. Unlike {@link resolveManifestPath} this never throws —
@@ -274,6 +419,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
typeof pkg.name === 'string' && pkg.name.length > 0
? pkg.name
: '(local integration)';
+ const packageProviderId = providerIdForPackage(pkg.name);
const manifestFile = resolveManifestPath(packageDir, spec);
let manifest;
@@ -299,6 +445,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
} catch (err) {
return {
name: spec,
+ ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
version: pkg.version,
__spec: spec,
__packageDir: packageDir,
@@ -308,6 +455,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
};
}
+ const providerId = providerIdForPackage(manifest.providerId ?? pkg.name);
+
/** @param {string | null | undefined} value */
const resolveRoot = value => {
if (value == null) return undefined;
@@ -320,6 +469,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
return {
name: spec,
+ ...(providerId == null ? {} : {providerId}),
version: pkg.version,
components: resolveRoot(manifest.components),
templates: resolveRoot(manifest.templates),
@@ -345,20 +495,22 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
* Load configured integrations.
*
* @param {string[]} [specs] package names
- * @param {{cwd?: string, fresh?: boolean}} [options]
+ * @param {{cwd?: string, fresh?: boolean, resolveProviders?: boolean}} [options]
+ * `resolveProviders: false` leaves provider identity to a caller that
+ * resolves it once over a larger set (Project.load)
* @returns {Promise<LoadedIntegration[]>}
*/
export async function loadIntegrations(
specs = [],
- {cwd = process.cwd(), fresh = false} = {},
+ {cwd = process.cwd(), fresh = false, resolveProviders = true} = {},
) {
/** @type {LoadedIntegration[]} */
const integrations = [];
- const seen = new Set();
+ const seenSpecs = new Set();
for (const spec of specs) {
- if (!spec || seen.has(spec)) continue;
- seen.add(spec);
+ if (!spec || seenSpecs.has(spec)) continue;
+ seenSpecs.add(spec);
const packageDir = resolvePackageDir(spec, cwd);
const pkgPath = path.join(packageDir, 'package.json');
@@ -371,6 +523,7 @@ export async function loadIntegrations(
);
}
+ const packageProviderId = providerIdForPackage(pkg.name ?? spec);
const manifestFile = resolveManifestPath(packageDir, spec);
let manifest;
/** @type {string[]} */
@@ -399,6 +552,7 @@ export async function loadIntegrations(
// discovery loops naturally skip it (no components/templates/codemods).
integrations.push({
name: pkg.name ?? spec,
+ ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
version: pkg.version,
__spec: spec,
__packageDir: packageDir,
@@ -408,6 +562,10 @@ export async function loadIntegrations(
continue;
}
+ const providerId = providerIdForPackage(
+ manifest.providerId ?? pkg.name ?? spec,
+ );
+
/** @param {string | null | undefined} value */
const resolveRoot = value => {
if (value == null) return undefined;
@@ -421,6 +579,7 @@ export async function loadIntegrations(
integrations.push({
name: pkg.name ?? spec,
+ ...(providerId == null ? {} : {providerId}),
version: pkg.version,
components: resolveRoot(manifest.components),
templates: resolveRoot(manifest.templates),
@@ -441,5 +600,5 @@ export async function loadIntegrations(
});
}
- return integrations;
+ return resolveProviders ? markProviderConflicts(integrations) : integrations;
}
diff --git a/packages/cli/foundation/integrations/integrations.test.mjs b/packages/cli/foundation/integrations/integrations.test.mjs
index e430490d2c..d955564be1 100644
--- a/packages/cli/foundation/integrations/integrations.test.mjs
+++ b/packages/cli/foundation/integrations/integrations.test.mjs
@@ -77,6 +77,7 @@ describe('configured integrations', () => {
const loaded = project.loadedIntegrations[0];
// Identity comes from package.json, not the manifest.
expect(loaded.name).toBe('@acme/widgets');
+ expect(loaded.providerId).toBe('@acme/widgets');
expect(loaded.version).toBe('1.2.3');
expect(loaded.components).toBe(path.join(pkgDir, 'docs'));
expect(loaded.templates).toBe(path.join(pkgDir, 'blocks'));
@@ -84,6 +85,43 @@ describe('configured integrations', () => {
expect(loaded.issuesUrl).toBe('https://example.com/issues');
});
+ it('preserves provider identity across an explicit package rename', async () => {
+ writeManifestPackage(tmpDir, {
+ body: `export default {providerId: '@acme/legacy-widgets'};\n`,
+ });
+
+ const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
+ expect(loaded.name).toBe('@acme/widgets');
+ expect(loaded.providerId).toBe('@acme/legacy-widgets');
+ expect(loaded.__unknownKeys).toEqual([]);
+ });
+
+ it('deduplicates package aliases by canonical provider identity', async () => {
+ writeManifestPackage(tmpDir, {body: `export default {};\n`});
+ const aliasDir = path.join(
+ tmpDir,
+ 'node_modules',
+ '@acme',
+ 'widgets-alias',
+ );
+ fs.mkdirSync(aliasDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(aliasDir, 'package.json'),
+ JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+ );
+ fs.writeFileSync(
+ path.join(aliasDir, 'astryx.integration.mjs'),
+ `export default {};\n`,
+ );
+
+ const loaded = await loadIntegrations(
+ ['@acme/widgets', '@acme/widgets-alias'],
+ {cwd: tmpDir},
+ );
+ expect(loaded).toHaveLength(1);
+ expect(loaded[0].providerId).toBe('@acme/widgets');
+ });
+
it('makes integration components discoverable', async () => {
const pkgDir = writeManifestPackage(tmpDir, {
body: `export default { components: './docs' };\n`,
@@ -207,6 +245,347 @@ describe('configured integrations', () => {
});
});
+describe('provider identity conflicts', () => {
+ /**
+ * Install one integration package that contributes a single component.
+ * @param {string} dir directory under node_modules
+ * @param {{name: string, version: string}} pkg package.json identity
+ * @param {Record<string, unknown>} manifest extra manifest fields
+ * @param {string} component the component it contributes
+ */
+ function installPackage(dir, pkg, manifest, component) {
+ const pkgDir = path.join(tmpDir, 'node_modules', ...dir.split('/'));
+ const componentsDir = path.join(pkgDir, 'components');
+ fs.mkdirSync(componentsDir, {recursive: true});
+ fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(pkg));
+ fs.writeFileSync(
+ path.join(pkgDir, 'astryx.integration.mjs'),
+ `export default ${JSON.stringify({components: './components', ...manifest})};\n`,
+ );
+ fs.writeFileSync(
+ path.join(componentsDir, `${component}.doc.mjs`),
+ `export default {type: 'component', name: '${component}', props: []};\n`,
+ );
+ fs.writeFileSync(
+ path.join(componentsDir, `${component}.tsx`),
+ `export function ${component}() { return null; }\n`,
+ );
+ }
+
+ /** @param {string[]} integrations */
+ function configure(integrations) {
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.config.mjs'),
+ `export default ${JSON.stringify({integrations})};\n`,
+ );
+ }
+
+ /**
+ * Make the project directory itself the package being authored.
+ * @param {Record<string, unknown>} pkg package.json fields
+ * @param {Record<string, unknown>} manifest extra manifest fields
+ * @param {string} component the component it contributes
+ */
+ function writeLocalPackage(pkg, manifest, component) {
+ const componentsDir = path.join(tmpDir, 'local-components');
+ fs.mkdirSync(componentsDir, {recursive: true});
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify(pkg));
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ `export default ${JSON.stringify({components: './local-components', ...manifest})};\n`,
+ );
+ fs.writeFileSync(
+ path.join(componentsDir, `${component}.doc.mjs`),
+ `export default {type: 'component', name: '${component}', props: []};\n`,
+ );
+ fs.writeFileSync(
+ path.join(componentsDir, `${component}.tsx`),
+ `export function ${component}() { return null; }\n`,
+ );
+ }
+
+ /** @param {import('../config/project.mjs').Project} project */
+ async function conflictIssues(project) {
+ return (await project.issues()).filter(
+ issue => issue.code === 'duplicate_provider',
+ );
+ }
+
+ it('keeps the first package and reports a different package claiming its ID', async () => {
+ installPackage(
+ '@acme/widgets',
+ {name: '@acme/widgets', version: '1.0.0'},
+ {},
+ 'Widget',
+ );
+ installPackage(
+ '@acme/renamed',
+ {name: '@acme/renamed', version: '2.0.0'},
+ {providerId: '@acme/widgets'},
+ 'RenamedWidget',
+ );
+ configure(['@acme/widgets', '@acme/renamed']);
+
+ const loaded = await loadIntegrations(['@acme/widgets', '@acme/renamed'], {
+ cwd: tmpDir,
+ });
+ expect(loaded.map(integration => integration.name)).toEqual([
+ '@acme/widgets',
+ '@acme/renamed',
+ ]);
+ expect(loaded[1]).toMatchObject({
+ providerId: '@acme/widgets',
+ __providerConflict: {
+ providerId: '@acme/widgets',
+ claimedBy: '@acme/widgets',
+ },
+ });
+ expect(loaded[1].components).toBeUndefined();
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ const owned = (await project.components()).map(component => [
+ component.package,
+ component.name,
+ ]);
+ expect(owned).toContainEqual(['@acme/widgets', 'Widget']);
+ expect(owned.some(([pkg]) => pkg === '@acme/renamed')).toBe(false);
+ expect(await project.issues()).toContainEqual(
+ expect.objectContaining({
+ package: '@acme/[email protected]',
+ code: 'duplicate_provider',
+ severity: 'warning',
+ message: expect.stringContaining(
+ '@acme/[email protected] loads first and is used',
+ ),
+ }),
+ );
+ });
+
+ it('reports the same package configured again at another version', async () => {
+ installPackage(
+ '@acme/widgets',
+ {name: '@acme/widgets', version: '1.0.0'},
+ {},
+ 'Widget',
+ );
+ installPackage(
+ 'widgets-next',
+ {name: '@acme/widgets', version: '2.0.0'},
+ {},
+ 'NextWidget',
+ );
+ configure(['@acme/widgets', 'widgets-next']);
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ const owned = (await project.components()).map(component => component.name);
+ expect(owned).toContain('Widget');
+ expect(owned).not.toContain('NextWidget');
+ expect(await project.issues()).toContainEqual(
+ expect.objectContaining({
+ package: '@acme/[email protected]',
+ code: 'duplicate_provider',
+ severity: 'warning',
+ message: expect.stringContaining('(from "widgets-next")'),
+ }),
+ );
+ });
+
+ it('reports an autolinked dependency that claims a configured ID', async () => {
+ installPackage(
+ '@acme/widgets',
+ {name: '@acme/widgets', version: '1.0.0'},
+ {},
+ 'Widget',
+ );
+ installPackage(
+ '@acme/renamed',
+ {name: '@acme/renamed', version: '2.0.0'},
+ {providerId: '@acme/widgets'},
+ 'RenamedWidget',
+ );
+ configure(['@acme/widgets']);
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({
+ name: 'consumer',
+ dependencies: {'@acme/renamed': '2.0.0'},
+ }),
+ );
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ expect(
+ project.loadedIntegrations.find(
+ integration => integration.name === '@acme/renamed',
+ ),
+ ).toMatchObject({
+ __autolinked: true,
+ __providerConflict: {claimedBy: '@acme/widgets'},
+ });
+ expect(await project.issues()).toContainEqual(
+ expect.objectContaining({
+ package: '@acme/[email protected]',
+ code: 'duplicate_provider',
+ }),
+ );
+ });
+
+ it("reports a set-aside package whose spec is the winner's name", async () => {
+ installPackage(
+ 'widgets-old',
+ {name: '@acme/widgets', version: '1.0.0'},
+ {},
+ 'OldWidget',
+ );
+ installPackage(
+ '@acme/widgets',
+ {name: '@acme/widgets', version: '2.0.0'},
+ {},
+ 'NewWidget',
+ );
+ configure(['widgets-old', '@acme/widgets']);
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ const owned = (await project.components()).map(component => component.name);
+ expect(owned).toContain('OldWidget');
+ expect(owned).not.toContain('NewWidget');
+ expect(await conflictIssues(project)).toEqual([
+ expect.objectContaining({
+ package: '@acme/[email protected]',
+ severity: 'warning',
+ message: expect.stringContaining(
+ '@acme/[email protected] and @acme/[email protected] (from "widgets-old") both claim',
+ ),
+ }),
+ ]);
+ });
+
+ it('reports an unversioned set-aside package whose spec is the winner\'s name', async () => {
+ installPackage(
+ 'widgets-old',
+ {name: '@acme/widgets', version: '1.0.0'},
+ {},
+ 'OldWidget',
+ );
+ installPackage('@acme/widgets', {name: '@acme/widgets'}, {}, 'NewWidget');
+ configure(['widgets-old', '@acme/widgets']);
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ expect(await conflictIssues(project)).toEqual([
+ expect.objectContaining({
+ package: '@acme/widgets',
+ message: expect.stringContaining(
+ '@acme/[email protected] (from "widgets-old") loads first and is used',
+ ),
+ }),
+ ]);
+ });
+
+ it('reports an autolinked alias of the same package at another version', async () => {
+ installPackage(
+ '@acme/legacy-ui',
+ {name: '@acme/ui', version: '0.1.22'},
+ {},
+ 'LegacyButton',
+ );
+ installPackage(
+ '@acme/ui',
+ {name: '@acme/ui', version: '1.0.0'},
+ {},
+ 'NewButton',
+ );
+ fs.rmSync(path.join(tmpDir, 'astryx.config.mjs'));
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({
+ name: 'consumer',
+ dependencies: {
+ '@acme/legacy-ui': 'npm:@acme/[email protected]',
+ '@acme/ui': '1.0.0',
+ },
+ }),
+ );
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ const owned = (await project.components()).map(component => component.name);
+ expect(owned).toContain('LegacyButton');
+ expect(owned).not.toContain('NewButton');
+ expect(await conflictIssues(project)).toEqual([
+ expect.objectContaining({
+ package: '@acme/[email protected]',
+ message: expect.stringContaining(
+ '@acme/[email protected] and @acme/[email protected] (from "@acme/legacy-ui") both claim',
+ ),
+ }),
+ ]);
+ });
+
+ it('recomputes conflicts after the authored package replaces its installed copy', async () => {
+ installPackage(
+ '@acme/widgets',
+ {name: '@acme/widgets', version: '1.0.0'},
+ {},
+ 'Widget',
+ );
+ installPackage(
+ '@acme/renamed',
+ {name: '@acme/renamed', version: '2.0.0'},
+ {providerId: '@acme/widgets'},
+ 'RenamedWidget',
+ );
+ configure(['@acme/widgets', '@acme/renamed']);
+ writeLocalPackage(
+ {name: '@acme/widgets', version: '3.0.0-dev'},
+ {providerId: '@acme/widgets-next'},
+ 'LocalWidget',
+ );
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ expect(
+ project.loadedIntegrations.some(
+ integration => integration.__providerConflict,
+ ),
+ ).toBe(false);
+ const owned = (await project.components()).map(component => component.name);
+ expect(owned).toEqual(
+ expect.arrayContaining(['LocalWidget', 'RenamedWidget']),
+ );
+ expect(owned).not.toContain('Widget');
+ expect(await conflictIssues(project)).toEqual([]);
+ });
+
+ it('lets the package being authored win over its installed predecessor', async () => {
+ installPackage(
+ '@acme/widgets',
+ {name: '@acme/widgets', version: '1.0.0'},
+ {},
+ 'Widget',
+ );
+ fs.rmSync(path.join(tmpDir, 'astryx.config.mjs'));
+ writeLocalPackage(
+ {
+ name: '@acme/renamed',
+ version: '2.0.0-dev',
+ devDependencies: {'@acme/widgets': '1.0.0'},
+ },
+ {providerId: '@acme/widgets'},
+ 'RenamedWidget',
+ );
+
+ const project = await Project.load(tmpDir, {fresh: true});
+ const owned = (await project.components()).map(component => component.name);
+ expect(owned).toContain('RenamedWidget');
+ expect(owned).not.toContain('Widget');
+ expect(await conflictIssues(project)).toEqual([
+ expect.objectContaining({
+ package: '@acme/[email protected]',
+ message: expect.stringContaining(
+ '@acme/[email protected] is the package being authored, so it is used',
+ ),
+ }),
+ ]);
+ });
+});
+
describe('local integration self-resolution', () => {
it('preserves a valid gapReport named export', async () => {
fs.writeFileSync(
@@ -225,7 +604,11 @@ export default {};
const loaded = await loadLocalIntegration(tmpDir, {fresh: true});
- expect(loaded).toMatchObject({name: '@acme/local', __local: true});
+ expect(loaded).toMatchObject({
+ name: '@acme/local',
+ providerId: '@acme/local',
+ __local: true,
+ });
expect(loaded?.__gapReport?.audience).toBe('internal');
expect(
loaded?.__gapReport?.handle(
diff --git a/packages/cli/foundation/integrations/provider-conflicts.test.mjs b/packages/cli/foundation/integrations/provider-conflicts.test.mjs
new file mode 100644
index 0000000000..a7d6d71d79
--- /dev/null
+++ b/packages/cli/foundation/integrations/provider-conflicts.test.mjs
@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Provider-identity conflicts proved against the repository's real
+ * integration packages instead of hand-written fixtures: the Lab package as it
+ * ships, beside a copy of Charts whose manifest also claims Lab's provider ID.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {Project} from '../config/project.mjs';
+import {doctor} from '../../api/doctor/doctor.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const REPO = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../../..',
+);
+const CHARTS = path.join(REPO, 'packages', 'charts');
+const SLOW = 60_000;
+
+/** Both packages are named; Lab is named as the one used, Charts as set aside. */
+const WINNER_NAMED =
+ /@astryxdesign\/charts@\S+ and @astryxdesign\/lab@\S+ both claim provider ID "@astryxdesign\/lab"\. @astryxdesign\/lab@\S+ loads first and is used; @astryxdesign\/charts@\S+ contributes nothing/u;
+
+let consumer;
+let chartsManifest;
+
+beforeEach(() => {
+ consumer = fs.mkdtempSync(
+ path.join(process.cwd(), '.astryx-provider-conflict-'),
+ );
+ const scope = path.join(consumer, 'node_modules', '@astryxdesign');
+ fs.mkdirSync(scope, {recursive: true});
+ fs.symlinkSync(
+ path.join(REPO, 'packages', 'lab'),
+ path.join(scope, 'lab'),
+ 'dir',
+ );
+
+ const charts = path.join(scope, 'charts');
+ fs.cpSync(CHARTS, charts, {
+ recursive: true,
+ filter: source => {
+ const [top] = path.relative(CHARTS, source).split(path.sep);
+ return top !== 'node_modules' && top !== 'dist';
+ },
+ });
+ chartsManifest = path.join(charts, 'astryx.integration.mjs');
+ const shipped = fs.readFileSync(chartsManifest, 'utf8');
+ const claimed = shipped.replace(
+ 'export default {',
+ "export default {\n providerId: '@astryxdesign/lab',",
+ );
+ expect(claimed).not.toBe(shipped);
+ fs.writeFileSync(chartsManifest, claimed);
+
+ fs.writeFileSync(
+ path.join(consumer, 'package.json'),
+ JSON.stringify({name: 'consumer', private: true}),
+ );
+ fs.writeFileSync(
+ path.join(consumer, 'astryx.config.mjs'),
+ "export default {integrations: ['@astryxdesign/lab', '@astryxdesign/charts']};\n",
+ );
+});
+
+afterEach(() => {
+ fs.rmSync(consumer, {recursive: true, force: true});
+});
+
+describe('provider identity conflicts in the real integration packages', () => {
+ it('keeps Lab, sets Charts aside, and names both on every surface', async () => {
+ const project = await Project.load(consumer, {fresh: true});
+ const components = await project.components();
+ expect(
+ components.filter(component => component.package === '@astryxdesign/lab')
+ .length,
+ ).toBeGreaterThan(0);
+ expect(
+ components.some(component => component.package === '@astryxdesign/charts'),
+ ).toBe(false);
+ const conflicts = (await project.issues()).filter(
+ issue => issue.code === 'duplicate_provider',
+ );
+ expect(conflicts).toEqual([
+ expect.objectContaining({
+ package: expect.stringMatching(/^@astryxdesign\/charts@\S+$/u),
+ severity: 'warning',
+ message: expect.stringMatching(WINNER_NAMED),
+ }),
+ ]);
+
+ const report = await doctor({cwd: consumer});
+ const check = report.data.checks.find(
+ candidate => candidate.id === 'provider-identity',
+ );
+ expect(check?.status).toBe('warn');
+ expect(check?.message).toMatch(WINNER_NAMED);
+
+ const cli = await runCli(['component', '--list'], consumer);
+ expect(cli.status).toBe(0);
+ expect(cli.stderr).toMatch(WINNER_NAMED);
+ }, SLOW);
+
+ it('loads both real packages without an issue once their IDs differ', async () => {
+ fs.copyFileSync(path.join(CHARTS, 'astryx.integration.mjs'), chartsManifest);
+
+ const project = await Project.load(consumer, {fresh: true});
+ const components = await project.components();
+ expect(
+ components.some(component => component.package === '@astryxdesign/charts'),
+ ).toBe(true);
+ expect(
+ (await project.issues()).filter(
+ issue => issue.code === 'duplicate_provider',
+ ),
+ ).toEqual([]);
+ }, SLOW);
+});
diff --git a/packages/cli/foundation/integrations/validate-contributions.mjs b/packages/cli/foundation/integrations/validate-contributions.mjs
index 9ba85d6c21..d48435bc43 100644
--- a/packages/cli/foundation/integrations/validate-contributions.mjs
+++ b/packages/cli/foundation/integrations/validate-contributions.mjs
@@ -39,6 +39,9 @@ import {discoverIntegrationThemes} from '../discovery/theme-discovery.mjs';
/** Stable issue code for an invalid optional agent-doc contribution. */
export const INVALID_AGENT_DOCS = 'invalid_agent_docs';
+/** Stable issue code for a package whose provider ID is already claimed. */
+export const DUPLICATE_PROVIDER = 'duplicate_provider';
+
/** @param {string} code @param {string} message @returns {Issue} */
export function issueError(code, message) {
return {code, severity: 'error', message};
@@ -289,6 +292,13 @@ export async function validateLoadedIntegration(loaded) {
/** @type {Issue[]} */
const issues = [];
if (!loaded || typeof loaded !== 'object') return issues;
+ // A package set aside for claiming another package's provider ID has no
+ // contribution roots to check; the conflict itself is what to report.
+ if (loaded.__providerConflict) {
+ return [
+ issueWarning(DUPLICATE_PROVIDER, loaded.__providerConflict.message),
+ ];
+ }
// A manifest that threw on import (or failed the schema) carries a load-error
// marker and no contribution roots, so every check below would find nothing
// and report a clean integration — which is how a stale manifest used to go
diff --git a/packages/cli/foundation/response/json-contract.test.mjs b/packages/cli/foundation/response/json-contract.test.mjs
index 58c6a78b9e..7934edb319 100644
--- a/packages/cli/foundation/response/json-contract.test.mjs
+++ b/packages/cli/foundation/response/json-contract.test.mjs
@@ -13,6 +13,8 @@
import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {
@@ -27,10 +29,20 @@ import {
} from './json.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI = path.resolve(__dirname, '..', '..', 'clients', 'cli', 'bin', 'astryx.mjs');
-
-function runCli(args) {
+const CLI = path.resolve(
+ __dirname,
+ '..',
+ '..',
+ 'clients',
+ 'cli',
+ 'bin',
+ 'astryx.mjs',
+);
+
+/** @param {string[]} args @param {{cwd?: string}} [options] */
+function runCli(args, {cwd = process.cwd()} = {}) {
return spawnSync(process.execPath, [CLI, ...args], {
+ cwd,
encoding: 'utf8',
timeout: 20_000,
stdio: ['ignore', 'pipe', 'pipe'],
@@ -42,7 +54,9 @@ describe('json envelope shape', () => {
let logs;
beforeEach(() => {
logs = [];
- vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
+ vi.spyOn(console, 'log').mockImplementation((...a) =>
+ logs.push(a.join(' ')),
+ );
setJsonMode(false);
});
afterEach(() => {
@@ -80,11 +94,13 @@ describe('json envelope shape', () => {
});
it('toErrorEnvelope honors an explicit code argument', () => {
- expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual({
- apiVersion: API_VERSION,
- error: 'boom',
- code: 'ERR_UNKNOWN_COMPONENT',
- });
+ expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual(
+ {
+ apiVersion: API_VERSION,
+ error: 'boom',
+ code: 'ERR_UNKNOWN_COMPONENT',
+ },
+ );
});
it('toErrorEnvelope reads a code carried on a thrown Error', () => {
@@ -109,8 +125,12 @@ describe('json envelope shape', () => {
// The guard is `Array.isArray(...) && .length`, not a bare `?.length` — a
// string ("hello".length === 5) or a `{length: n}` object must NOT slip
// through as `suggestions`, which is contractually a Suggestion[].
- expect('suggestions' in toErrorEnvelope('x', /** @type {any} */ ('hello'))).toBe(false);
- expect('suggestions' in toErrorEnvelope('x', /** @type {any} */ ({length: 3}))).toBe(false);
+ expect(
+ 'suggestions' in toErrorEnvelope('x', /** @type {any} */ ('hello')),
+ ).toBe(false);
+ expect(
+ 'suggestions' in toErrorEnvelope('x', /** @type {any} */ ({length: 3})),
+ ).toBe(false);
});
});
@@ -119,8 +139,12 @@ describe('stdout discipline (humanLog / humanWarn)', () => {
beforeEach(() => {
logs = [];
errs = [];
- vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
- vi.spyOn(console, 'error').mockImplementation((...a) => errs.push(a.join(' ')));
+ vi.spyOn(console, 'log').mockImplementation((...a) =>
+ logs.push(a.join(' ')),
+ );
+ vi.spyOn(console, 'error').mockImplementation((...a) =>
+ errs.push(a.join(' ')),
+ );
});
afterEach(() => {
vi.restoreAllMocks();
@@ -174,10 +198,15 @@ describe('contract: every --json emission is valid JSON with apiVersion', () =>
});
it('init emits its install receipt', () => {
- const r = runCli(['init', '--json']);
- const env = JSON.parse(r.stdout);
- expect(env.apiVersion).toBe(API_VERSION);
- expect(env.type).toBe('init.run');
+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-json-contract-'));
+ try {
+ const r = runCli(['init', '--json'], {cwd});
+ const env = JSON.parse(r.stdout);
+ expect(env.apiVersion).toBe(API_VERSION);
+ expect(env.type).toBe('init.run');
+ } finally {
+ fs.rmSync(cwd, {recursive: true, force: true});
+ }
});
it('supported command (discover) emits clean JSON, no human chatter leak', () => {
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index 660cff067d..e532864f0c 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -68,10 +68,15 @@ export const doc = {
description:
"One topic's full ReferenceDoc, with token-ref blocks inlined.",
},
+ {
+ value: 'docs.index',
+ description:
+ "One topic's section index (--index): each section's key, title, and one-line summary.",
+ },
{
value: 'docs.detail.section',
description:
- 'A single ReferenceSection of a topic: the first whose title contains the section query.',
+ 'One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined.',
},
// blog (read from the published RSS feed)
diff --git a/packages/cli/test/authoring-types/namespace.doc.mjs b/packages/cli/test/authoring-types/namespace.doc.mjs
new file mode 100644
index 0000000000..c4f50684c0
--- /dev/null
+++ b/packages/cli/test/authoring-types/namespace.doc.mjs
@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'cli',
+ title: 'Astryx CLI',
+ summary: 'Commands, APIs, and integration authoring.',
+ slots: {
+ guides: {
+ title: 'Guides',
+ accepts: {kinds: ['namespace', 'generic']},
+ },
+ },
+ blocks: [
+ {type: 'collection', source: {slot: 'guides'}, presentation: 'cards'},
+ ],
+};
diff --git a/packages/cli/test/authoring-types/namespace.doc.ts b/packages/cli/test/authoring-types/namespace.doc.ts
new file mode 100644
index 0000000000..3d6f963103
--- /dev/null
+++ b/packages/cli/test/authoring-types/namespace.doc.ts
@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {
+ AuthoredDocEntry,
+ AuthoredDocKindOf,
+ NamespaceDoc,
+ ProviderId,
+} from '@astryxdesign/cli/authoring';
+
+export const docs = {
+ type: 'namespace',
+ name: 'integrations',
+ title: 'Author integrations',
+ summary: 'Publish reusable Astryx packages.',
+ placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
+ slots: {
+ reference: {
+ title: 'Reference',
+ accepts: {kinds: ['command', 'function', 'schema', 'enum']},
+ },
+ },
+ blocks: [
+ {
+ type: 'workflow',
+ steps: [{title: 'Validate', references: ['command:doctor']}],
+ },
+ {type: 'reference', target: 'schema:integration'},
+ ],
+} satisfies NamespaceDoc;
+
+export type Provider = ProviderId;
+export type Entry = AuthoredDocEntry;
+
+type Equal<Left, Right> =
+ (<Value>() => Value extends Left ? 1 : 2) extends <
+ Value,
+ >() => Value extends Right ? 1 : 2
+ ? true
+ : false;
+type Assert<Value extends true> = Value;
+
+export type NamespaceKindContract = Assert<
+ Equal<AuthoredDocKindOf<NamespaceDoc>, 'namespace'>
+>;
+export type NamespaceEntryKindContract = Assert<
+ Equal<AuthoredDocEntry<NamespaceDoc>['kind'], 'namespace'>
+>;
+
+declare const namespaceEntry: AuthoredDocEntry<NamespaceDoc>;
+// @ts-expect-error Compiler entries expose immutable authored snapshots.
+namespaceEntry.authored.title = 'Changed';
diff --git a/packages/cli/test/drift/docs-drift.mjs b/packages/cli/test/drift/docs-drift.mjs
index 6777a56040..a52115903f 100644
--- a/packages/cli/test/drift/docs-drift.mjs
+++ b/packages/cli/test/drift/docs-drift.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Drift checks for the colocated CLI docs. Keeps the hand-authored docs
- * honest against their sources of truth:
- * - every `*.doc.mjs` under the doc roots parses via `parseDoc`;
+ * @file Drift checks for every production AuthoredDoc in the repository. Keeps
+ * the hand-authored docs honest against their sources of truth:
+ * - every `*.doc.mjs` under a production doc root parses via `parseDoc`;
* - each CommandDoc's `fn` resolves to a FunctionDoc, its arg/option `param`s
* exist on that function, and its `name` is a real manifest command;
* - the error-codes EnumDoc == ERROR_CODES exactly;
@@ -21,13 +21,21 @@ import {allErrorCodes} from '../../foundation/response/error-codes.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const CLI_ROOT = path.resolve(HERE, '../..');
+const REPO_ROOT = path.resolve(CLI_ROOT, '../..');
const BIN = path.join(CLI_ROOT, 'clients/cli/bin/astryx.mjs');
const DOC_ROOTS = [
- 'authoring',
- 'api',
- 'clients/cli/commands',
- 'foundation/response',
-].map(r => path.join(CLI_ROOT, r));
+ 'packages/cli/authoring',
+ 'packages/cli/api',
+ 'packages/cli/clients/cli/commands',
+ 'packages/cli/foundation',
+ 'packages/cli/assets',
+ 'packages/cli/test/authoring-types',
+ 'packages/core/src',
+ 'packages/lab/src',
+ 'packages/charts/src',
+ 'packages/richtext/src',
+ 'packages/vega/src',
+].map(root => path.join(REPO_ROOT, root));
/** @param {string} dir @returns {string[]} */
function walk(dir) {
@@ -45,7 +53,10 @@ export async function collectDocs() {
const out = [];
for (const f of files) {
const mod = await import(pathToFileURL(f).href);
- out.push({file: path.relative(CLI_ROOT, f), doc: mod.doc ?? mod.docs});
+ out.push({
+ file: path.relative(REPO_ROOT, f),
+ doc: mod.doc ?? mod.docs ?? mod.default,
+ });
}
return out;
}
diff --git a/packages/cli/test/drift/docs-drift.test.mjs b/packages/cli/test/drift/docs-drift.test.mjs
index f133bde64e..3ca1fc53a0 100644
--- a/packages/cli/test/drift/docs-drift.test.mjs
+++ b/packages/cli/test/drift/docs-drift.test.mjs
@@ -8,10 +8,10 @@
import {describe, it, expect} from 'vitest';
import {runDrift} from './docs-drift.mjs';
-describe('colocated CLI docs drift', () => {
+describe('production authored-doc drift', () => {
it('every doc parses and stays in sync with its source of truth', async () => {
const {count, errors} = await runDrift();
- expect(count).toBeGreaterThan(0);
+ expect(count).toBeGreaterThan(1000);
if (errors.length) {
throw new Error(
`docs drift detected (${errors.length}):\n ${errors.join('\n ')}`,
diff --git a/packages/cli/tsconfig.authoring-contract.json b/packages/cli/tsconfig.authoring-contract.json
index e519d3a47f..c13c326bfd 100644
--- a/packages/cli/tsconfig.authoring-contract.json
+++ b/packages/cli/tsconfig.authoring-contract.json
@@ -1,6 +1,11 @@
{
"//": "Focused typecheck for the authoring surface. checkJs is on so the JSDoc drift-locks (Expect<Equal<z.infer<schema>, PublicType>>) in each parser are evaluated — a sealed schema that drifts from its public type fails here.",
"extends": "./tsconfig.strict.json",
- "include": ["authoring/**/*.mjs", "authoring/**/*.ts"],
+ "include": [
+ "authoring/**/*.mjs",
+ "authoring/**/*.ts",
+ "test/authoring-types/**/*.mjs",
+ "test/authoring-types/**/*.ts"
+ ],
"exclude": ["**/*.test.mjs"]
}