Skip to content

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

TypeScript

refactor(cli): split docs into api/docs leaf shape (#4481)

Joeyf184e8856fd4
diff --git a/.changeset/cli-docs-leaves.md b/.changeset/cli-docs-leaves.md
new file mode 100644
index 0000000000..a6d7ba6411
--- /dev/null
+++ b/.changeset/cli-docs-leaves.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[refactor] CLI: docs reorganized into api/docs leaf shape — `docs()` in `api/docs/docs.mjs` is now a dispatcher + barrel that routes by argument shape into three leaves (`api/docs/list`, `api/docs/detail`, `api/docs/detail/section`), each projecting into a single `{ type, data }` envelope. The discovery, overlay loading, and topic resolution shared by ≥2 leaves live in `api/docs/_adapter.mjs`. Pure reorganization: the `docs` export, `api/index.mjs`, the CLI consumer, and all `--json` and human output are unchanged (byte-identical).
+@josephfarina
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
new file mode 100644
index 0000000000..ab79705e1d
--- /dev/null
+++ b/packages/cli/api/docs/_adapter.mjs
@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared doc-loading and topic-resolution helpers for the docs leaves.
+ *
+ * @input packages/cli/docs/{topic}.doc.mjs and, when a --dense/--zh overlay is
+ * requested, the sibling {topic}.doc.dense.mjs / {topic}.doc.zh.mjs.
+ * @output Topic discovery map, overlay-merged reference-doc data, and a combined
+ * resolve step ({topics, docsData}) that the detail and section leaves share.
+ * @position Sits beside docs.mjs (api/docs/). Owns everything ≥2 leaves need so
+ * no leaf re-implements discovery, overlay merging, or unknown-topic handling.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+
+const DOCS_DIR = path.join(CLI_ROOT, 'docs');
+
+/**
+ * @returns {Record<string, string>}
+ */
+export function discoverTopics() {
+ /** @type {Record<string, string>} */
+ const topics = {};
+ if (!fs.existsSync(DOCS_DIR)) return topics;
+ for (const file of fs.readdirSync(DOCS_DIR)) {
+ const match = file.match(/^([\w-]+)\.doc\.mjs$/);
+ if (match) topics[match[1]] = path.join(DOCS_DIR, file);
+ }
+ return topics;
+}
+
+/**
+ * @param {string} docPath
+ * @param {{lang?: string|null}} [opts]
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
+ */
+export async function loadReferenceDocs(docPath, {lang} = {}) {
+ const mod = await import(pathToFileURL(docPath).href);
+ const docs = mod.docs;
+ 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`);
+ if (!fs.existsSync(translationPath)) return docs;
+
+ const translationMod = await import(pathToFileURL(translationPath).href);
+ const translation = translationMod.docsZh || translationMod.docsDense;
+ if (!translation) return docs;
+
+ // Overlays are keyed to a base section by title (`section`), not by array
+ // position. Position-keying silently grafted each overlay title onto whatever
+ // base section happened to share its index, so an overlay that omitted or
+ // reordered a section corrupted every section after it — `docs tokens --dense`
+ // printed the colour table under a "Spacing" heading (#2182). An overlay may
+ // now cover any subset of sections, in any order; sections it does not name
+ // keep their base content.
+ /** @type {Map<string, any>} */
+ const bySection = new Map();
+ for (const ts of translation.sections ?? []) {
+ if (ts?.section != null) bySection.set(ts.section, ts);
+ }
+
+ return {
+ ...docs,
+ description: translation.description || docs.description,
+ sections: docs.sections.map(
+ (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ section) => {
+ const ts = bySection.get(section.title);
+ if (!ts) return section;
+ return {
+ ...section,
+ title: ts.title || section.title,
+ content: section.content.map(
+ (
+ /** @type {import('../../../core/src/docs-types').ContentBlock} */ block,
+ /** @type {number} */ bi,
+ ) => {
+ 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};
+ return block;
+ },
+ ),
+ };
+ },
+ ),
+ };
+}
+
+/**
+ * Discover topics, resolve `topic` to its doc file (throwing `ERR_UNKNOWN_TOPIC`
+ * when unmatched), and load that topic's reference doc with any --dense/--zh
+ * overlay applied. Shared by the detail and section leaves so topic normalization
+ * and unknown-topic handling live in exactly one place.
+ *
+ * @param {string} topic
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @returns {Promise<{
+ * topics: Record<string, string>,
+ * docsData: import('../../types/docs').DocsDetailResponse['data'],
+ * }>}
+ */
+export async function resolveTopicDocs(topic, options = {}) {
+ const {lang = null, zh = false, dense = false} = options;
+ const effectiveLang = lang || (dense ? 'dense' : zh ? 'zh' : null);
+ const topics = discoverTopics();
+
+ const normalized = topic.toLowerCase();
+ if (!topics[normalized]) {
+ throw new AstryxError(
+ `Unknown topic "${topic}"`,
+ Object.keys(topics).map(t => ({name: t, reason: 'available topic'})),
+ ERROR_CODES.ERR_UNKNOWN_TOPIC,
+ );
+ }
+
+ const docsData = await loadReferenceDocs(topics[normalized], {lang: effectiveLang});
+ return {topics, docsData};
+}
diff --git a/packages/cli/api/docs/detail/detail.mjs b/packages/cli/api/docs/detail/detail.mjs
new file mode 100644
index 0000000000..2bce94dc25
--- /dev/null
+++ b/packages/cli/api/docs/detail/detail.mjs
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs.detail leaf — load one topic's full reference doc.
+ *
+ * @input A topic name plus optional {lang, zh, dense}. Resolves and loads the
+ * topic via the shared adapter, then inlines any token-ref blocks.
+ * @output { type: 'docs.detail', data: ReferenceDoc } — the full doc with
+ * token-refs resolved, matching `xds --json docs <topic>`.
+ * @position Leaf under api/docs. Owns resolveTokenRefs (used only here); shares
+ * discovery/loading/topic-resolution with the section leaf via _adapter.mjs.
+ */
+
+import {pathToFileURL} from 'node:url';
+import {resolveTopicDocs} from '../_adapter.mjs';
+
+/**
+ * Resolve token-ref blocks by inlining the referenced section's table.
+ * This allows section docs to reference token tables without duplicating data.
+ * @param {import('../../../types/docs').DocsDetailResponse['data']} docsData
+ * @param {Record<string, string>} topics
+ * @returns {Promise<import('../../../types/docs').DocsDetailResponse['data']>}
+ */
+async function resolveTokenRefs(docsData, topics) {
+ const resolved = {...docsData, sections: [...docsData.sections]};
+ for (let si = 0; si < resolved.sections.length; si++) {
+ const section = resolved.sections[si];
+ /** @type {import('../../../../core/src/docs-types').ContentBlock[]} */
+ const newContent = [];
+ for (const block of section.content) {
+ if (block.type === 'token-ref') {
+ const refPath = topics[block.topic];
+ if (!refPath) {
+ newContent.push({type: 'prose', text: `[token-ref: unknown topic "${block.topic}"]`});
+ continue;
+ }
+ const refMod = await import(pathToFileURL(refPath).href);
+ const refDocs = refMod.docs;
+ const refSection = refDocs.sections.find(
+ (/** @type {import('../../../../core/src/docs-types').ReferenceSection} */ s) =>
+ s.title.toLowerCase() === block.section.toLowerCase(),
+ );
+ if (!refSection) {
+ newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
+ continue;
+ }
+ // Inline the referenced section's content blocks (tables, prose, etc.)
+ // and carry over the previewType
+ for (const refBlock of refSection.content) {
+ newContent.push(refBlock);
+ }
+ // 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};
+ }
+ } else {
+ newContent.push(block);
+ }
+ }
+ if (resolved.sections[si] === section) {
+ resolved.sections[si] = {...section, content: newContent};
+ } else {
+ resolved.sections[si].content = newContent;
+ }
+ }
+ return resolved;
+}
+
+/**
+ * @param {string} topic
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @returns {Promise<import('../../../types/docs').DocsDetailResponse>}
+ */
+export async function detail(topic, options = {}) {
+ const {topics, docsData} = await resolveTopicDocs(topic, options);
+ const resolved = await resolveTokenRefs(docsData, topics);
+ 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
new file mode 100644
index 0000000000..3cb47684b7
--- /dev/null
+++ b/packages/cli/api/docs/detail/section/section.mjs
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs.detail.section leaf — load a single named 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.
+ * @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 '../../../../lib/error-codes.mjs';
+import {resolveTopicDocs} from '../../_adapter.mjs';
+
+/**
+ * @param {string} topic
+ * @param {string} sectionName
+ * @param {object} [options]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @returns {Promise<import('../../../../types/docs').DocsDetailSectionResponse>}
+ */
+export async function section(topic, sectionName, options = {}) {
+ const {docsData} = await resolveTopicDocs(topic, options);
+
+ const normalizedSection = sectionName.toLowerCase();
+ const match = docsData.sections.find(s => s.title.toLowerCase().includes(normalizedSection));
+ if (!match) {
+ throw new AstryxError(
+ `Section "${sectionName}" not found in "${topic}"`,
+ docsData.sections.map(s => ({name: s.title, reason: 'available section'})),
+ ERROR_CODES.ERR_UNKNOWN_SECTION,
+ );
+ }
+ return {type: 'docs.detail.section', data: match};
+}
diff --git a/packages/cli/api/docs/docs.mjs b/packages/cli/api/docs/docs.mjs
index 0ad4a62380..eb0abfb620 100644
--- a/packages/cli/api/docs/docs.mjs
+++ b/packages/cli/api/docs/docs.mjs
@@ -2,143 +2,25 @@
/**
* @file Programmatic API for the docs command.
+ *
+ * Dispatcher + barrel. `docs()` routes by argument shape into one of three
+ * 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
+ *
+ * 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.
*/
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
-import {CLI_ROOT} from '../../utils/paths.mjs';
-import {AstryxError} from '../error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {list} from './list/list.mjs';
+import {detail} from './detail/detail.mjs';
+import {section as sectionLeaf} from './detail/section/section.mjs';
-const DOCS_DIR = path.join(CLI_ROOT, 'docs');
-
-/**
- * @returns {Record<string, string>}
- */
-function discoverTopics() {
- /** @type {Record<string, string>} */
- const topics = {};
- if (!fs.existsSync(DOCS_DIR)) return topics;
- for (const file of fs.readdirSync(DOCS_DIR)) {
- const match = file.match(/^([\w-]+)\.doc\.mjs$/);
- if (match) topics[match[1]] = path.join(DOCS_DIR, file);
- }
- return topics;
-}
-
-/**
- * @param {string} docPath
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
- */
-async function loadReferenceDocs(docPath, {lang} = {}) {
- const mod = await import(pathToFileURL(docPath).href);
- const docs = mod.docs;
- 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`);
- if (!fs.existsSync(translationPath)) return docs;
-
- const translationMod = await import(pathToFileURL(translationPath).href);
- const translation = translationMod.docsZh || translationMod.docsDense;
- if (!translation) return docs;
-
- // Overlays are keyed to a base section by title (`section`), not by array
- // position. Position-keying silently grafted each overlay title onto whatever
- // base section happened to share its index, so an overlay that omitted or
- // reordered a section corrupted every section after it — `docs tokens --dense`
- // printed the colour table under a "Spacing" heading (#2182). An overlay may
- // now cover any subset of sections, in any order; sections it does not name
- // keep their base content.
- /** @type {Map<string, any>} */
- const bySection = new Map();
- for (const ts of translation.sections ?? []) {
- if (ts?.section != null) bySection.set(ts.section, ts);
- }
-
- return {
- ...docs,
- description: translation.description || docs.description,
- sections: docs.sections.map(
- (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ section) => {
- const ts = bySection.get(section.title);
- if (!ts) return section;
- return {
- ...section,
- title: ts.title || section.title,
- content: section.content.map(
- (
- /** @type {import('../../../core/src/docs-types').ContentBlock} */ block,
- /** @type {number} */ bi,
- ) => {
- 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};
- return block;
- },
- ),
- };
- },
- ),
- };
-}
-
-/**
- * Resolve token-ref blocks by inlining the referenced section's table.
- * This allows section docs to reference token tables without duplicating data.
- * @param {import('../../types/docs').DocsDetailResponse['data']} docsData
- * @param {Record<string, string>} topics
- * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
- */
-async function resolveTokenRefs(docsData, topics) {
- const resolved = {...docsData, sections: [...docsData.sections]};
- for (let si = 0; si < resolved.sections.length; si++) {
- const section = resolved.sections[si];
- /** @type {import('../../../core/src/docs-types').ContentBlock[]} */
- const newContent = [];
- for (const block of section.content) {
- if (block.type === 'token-ref') {
- const refPath = topics[block.topic];
- if (!refPath) {
- newContent.push({type: 'prose', text: `[token-ref: unknown topic "${block.topic}"]`});
- continue;
- }
- const refMod = await import(pathToFileURL(refPath).href);
- const refDocs = refMod.docs;
- const refSection = refDocs.sections.find(
- (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ s) =>
- s.title.toLowerCase() === block.section.toLowerCase(),
- );
- if (!refSection) {
- newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
- continue;
- }
- // Inline the referenced section's content blocks (tables, prose, etc.)
- // and carry over the previewType
- for (const refBlock of refSection.content) {
- newContent.push(refBlock);
- }
- // 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};
- }
- } else {
- newContent.push(block);
- }
- }
- if (resolved.sections[si] === section) {
- resolved.sections[si] = {...section, content: newContent};
- } else {
- resolved.sections[si].content = newContent;
- }
- }
- return resolved;
-}
+export {list, detail, sectionLeaf as section};
/**
* @param {string} [topic]
@@ -154,48 +36,7 @@ async function resolveTokenRefs(docsData, topics) {
* >}
*/
export async function docs(topic, section, options = {}) {
- const {lang = null, zh = false, dense = false} = options;
- const effectiveLang = lang || (dense ? 'dense' : zh ? 'zh' : null);
- const topics = discoverTopics();
-
- if (!topic) {
- /** @type {Array<import('../../types/docs').DocsListEntry>} */
- const entries = [];
- for (const [name, docPath] of Object.entries(topics)) {
- try {
- const mod = await import(pathToFileURL(docPath).href);
- entries.push({topic: name, description: mod.docs.description});
- } catch {
- entries.push({topic: name, description: ''});
- }
- }
- return {type: 'docs.list', data: entries};
- }
-
- const normalized = topic.toLowerCase();
- if (!topics[normalized]) {
- throw new AstryxError(
- `Unknown topic "${topic}"`,
- Object.keys(topics).map(t => ({name: t, reason: 'available topic'})),
- ERROR_CODES.ERR_UNKNOWN_TOPIC,
- );
- }
-
- const docsData = await loadReferenceDocs(topics[normalized], {lang: effectiveLang});
-
- if (section) {
- const normalizedSection = section.toLowerCase();
- const match = docsData.sections.find(s => s.title.toLowerCase().includes(normalizedSection));
- if (!match) {
- throw new AstryxError(
- `Section "${section}" not found in "${topic}"`,
- docsData.sections.map(s => ({name: s.title, reason: 'available section'})),
- ERROR_CODES.ERR_UNKNOWN_SECTION,
- );
- }
- return {type: 'docs.detail.section', data: match};
- }
-
- const resolved = await resolveTokenRefs(docsData, topics);
- return {type: 'docs.detail', data: resolved};
+ if (!topic) return list();
+ if (section) return sectionLeaf(topic, section, options);
+ return detail(topic, options);
}
diff --git a/packages/cli/api/docs/list/list.mjs b/packages/cli/api/docs/list/list.mjs
new file mode 100644
index 0000000000..d59ea34413
--- /dev/null
+++ b/packages/cli/api/docs/list/list.mjs
@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs.list leaf — enumerate the available reference-doc topics.
+ *
+ * @input Reads packages/cli/docs/{topic}.doc.mjs via the shared adapter's
+ * topic discovery. Each topic's English `description` is read directly; the
+ * listing never applies --dense/--zh overlays.
+ * @output { type: 'docs.list', data: DocsListEntry[] } — one entry per topic,
+ * in filesystem-discovery order, matching `xds --json docs`.
+ * @position Leaf under api/docs. Sibling of detail; both share _adapter.mjs.
+ */
+
+import {pathToFileURL} from 'node:url';
+import {discoverTopics} from '../_adapter.mjs';
+
+/**
+ * @returns {Promise<import('../../../types/docs').DocsListResponse>}
+ */
+export async function list() {
+ const topics = discoverTopics();
+ /** @type {Array<import('../../../types/docs').DocsListEntry>} */
+ const entries = [];
+ for (const [name, docPath] of Object.entries(topics)) {
+ try {
+ const mod = await import(pathToFileURL(docPath).href);
+ entries.push({topic: name, description: mod.docs.description});
+ } catch {
+ entries.push({topic: name, description: ''});
+ }
+ }
+ return {type: 'docs.list', data: entries};
+}