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.mdnew file mode 100644index 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).+@josephfarinadiff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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};+}