Skip to content

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

TypeScript

refactor(cli): split component.mjs into lib/ modules + lazy command registry (#613)

Joey098003451d0a
diff --git a/packages/cli/src/commands/component.mjs b/packages/cli/src/commands/component.mjs
deleted file mode 100644
index a3af2ba748..0000000000
--- a/packages/cli/src/commands/component.mjs
+++ /dev/null
@@ -1,1273 +0,0 @@
-/**
- * @file component command — List components and print component docs
- *
- * `xds component --list` prints all components grouped by category.
- * `xds component <name>` prints the full component README.
- * `xds component <name> --compact` prints a token-optimized version for LLMs.
- *
- * Component docs live in typed {Name}.doc.mjs files (ComponentDoc exports).
- * This file imports them directly — no markdown parsing needed.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
-import {findCoreDir} from '../utils/paths.mjs';
-
-/**
- * Map top-level src/ directories to display categories.
- * New directories without a mapping will appear under "Other".
- * Adding a new component file to an existing directory requires NO changes here.
- */
-const DIR_TO_CATEGORY = {
- // Layout
- AspectRatio: 'Layout',
- Center: 'Layout',
- CollapsibleGroup: 'Layout',
- Grid: 'Layout',
- Layout: 'Layout',
- Stack: 'Layout',
- // Display
- Avatar: 'Display',
- Badge: 'Display',
- Divider: 'Display',
- Icon: 'Display',
- Skeleton: 'Display',
- Table: 'Display',
- Text: 'Display',
- // Form
- CheckboxInput: 'Form',
- DateInput: 'Form',
- Field: 'Form',
- NumberInput: 'Form',
- RadioList: 'Form',
- Selector: 'Form',
- Slider: 'Form',
- Switch: 'Form',
- TextArea: 'Form',
- TextInput: 'Form',
- TimeInput: 'Form',
- // Action
- Button: 'Action',
- CloseButton: 'Action',
- DropdownMenu: 'Action',
- Link: 'Action',
- // Navigation
- TabList: 'Navigation',
- TopNav: 'Navigation',
- // Overlay
- Calendar: 'Overlay',
- Dialog: 'Overlay',
- Layer: 'Overlay',
-};
-
-const CATEGORY_ORDER = ['Layout', 'Display', 'Form', 'Action', 'Navigation', 'Overlay'];
-const SKIP_DIRS = new Set(['theme', 'hooks', 'utils', '__tests__', 'node_modules']);
-
-/**
- * Auto-discover components by scanning for XDS*.tsx files in core/src/.
- * Groups them by category using the DIR_TO_CATEGORY mapping.
- */
-export function discoverComponents(coreDir) {
- const srcDir = path.join(coreDir, 'src');
- const categories = {};
-
- function collectXDSFiles(dirPath) {
- const results = [];
- if (!fs.existsSync(dirPath)) return results;
- const entries = fs.readdirSync(dirPath, {withFileTypes: true});
- for (const entry of entries) {
- if (entry.isDirectory()) {
- results.push(...collectXDSFiles(path.join(dirPath, entry.name)));
- } else if (
- /^XDS[A-Z]\w+\.tsx$/.test(entry.name) &&
- !entry.name.includes('.test.') &&
- !entry.name.includes('Context.')
- ) {
- results.push(entry.name);
- }
- }
- return results;
- }
-
- const topEntries = fs.readdirSync(srcDir, {withFileTypes: true});
- for (const entry of topEntries) {
- if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
-
- const category = DIR_TO_CATEGORY[entry.name] || 'Other';
- const xdsFiles = collectXDSFiles(path.join(srcDir, entry.name));
-
- for (const fileName of xdsFiles) {
- const componentName = fileName.replace(/^XDS/, '').replace(/\.tsx$/, '');
- if (!categories[category]) categories[category] = [];
- if (!categories[category].includes(componentName)) {
- categories[category].push(componentName);
- }
- }
- }
-
- // Sort components within each category
- for (const cat of Object.keys(categories)) {
- categories[cat].sort();
- }
-
- // Return in defined order
- const ordered = {};
- for (const cat of CATEGORY_ORDER) {
- if (categories[cat]) ordered[cat] = categories[cat];
- }
- // Append any categories not in CATEGORY_ORDER (e.g. "Other")
- for (const cat of Object.keys(categories)) {
- if (!ordered[cat]) ordered[cat] = categories[cat];
- }
-
- return ordered;
-}
-
-/**
- * Merge a TranslationDoc overlay onto a base ComponentDoc.
- * Replaces prose fields (description, features, notes, accessibility, keyboard,
- * prop descriptions) while keeping structure (props, examples, types, defaults).
- */
-function mergeTranslation(docs, translation) {
- if (!translation) return docs;
-
- const merged = {...docs};
- if (translation.description) merged.description = translation.description;
- if (translation.features) merged.features = translation.features;
- if (translation.notes) merged.notes = translation.notes;
- if (translation.accessibility) merged.accessibility = translation.accessibility;
- if (translation.keyboard) merged.keyboard = translation.keyboard;
-
- // Merge prop descriptions for single-component docs
- if (translation.propDescriptions && merged.props) {
- merged.props = merged.props.map(prop => {
- const desc = translation.propDescriptions[prop.name];
- return desc != null ? {...prop, description: desc} : prop;
- });
- }
-
- // Merge sub-component translations
- if (translation.components && merged.components) {
- merged.components = merged.components.map((comp, i) => {
- const trans = translation.components.find(t => t.name === comp.name)
- || translation.components[i];
- if (!trans) return comp;
-
- const mergedComp = {...comp};
- if (trans.description) mergedComp.description = trans.description;
- if (trans.propDescriptions && comp.props) {
- mergedComp.props = comp.props.map(prop => {
- const desc = trans.propDescriptions[prop.name];
- return desc != null ? {...prop, description: desc} : prop;
- });
- }
- return mergedComp;
- });
- }
-
- return merged;
-}
-
-/**
- * Load the typed docs object from a .doc.mjs file.
- * Supports --lang flag: 'zh' for Chinese, 'dense' for compressed format.
- * Also supports legacy --zh and --dense flags.
- * Translations are merged onto the base docs, keeping structure intact.
- */
-export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {}) {
- const mod = await import(pathToFileURL(readmePath).href);
- const docs = mod.docs;
-
- // Resolve which translation to use (--lang takes priority over legacy flags)
- const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
- if (!locale) return docs;
-
- const translationKey = locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
- if (!translationKey || !mod[translationKey]) return docs;
-
- const translation = mod[translationKey];
-
- // If the translation is a full ComponentDoc (legacy docsZh shape), return it directly
- if (translation.props || translation.components?.some(c => c.props)) {
- return translation;
- }
-
- // Otherwise it's a TranslationDoc — merge it onto docs
- return mergeTranslation(docs, translation);
-}
-
-/**
- * Find the doc file for a component, checking both top-level
- * and nested directories. Prefers {Name}.doc.mjs, then README.md
- * (for backward compatibility).
- */
-export function findComponentReadme(coreDir, name) {
- const srcDir = path.join(coreDir, 'src');
- // Preferred: {Name}.doc.mjs, then README.md
- const docNames = [`${name}.doc.mjs`, 'README.md'];
-
- for (const docName of docNames) {
- // Direct match: src/{name}/{Name}.doc.mjs (or README.md)
- const direct = path.join(srcDir, name, docName);
- if (fs.existsSync(direct)) return direct;
- }
-
- // Nested match: src/*/{name}/{Name}.doc.mjs (or README.md)
- const entries = fs.readdirSync(srcDir, {withFileTypes: true});
- for (const docName of docNames) {
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
- const nested = path.join(srcDir, entry.name, name, docName);
- if (fs.existsSync(nested)) return nested;
- }
- }
-
- // Fallback: find the directory containing XDS{name}.tsx,
- // then return the doc file in that directory or nearest parent
- const sourcePath = findComponentSource(coreDir, name);
- if (sourcePath) {
- let dir = path.dirname(sourcePath);
- while (dir.startsWith(srcDir)) {
- for (const docName of docNames) {
- const docFile = path.join(dir, docName);
- if (fs.existsSync(docFile)) return docFile;
- }
- dir = path.dirname(dir);
- }
- }
-
- return null;
-}
-
-/**
- * Find the main source file for a component (XDS*.tsx, excluding tests).
- * For "Button" finds src/Button/XDSButton.tsx
- * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
- * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
- */
-export function findComponentSource(coreDir, name) {
- const srcDir = path.join(coreDir, 'src');
- const xdsName = `XDS${name}.tsx`;
-
- function searchDir(dirPath) {
- if (!fs.existsSync(dirPath)) return null;
- const entries = fs.readdirSync(dirPath, {withFileTypes: true});
-
- // Check for exact match first
- const exact = path.join(dirPath, xdsName);
- if (fs.existsSync(exact)) return exact;
-
- // Recurse into subdirectories
- for (const entry of entries) {
- if (entry.isDirectory()) {
- const found = searchDir(path.join(dirPath, entry.name));
- if (found) return found;
- }
- }
- return null;
- }
-
- // Search in the component's directory
- const directDir = path.join(srcDir, name);
- if (fs.existsSync(directDir)) {
- const found = searchDir(directDir);
- if (found) return found;
- }
-
- // Search nested (component might be under a parent dir)
- const entries = fs.readdirSync(srcDir, {withFileTypes: true});
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
- const nestedDir = path.join(srcDir, entry.name, name);
- if (fs.existsSync(nestedDir)) {
- const found = searchDir(nestedDir);
- if (found) return found;
- }
- }
-
- // Fallback: search entire src tree for the file
- return searchDir(srcDir);
-}
-
-/**
- * Compute the Levenshtein (edit) distance between two strings.
- * Used for fuzzy-matching component names. Dependency-free.
- */
-export function levenshteinDistance(a, b) {
- const m = a.length, n = b.length;
- const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
- for (let i = 0; i <= m; i++) dp[i][0] = i;
- for (let j = 0; j <= n; j++) dp[0][j] = j;
- for (let i = 1; i <= m; i++) {
- for (let j = 1; j <= n; j++) {
- dp[i][j] = a[i-1] === b[j-1]
- ? dp[i-1][j-1]
- : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
- }
- }
- return dp[m][n];
-}
-
-/**
- * Find the closest component names to a given (possibly misspelled) name.
- * Returns matches sorted by distance, filtered to maxDistance.
- */
-export function findClosestComponents(name, components, maxDistance = 3) {
- const allNames = Object.values(components).flat();
- const needle = name.toLowerCase();
-
- const matches = allNames
- .map(comp => ({
- name: comp,
- distance: levenshteinDistance(needle, comp.toLowerCase()),
- }))
- .filter(m => m.distance <= maxDistance)
- .sort((a, b) => a.distance - b.distance);
-
- return matches;
-}
-
-/**
- * Resolve the import path for a component.
- * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.
- */
-export function resolveImportPath(coreDir, componentName) {
- const srcDir = path.join(coreDir, 'src');
- const sourcePath = findComponentSource(coreDir, componentName);
- if (!sourcePath) return '@xds/core';
-
- // Get the top-level directory under src/ from the source path
- const relToSrc = path.relative(srcDir, sourcePath);
- const topDir = relToSrc.split(path.sep)[0];
-
- // Check package.json exports for ./${topDir}
- const pkgPath = path.join(coreDir, 'package.json');
- if (fs.existsSync(pkgPath)) {
- const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
- if (pkg.exports && pkg.exports[`./${topDir}`]) {
- return `@xds/core/${topDir}`;
- }
- }
-
- return '@xds/core';
-}
-
-// ── Legacy markdown-parsing functions ────────────────────────────────
-// These are kept for backward compatibility with existing tests.
-// The CLI action handler uses the new format functions below instead.
-
-/**
- * Minimal cleanup for full docs (default mode).
- * Strips SYNC comments, rewrites title, collapses blank lines.
- */
-export function cleanReadme(content, componentName) {
- const displayName = componentName.startsWith('XDS')
- ? componentName
- : componentName.charAt(0).toUpperCase() + componentName.slice(1);
-
- const lines = content.split('\n');
- const output = [];
-
- for (const line of lines) {
- if (line.includes('<!-- SYNC:') || line.includes('SYNC:')) continue;
-
- if (line.startsWith('# /')) {
- output.push(`# ${displayName}`);
- continue;
- }
-
- output.push(line);
- }
-
- // Collapse consecutive blank lines
- const cleaned = [];
- let prevEmpty = false;
- for (const line of output) {
- const isEmpty = line.trim() === '';
- if (isEmpty && prevEmpty) continue;
- cleaned.push(line);
- prevEmpty = isEmpty;
- }
-
- // Trim trailing blank lines
- while (cleaned.length > 0 && cleaned[cleaned.length - 1].trim() === '') {
- cleaned.pop();
- }
-
- return cleaned.join('\n') + '\n';
-}
-
-// Sections to skip in compact mode
-const COMPACT_SKIP_SECTIONS = [
- 'Files',
- 'RTL Support',
- 'Related',
- 'Dividers',
- 'Components',
- 'Overview',
-];
-const MAX_EXAMPLES = 3;
-
-/**
- * Extract compact docs for LLM consumption.
- * Keeps: title, description, Features, Usage (limited examples), Props, Implementation Notes.
- * Drops: Files, RTL Support, Related, ASCII art, overflow code blocks.
- */
-export function extractCompact(content, componentName) {
- const lines = content.split('\n');
- const output = [];
- let inSkipSection = false;
- let inCodeBlock = false;
- let codeBlockCount = 0;
- let skipCurrentBlock = false;
- let currentSection = null;
-
- const displayName = componentName.startsWith('XDS')
- ? componentName
- : componentName.charAt(0).toUpperCase() + componentName.slice(1);
-
- for (let i = 0; i < lines.length; i++) {
- const line = lines[i];
-
- if (line.startsWith('```')) {
- if (!inCodeBlock) {
- inCodeBlock = true;
- const nextLine = lines[i + 1] || '';
- const isAsciiBlock =
- /^[┌┐└┘├┤┬┴┼─│\s]+$/.test(nextLine) ||
- /^\s*[│├└┌]/.test(nextLine);
- if (isAsciiBlock) {
- skipCurrentBlock = true;
- continue;
- }
- if (codeBlockCount >= MAX_EXAMPLES) {
- skipCurrentBlock = true;
- continue;
- }
- codeBlockCount++;
- skipCurrentBlock = false;
- } else {
- inCodeBlock = false;
- if (skipCurrentBlock) {
- skipCurrentBlock = false;
- continue;
- }
- }
- }
-
- if (inCodeBlock && skipCurrentBlock) continue;
-
- const sectionMatch = line.match(/^##\s+(.+)$/);
- if (sectionMatch) {
- const sectionName = sectionMatch[1].trim();
- codeBlockCount = 0;
-
- if (COMPACT_SKIP_SECTIONS.some(s => sectionName.includes(s))) {
- inSkipSection = true;
- currentSection = sectionName;
- continue;
- }
- inSkipSection = false;
- currentSection = sectionName;
- }
-
- const subsectionMatch = line.match(/^###\s+(.+)$/);
- if (
- subsectionMatch &&
- currentSection === 'Usage' &&
- codeBlockCount >= MAX_EXAMPLES
- ) {
- continue;
- }
-
- if (inSkipSection) continue;
- if (line.includes('<!-- SYNC:') || line.includes('SYNC:')) continue;
- if (
- /^[┌┐└┘├┤┬┴┼─│\s]+$/.test(line) ||
- /^\s*[│├└┌]\s*/.test(line)
- ) {
- continue;
- }
-
- if (line.startsWith('# /')) {
- output.push(`# ${displayName}`);
- continue;
- }
-
- output.push(line);
- }
-
- while (output.length > 0 && output[output.length - 1].trim() === '') {
- output.pop();
- }
-
- const cleaned = [];
- let prevEmpty = false;
- for (const line of output) {
- const isEmpty = line.trim() === '';
- if (isEmpty && prevEmpty) continue;
- cleaned.push(line);
- prevEmpty = isEmpty;
- }
-
- return cleaned.join('\n') + '\n';
-}
-
-/**
- * Extract a brief, LLM-optimized summary from a README.
- *
- * Format: component signature + key props + one usage example.
- * Targets ~200-400 chars per component (vs ~2-3KB for --compact).
- *
- * Example output:
- * Button(variant: primary|secondary|ghost|destructive, size: sm|md|lg)
- * label: string (required) · isLoading isDisabled icon tooltip children
- * <XDSButton variant="primary" onClick={fn}>Save</XDSButton>
- */
-export function extractBrief(content, componentName, importHint) {
- const displayName = componentName.startsWith('XDS')
- ? componentName
- : `XDS${componentName}`;
-
- const lines = content.split('\n');
-
- // 1. Extract first paragraph as description
- let description = '';
- for (let i = 0; i < lines.length; i++) {
- const line = lines[i].trim();
- if (line.startsWith('#')) continue;
- if (line === '') continue;
- if (line.startsWith('|') || line.startsWith('```')) break;
- description = line;
- break;
- }
-
- // 2. Extract props from the Props table
- // Supports two README layouts:
- // a) Single-component: `## Props` section with a table
- // b) Multi-component: `### XDSComponentName` subsection with a table
- const props = [];
- let inPropsTable = false;
- let headerParsed = false;
- let inComponentSection = false;
-
- // For multi-component READMEs, find the section for this specific component
- const componentSectionRe = new RegExp(
- `^###\\s+${displayName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`
- );
-
- for (const line of lines) {
- // Detect `## Props` (single-component layout)
- if (/^#{2,3}\s+Props/.test(line)) {
- inPropsTable = true;
- headerParsed = false;
- continue;
- }
-
- // Detect `### XDSComponentName` (multi-component layout)
- if (componentSectionRe.test(line)) {
- inComponentSection = true;
- continue;
- }
-
- // Exit component section when hitting another ### heading
- if (inComponentSection && /^###\s+/.test(line) && !componentSectionRe.test(line)) {
- inComponentSection = false;
- if (inPropsTable) inPropsTable = false;
- continue;
- }
-
- // Within a component section, a pipe-delimited table is a props table
- if (inComponentSection && !inPropsTable && /^\|\s*`?Prop/.test(line)) {
- inPropsTable = true;
- headerParsed = false;
- // Don't continue — let the header row logic below handle it
- }
-
- if (inPropsTable && /^#{2,3}\s+/.test(line) && !/Props/.test(line) && !inComponentSection) {
- inPropsTable = false;
- continue;
- }
- if (!inPropsTable) continue;
-
- // Skip table header separator
- if (/^\|\s*-/.test(line)) {
- headerParsed = true;
- continue;
- }
- // Skip the header row itself
- if (!headerParsed && /^\|\s*`?Prop/.test(line)) continue;
-
- // Parse prop row: | `name` | `type` | `default` | description |
- const cells = line
- .split('|')
- .map(c => c.trim().replace(/`/g, ''))
- .filter(Boolean);
- if (cells.length >= 3) {
- const name = cells[0];
- const type = cells[1];
- const defaultVal = cells[2] || '';
- const desc = cells[3] || '';
-
- // Skip internal/style props
- if (['xstyle', 'data-testid', 'className', 'style'].includes(name))
- continue;
-
- props.push({name, type, defaultVal, desc});
- }
- }
-
- // 3. Build signature line from variant/size/type/level props
- const signatureProps = [];
- const otherProps = [];
-
- for (const prop of props) {
- // Props with union types go in the signature
- if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
- const values = prop.type
- .replace(/['"]/g, '')
- .split('|')
- .map(v => v.trim())
- .join('|');
- signatureProps.push(`${prop.name}: ${values}`);
- } else if (prop.desc.includes('required') || prop.defaultVal === '—' || prop.defaultVal === '-') {
- otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
- } else {
- otherProps.push(prop.name);
- }
- }
-
- // 4. Extract first code example
- // For multi-component READMEs, prefer examples from the component's section
- let example = '';
- let fallbackExample = '';
- let inCode = false;
- let inCompSection = false;
-
- for (const line of lines) {
- // Track whether we're in this component's subsection
- if (componentSectionRe.test(line)) {
- inCompSection = true;
- continue;
- }
- if (inCompSection && /^###\s+/.test(line) && !componentSectionRe.test(line)) {
- inCompSection = false;
- }
-
- if (line.startsWith('```tsx') || line.startsWith('```jsx')) {
- inCode = true;
- continue;
- }
- if (inCode && line.startsWith('```')) {
- inCode = false;
- continue;
- }
- if (inCode) {
- const trimmed = line.trim();
- // Take the first substantial JSX line
- if (trimmed.startsWith('<XDS') || trimmed.startsWith('<')) {
- if (inCompSection && !example) {
- // Prefer example from this component's section
- example = trimmed;
- } else if (!fallbackExample) {
- // Fallback: first example from anywhere in the README
- fallbackExample = trimmed;
- }
- if (example) break; // Found one in the right section, done
- }
- }
- }
- // Use component-section example if found, otherwise fallback
- if (!example) example = fallbackExample;
-
- // 5. Build output
- const output = [];
-
- // Signature line
- const sigStr =
- signatureProps.length > 0
- ? `${displayName}(${signatureProps.join(', ')})`
- : displayName;
- output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);
-
- // Description (shortened)
- if (description) {
- const shortDesc =
- description.length > 80
- ? description.slice(0, 77) + '...'
- : description;
- output.push(` ${shortDesc}`);
- }
-
- // Other props
- if (otherProps.length > 0) {
- output.push(` ${otherProps.join(' · ')}`);
- }
-
- // Example
- if (example) {
- output.push(` ${example}`);
- }
-
- // Warn on stderr when extraction is incomplete (doesn't pollute brief output)
- if (props.length === 0) {
- console.warn(
- `⚠️ No props found for ${displayName}. Ensure README has a '### ${displayName}' section with a props table.`,
- );
- }
- if (!example) {
- console.warn(`⚠️ No code example found for ${displayName}.`);
- }
-
- return output.join('\n') + '\n';
-}
-
-/**
- * Extract brief summaries for ALL components in one output.
- * One read, zero round-trips — the LLM gets enough to use any component.
- */
-export function extractBriefAll(coreDir) {
- const components = discoverComponents(coreDir);
- const output = [];
-
- // Add xstyle override hint at the top
- output.push(
- `> **Style overrides:** Most components accept an \`xstyle\` prop.`,
- `> Use inline objects for simple overrides: \`xstyle={{ maxWidth: 300 }}\``,
- `> Use \`stylex.create()\` for pseudo-classes/media queries or 3+ properties.`,
- `> See \`npx xds docs principles\` for details.\n`,
- );
-
- for (const [category, comps] of Object.entries(components)) {
- output.push(`## ${category}\n`);
- for (const comp of comps) {
- const readmePath = findComponentReadme(coreDir, comp);
- if (readmePath) {
- const content = fs.readFileSync(readmePath, 'utf-8');
- const importPath = resolveImportPath(coreDir, comp);
- output.push(extractBrief(content, comp, importPath));
- } else {
- output.push(`XDS${comp}\n (no docs)\n`);
- }
- }
- }
-
- return output.join('\n');
-}
-
-/**
- * Ensure compact output includes an import statement.
- * If the output already contains `from '@xds/core`, returns as-is.
- * Otherwise, injects an ## Import section after the title/description,
- * before the first ## section.
- */
-export function ensureImportStatement(compactOutput, componentName, coreDir) {
- // Already has an Import section — return as-is
- if (/^## Import$/m.test(compactOutput)) {
- return compactOutput;
- }
-
- const displayName = componentName.startsWith('XDS')
- ? componentName
- : `XDS${componentName}`;
-
- const importPath = resolveImportPath(coreDir, componentName);
- const importBlock = `## Import\n\n\`\`\`tsx\nimport { ${displayName} } from '${importPath}';\n\`\`\`\n`;
-
- // Find the first ## section and inject before it
- const lines = compactOutput.split('\n');
- const output = [];
- let injected = false;
-
- for (let i = 0; i < lines.length; i++) {
- if (!injected && lines[i].startsWith('## ')) {
- output.push(importBlock);
- injected = true;
- }
- output.push(lines[i]);
- }
-
- // If no ## section found, append at the end
- if (!injected) {
- output.push('');
- output.push(importBlock);
- }
-
- return output.join('\n');
-}
-
-/**
- * Extract only the Props section(s) from a README.
- * Useful for quick reference and LLM context.
- */
-export function extractProps(content, componentName) {
- const lines = content.split('\n');
- const output = [];
- let inPropsSection = false;
- let sectionDepth = 0;
-
- for (const line of lines) {
- // Detect Props section (## Props or ### XDSFoo Props)
- if (/^#{2,3}\s+.*Props/.test(line)) {
- inPropsSection = true;
- sectionDepth = line.match(/^(#+)/)[1].length;
- output.push(line);
- continue;
- }
-
- // Exit props section when hitting another section at same or higher level
- if (inPropsSection && /^#{2,3}\s+/.test(line) && !line.includes('Props')) {
- const depth = line.match(/^(#+)/)[1].length;
- if (depth <= sectionDepth) {
- inPropsSection = false;
- continue;
- }
- }
-
- if (inPropsSection) {
- output.push(line);
- }
- }
-
- if (output.length === 0) {
- return `No props documentation found for ${componentName}.\n`;
- }
-
- // Trim trailing blank lines
- while (output.length > 0 && output[output.length - 1].trim() === '') {
- output.pop();
- }
-
- return output.join('\n') + '\n';
-}
-
-// ── Format functions ────────────────────────────────────────────────
-// These operate on the typed ComponentDoc object directly.
-// Used by the CLI action handler for .doc.mjs files.
-
-/**
- * Render a props array as a markdown table.
- */
-function formatPropsTable(props) {
- if (!props || props.length === 0) return '';
- const lines = [];
- lines.push('| Prop | Type | Default | Description |');
- lines.push('|------|------|---------|-------------|');
- for (const p of props) {
- const def = p.default ? `\`${p.default}\`` : '—';
- const req = p.required ? ' **(required)**' : '';
- lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
- }
- return lines.join('\n');
-}
-
-/**
- * Format full component docs (default mode, replaces cleanReadme).
- */
-export function formatFull(docs) {
- const sections = [];
-
- sections.push(`# ${docs.name}\n`);
- sections.push(docs.description + '\n');
-
- if (docs.features?.length) {
- sections.push('## Features\n');
- sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');
- }
-
- // Single component props
- if ('props' in docs) {
- sections.push('## Props\n');
- sections.push(formatPropsTable(docs.props) + '\n');
- }
-
- // Multi-component
- if ('components' in docs) {
- sections.push('## Components\n');
- for (const comp of docs.components) {
- sections.push(`### ${comp.name}\n`);
- sections.push(comp.description + '\n');
- sections.push(formatPropsTable(comp.props) + '\n');
- if (comp.examples?.length) {
- for (const ex of comp.examples) {
- if (ex.label) sections.push(`#### ${ex.label}\n`);
- sections.push('```tsx\n' + ex.code + '\n```\n');
- }
- }
- }
- }
-
- if (docs.examples?.length) {
- sections.push('## Examples\n');
- for (const ex of docs.examples) {
- if (ex.label) sections.push(`### ${ex.label}\n`);
- sections.push('```tsx\n' + ex.code + '\n```\n');
- }
- }
-
- if (docs.theming) {
- sections.push('## Theming\n');
- sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);
- if (docs.theming.surfaces?.length) {
- const surfaceLines = [];
- surfaceLines.push('| Surface | Description |');
- surfaceLines.push('|---------|-------------|');
- for (const s of docs.theming.surfaces) {
- surfaceLines.push(`| \`${s.name}\` | ${s.description} |`);
- }
- sections.push(surfaceLines.join('\n') + '\n');
- }
- }
-
- if (docs.accessibility?.length) {
- sections.push('## Accessibility\n');
- sections.push(docs.accessibility.map(a => `- ${a}`).join('\n') + '\n');
- }
-
- if (docs.keyboard) {
- sections.push('## Keyboard\n');
- sections.push(docs.keyboard + '\n');
- }
-
- if (docs.notes?.length) {
- sections.push('## Notes\n');
- sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');
- }
-
- return sections.join('\n');
-}
-
-/**
- * Format compact docs for LLM consumption (replaces extractCompact + ensureImportStatement).
- * Includes: import, features, props, limited examples, keyboard, notes.
- */
-export function formatCompact(docs, componentName, importHint) {
- const displayName = componentName.startsWith('XDS')
- ? componentName
- : `XDS${componentName}`;
-
- const sections = [];
-
- sections.push(`# ${docs.name}\n`);
- sections.push(docs.description + '\n');
-
- // Import statement
- if (importHint) {
- sections.push('## Import\n');
- sections.push(`\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`);
- }
-
- if (docs.features?.length) {
- sections.push('## Features\n');
- sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');
- }
-
- // Props
- if ('props' in docs) {
- sections.push('## Props\n');
- sections.push(formatPropsTable(docs.props) + '\n');
- }
-
- if ('components' in docs) {
- for (const comp of docs.components) {
- sections.push(`### ${comp.name}\n`);
- sections.push(comp.description + '\n');
- sections.push(formatPropsTable(comp.props) + '\n');
- }
- }
-
- // Limited examples (max 3)
- const examples = docs.examples?.slice(0, 3) || [];
- if (examples.length) {
- sections.push('## Usage\n');
- for (const ex of examples) {
- if (ex.label) sections.push(`### ${ex.label}\n`);
- sections.push('```tsx\n' + ex.code + '\n```\n');
- }
- }
-
- if (docs.keyboard) {
- sections.push('## Keyboard\n');
- sections.push(docs.keyboard + '\n');
- }
-
- if (docs.notes?.length) {
- sections.push('## Notes\n');
- sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');
- }
-
- return sections.join('\n');
-}
-
-/**
- * Format a brief, LLM-optimized summary (replaces extractBrief).
- *
- * Format: component signature + key props + one usage example.
- * Targets ~200-400 chars per component (vs ~2-3KB for --compact).
- *
- * For multi-component docs, extracts the entry matching componentName.
- */
-export function formatBrief(docs, componentName, importHint) {
- const displayName = componentName.startsWith('XDS')
- ? componentName
- : `XDS${componentName}`;
-
- // Find the right props and examples for this component
- let props = [];
- let description = docs.description;
- let examples = docs.examples || [];
-
- if ('props' in docs) {
- props = docs.props;
- } else if ('components' in docs) {
- const entry = docs.components.find(c => c.name === displayName);
- if (entry) {
- props = entry.props;
- description = entry.description;
- examples = entry.examples || docs.examples || [];
- }
- }
-
- // Build signature from union-type props
- const signatureProps = [];
- const otherProps = [];
-
- for (const prop of props) {
- if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
- const values = prop.type
- .replace(/['"]/g, '')
- .split('|')
- .map(v => v.trim())
- .join('|');
- signatureProps.push(`${prop.name}: ${values}`);
- } else if (prop.required) {
- otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
- } else {
- otherProps.push(prop.name);
- }
- }
-
- // Build output
- const output = [];
-
- // Signature line
- const sigStr =
- signatureProps.length > 0
- ? `${displayName}(${signatureProps.join(', ')})`
- : displayName;
- output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);
-
- // Description (shortened)
- if (description) {
- const shortDesc =
- description.length > 80
- ? description.slice(0, 77) + '...'
- : description;
- output.push(` ${shortDesc}`);
- }
-
- // Other props
- if (otherProps.length > 0) {
- output.push(` ${otherProps.join(' · ')}`);
- }
-
- // First code example
- if (examples.length > 0) {
- const code = examples[0].code;
- const codeLine =
- code.split('\n').find(l => l.trim().startsWith('<XDS')) ||
- code.split('\n')[0];
- output.push(` ${codeLine.trim()}`);
- }
-
- return output.join('\n') + '\n';
-}
-
-/**
- * Format only the props tables (replaces extractProps).
- */
-export function formatProps(docs, componentName) {
- if ('props' in docs) {
- return `## Props\n\n${formatPropsTable(docs.props)}\n`;
- }
-
- if ('components' in docs) {
- const sections = [];
- for (const comp of docs.components) {
- sections.push(`### ${comp.name} Props\n`);
- sections.push(formatPropsTable(comp.props) + '\n');
- }
- return sections.join('\n');
- }
-
- return `No props documentation found for ${componentName}.\n`;
-}
-
-/**
- * Format brief summaries for ALL components in one output.
- */
-export async function formatBriefAll(coreDir, {zh = false, lang} = {}) {
- const components = discoverComponents(coreDir);
- const output = [];
-
- for (const [category, comps] of Object.entries(components)) {
- output.push(`## ${category}\n`);
- for (const comp of comps) {
- const readmePath = findComponentReadme(coreDir, comp);
- if (readmePath && readmePath.endsWith('.doc.mjs')) {
- const docs = await loadDocs(readmePath, {zh, lang});
- const importPath = resolveImportPath(coreDir, comp);
- output.push(formatBrief(docs, comp, importPath));
- } else if (readmePath) {
- // Legacy README.md path
- const content = fs.readFileSync(readmePath, 'utf-8');
- const importPath = resolveImportPath(coreDir, comp);
- output.push(extractBrief(content, comp, importPath));
- } else {
- output.push(`XDS${comp}\n (no docs)\n`);
- }
- }
- }
-
- return output.join('\n');
-}
-
-export function registerComponent(program) {
- program
- .command('component [name]')
- .description('List components or print component docs')
- .option('--list', 'List all components grouped by category')
- .option('--category <category>', 'List components in a specific category')
- .option('--compact', 'Token-optimized output for LLMs')
- .option('--brief', 'Minimal LLM output: signature + props + one example (~200 chars)')
- .option('--brief-all', 'Brief summaries of ALL components in one output')
- .option('--props', 'Print only the props table')
- .option('--source', 'Print component source code')
- .action(async (name, options) => {
- const coreDir = findCoreDir(process.cwd());
- const zh = program.opts().zh || false;
- const dense = program.opts().dense || false;
- const lang = program.opts().lang || null;
-
- if (!coreDir) {
- console.error(
- 'Error: Could not find @xds/core package.\n' +
- 'Make sure you are inside the XDS monorepo or have @xds/core installed.',
- );
- process.exit(1);
- }
-
- if (options.briefAll) {
- console.log(await formatBriefAll(coreDir, {zh, lang}));
- return;
- }
-
- if (options.category || options.list || !name) {
- const components = discoverComponents(coreDir);
-
- if (options.category) {
- const cat = options.category;
- const match = Object.entries(components).find(
- ([key]) => key.toLowerCase() === cat.toLowerCase(),
- );
- if (!match) {
- console.error(`Error: Unknown category "${cat}".`);
- console.error(
- `Available categories: ${Object.keys(components).join(', ')}`,
- );
- process.exit(1);
- }
- console.log(`\n${match[0]}:`);
- for (const comp of match[1]) {
- console.log(` ${comp}`);
- }
- console.log('');
- return;
- }
-
- console.log('');
- for (const [category, comps] of Object.entries(components)) {
- console.log(`${category}:`);
- for (const comp of comps) {
- console.log(` ${comp}`);
- }
- console.log('');
- }
- console.log('Usage: npx xds component <name>');
- console.log('');
- return;
- }
-
- // Normalize: strip XDS prefix for directory lookup
- const dirName = name.replace(/^XDS/, '');
-
- if (options.source) {
- const sourcePath = findComponentSource(coreDir, dirName);
- if (!sourcePath) {
- console.error(`Error: Source for "${name}" not found.`);
- process.exit(1);
- }
- const source = fs.readFileSync(sourcePath, 'utf-8');
- console.log(source);
- return;
- }
-
- let readmePath = findComponentReadme(coreDir, dirName);
- let resolvedName = dirName;
-
- if (!readmePath) {
- // Try fuzzy matching
- const components = discoverComponents(coreDir);
- const closest = findClosestComponents(dirName, components);
-
- if (closest.length === 1) {
- resolvedName = closest[0].name;
- readmePath = findComponentReadme(coreDir, resolvedName);
- if (readmePath) {
- console.log(`Did you mean ${resolvedName}?\n`);
- }
- } else if (closest.length > 1) {
- console.error(`Component "${name}" not found. Did you mean one of these?\n`);
- for (const match of closest) {
- console.error(` ${match.name}`);
- }
- console.error('');
- process.exit(1);
- }
-
- if (!readmePath) {
- console.error(`Error: Component "${name}" not found.`);
- console.error('Run `npx xds component --list` to see available components.');
- process.exit(1);
- }
- }
-
- if (readmePath.endsWith('.doc.mjs')) {
- const docs = await loadDocs(readmePath, {zh, dense, lang});
- const importHint = resolveImportPath(coreDir, resolvedName);
- if (options.props) {
- console.log(formatProps(docs, resolvedName));
- } else if (options.brief) {
- console.log(formatBrief(docs, resolvedName, importHint));
- } else if (options.compact) {
- console.log(formatCompact(docs, resolvedName, importHint));
- } else {
- console.log(formatFull(docs));
- }
- } else {
- // Legacy path for README.md files
- const content = fs.readFileSync(readmePath, 'utf-8');
- if (options.props) {
- console.log(extractProps(content, resolvedName));
- } else if (options.brief) {
- console.log(extractBrief(content, resolvedName));
- } else if (options.compact) {
- const compact = extractCompact(content, resolvedName);
- console.log(ensureImportStatement(compact, resolvedName, coreDir));
- } else {
- console.log(cleanReadme(content, resolvedName));
- }
- }
- });
-}
diff --git a/packages/cli/src/commands/component.test.mjs b/packages/cli/src/commands/component.test.mjs
index 75e25d0418..110619873a 100644
--- a/packages/cli/src/commands/component.test.mjs
+++ b/packages/cli/src/commands/component.test.mjs
@@ -11,7 +11,7 @@ import {
findComponentSource,
levenshteinDistance,
findClosestComponents,
-} from './component.mjs';
+} from './component/index.mjs';
let tmpDir;
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
new file mode 100644
index 0000000000..91ef1b4301
--- /dev/null
+++ b/packages/cli/src/commands/component/index.mjs
@@ -0,0 +1,181 @@
+/**
+ * @file component command — List components and print component docs
+ *
+ * Subcommands: list, search, metadata, props, examples, example, source
+ * Global options: --detail brief|normal, --lang en|zh|dense
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findCoreDir} from '../../utils/paths.mjs';
+import {
+ discoverComponents,
+ findComponentReadme,
+ findComponentSource,
+ resolveImportPath,
+} from '../../lib/component-discovery.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {
+ formatFull,
+ formatCompact,
+ formatBrief,
+ formatProps,
+ formatBriefAll,
+} from '../../lib/component-format.mjs';
+import {
+ cleanReadme,
+ extractCompact,
+ extractBrief,
+ extractBriefAll,
+ ensureImportStatement,
+ extractProps,
+} from '../../lib/component-legacy.mjs';
+import {findClosestComponents} from '../../lib/string-utils.mjs';
+
+export function registerComponent(program) {
+ program
+ .command('component [name]')
+ .description('List components or print component docs')
+ .option('--list', 'List all components grouped by category')
+ .option('--category <category>', 'List components in a specific category')
+ .option('--compact', 'Token-optimized output for LLMs')
+ .option('--brief', 'Minimal LLM output: signature + props + one example (~200 chars)')
+ .option('--brief-all', 'Brief summaries of ALL components in one output')
+ .option('--props', 'Print only the props table')
+ .option('--source', 'Print component source code')
+ .action(async (name, options) => {
+ const coreDir = findCoreDir(process.cwd());
+ const zh = program.opts().zh || false;
+ const dense = program.opts().dense || false;
+ const lang = program.opts().lang || null;
+
+ if (!coreDir) {
+ console.error(
+ 'Error: Could not find @xds/core package.\n' +
+ 'Make sure you are inside the XDS monorepo or have @xds/core installed.',
+ );
+ process.exit(1);
+ }
+
+ if (options.briefAll) {
+ console.log(await formatBriefAll(coreDir, {zh, lang}));
+ return;
+ }
+
+ if (options.category || options.list || !name) {
+ const components = discoverComponents(coreDir);
+
+ if (options.category) {
+ const cat = options.category;
+ const match = Object.entries(components).find(
+ ([key]) => key.toLowerCase() === cat.toLowerCase(),
+ );
+ if (!match) {
+ console.error(`Error: Unknown category "${cat}".`);
+ console.error(
+ `Available categories: ${Object.keys(components).join(', ')}`,
+ );
+ process.exit(1);
+ }
+ console.log(`\n${match[0]}:`);
+ for (const comp of match[1]) {
+ console.log(` ${comp}`);
+ }
+ console.log('');
+ return;
+ }
+
+ console.log('');
+ for (const [category, comps] of Object.entries(components)) {
+ console.log(`${category}:`);
+ for (const comp of comps) {
+ console.log(` ${comp}`);
+ }
+ console.log('');
+ }
+ console.log('Usage: npx xds component <name>');
+ console.log('');
+ return;
+ }
+
+ // Normalize: strip XDS prefix for directory lookup
+ const dirName = name.replace(/^XDS/, '');
+
+ if (options.source) {
+ const sourcePath = findComponentSource(coreDir, dirName);
+ if (!sourcePath) {
+ console.error(`Error: Source for "${name}" not found.`);
+ process.exit(1);
+ }
+ const source = fs.readFileSync(sourcePath, 'utf-8');
+ console.log(source);
+ return;
+ }
+
+ let readmePath = findComponentReadme(coreDir, dirName);
+ let resolvedName = dirName;
+
+ if (!readmePath) {
+ // Try fuzzy matching
+ const components = discoverComponents(coreDir);
+ const closest = findClosestComponents(dirName, components);
+
+ if (closest.length === 1) {
+ resolvedName = closest[0].name;
+ readmePath = findComponentReadme(coreDir, resolvedName);
+ if (readmePath) {
+ console.log(`Did you mean ${resolvedName}?\n`);
+ }
+ } else if (closest.length > 1) {
+ console.error(`Component "${name}" not found. Did you mean one of these?\n`);
+ for (const match of closest) {
+ console.error(` ${match.name}`);
+ }
+ console.error('');
+ process.exit(1);
+ }
+
+ if (!readmePath) {
+ console.error(`Error: Component "${name}" not found.`);
+ console.error('Run `npx xds component --list` to see available components.');
+ process.exit(1);
+ }
+ }
+
+ if (readmePath.endsWith('.doc.mjs')) {
+ const docs = await loadDocs(readmePath, {zh, dense, lang});
+ const importHint = resolveImportPath(coreDir, resolvedName);
+ if (options.props) {
+ console.log(formatProps(docs, resolvedName));
+ } else if (options.brief) {
+ console.log(formatBrief(docs, resolvedName, importHint));
+ } else if (options.compact) {
+ console.log(formatCompact(docs, resolvedName, importHint));
+ } else {
+ console.log(formatFull(docs));
+ }
+ } else {
+ // Legacy path for README.md files
+ const content = fs.readFileSync(readmePath, 'utf-8');
+ if (options.props) {
+ console.log(extractProps(content, resolvedName));
+ } else if (options.brief) {
+ console.log(extractBrief(content, resolvedName));
+ } else if (options.compact) {
+ const compact = extractCompact(content, resolvedName);
+ console.log(ensureImportStatement(compact, resolvedName, coreDir));
+ } else {
+ console.log(cleanReadme(content, resolvedName));
+ }
+ }
+ });
+}
+
+
+// Re-export lib functions for backward compatibility
+// (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
+export {discoverComponents, findComponentReadme, findComponentSource, resolveImportPath} from '../../lib/component-discovery.mjs';
+export {loadDocs} from '../../lib/component-loader.mjs';
+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
+export {cleanReadme, extractCompact, extractBrief, extractBriefAll, ensureImportStatement, extractProps} from '../../lib/component-legacy.mjs';
+export {levenshteinDistance, findClosestComponents} from '../../lib/string-utils.mjs';
diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjs
index d0ffd9a2a4..fbc9d92cbc 100644
--- a/packages/cli/src/index.mjs
+++ b/packages/cli/src/index.mjs
@@ -1,19 +1,15 @@
/**
* @file XDS CLI — Commander program setup
*
- * Registers all commands: init, swizzle, agent-docs, component, docs, template.
+ * Registers all commands via lazy loading. If one command fails to load
+ * (bad import, syntax error), the other commands still work.
*/
import {Command} from 'commander';
-import {registerInit} from './commands/init.mjs';
-import {registerSwizzle} from './commands/swizzle.mjs';
-import {registerAgentDocs} from './commands/agent-docs.mjs';
-import {registerComponent} from './commands/component.mjs';
-import {registerDocs} from './commands/docs.mjs';
-import {registerTemplate} from './commands/template.mjs';
-import {registerGapReport} from './commands/gap-report.mjs';
-import {registerUpgrade} from './commands/upgrade.mjs';
-import {registerTheme} from './commands/build-theme.mjs';
+import {fileURLToPath} from 'node:url';
+import * as path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
export const program = new Command();
@@ -29,15 +25,38 @@ program
program.help();
});
-registerInit(program);
-registerComponent(program);
-registerDocs(program);
-registerSwizzle(program);
-registerAgentDocs(program);
-registerTemplate(program);
-registerGapReport(program);
-registerUpgrade(program);
-registerTheme(program);
+/**
+ * Command registry — each command is lazy-loaded so a broken command
+ * doesn't take down the entire CLI.
+ */
+const commands = [
+ {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
+ {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
+ {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
+ {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
+ {name: 'agent-docs', path: './commands/agent-docs.mjs', register: 'registerAgentDocs'},
+ {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
+ {name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
+ {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
+ {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
+];
+
+for (const cmd of commands) {
+ try {
+ const mod = await import(cmd.path);
+ mod[cmd.register](program);
+ } catch (e) {
+ // Command fails to load but CLI still works
+ program
+ .command(cmd.name)
+ .description(`(failed to load: ${e.message})`)
+ .action(() => {
+ console.error(`Command "${cmd.name}" failed to load:`);
+ console.error(e.message);
+ process.exit(1);
+ });
+ }
+}
// Hidden command used by package.json postinstall scripts
program
diff --git a/packages/cli/src/lib/component-discovery.mjs b/packages/cli/src/lib/component-discovery.mjs
new file mode 100644
index 0000000000..0c39c2f934
--- /dev/null
+++ b/packages/cli/src/lib/component-discovery.mjs
@@ -0,0 +1,238 @@
+/**
+ * @file Component discovery — find, list, and resolve XDS components
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DIR_TO_CATEGORY = {
+ // Layout
+ AspectRatio: 'Layout',
+ Center: 'Layout',
+ CollapsibleGroup: 'Layout',
+ Grid: 'Layout',
+ Layout: 'Layout',
+ Stack: 'Layout',
+ // Display
+ Avatar: 'Display',
+ Badge: 'Display',
+ Divider: 'Display',
+ Icon: 'Display',
+ Skeleton: 'Display',
+ Table: 'Display',
+ Text: 'Display',
+ // Form
+ CheckboxInput: 'Form',
+ DateInput: 'Form',
+ Field: 'Form',
+ NumberInput: 'Form',
+ RadioList: 'Form',
+ Selector: 'Form',
+ Slider: 'Form',
+ Switch: 'Form',
+ TextArea: 'Form',
+ TextInput: 'Form',
+ TimeInput: 'Form',
+ // Action
+ Button: 'Action',
+ CloseButton: 'Action',
+ DropdownMenu: 'Action',
+ Link: 'Action',
+ // Navigation
+ TabList: 'Navigation',
+ TopNav: 'Navigation',
+ // Overlay
+ Calendar: 'Overlay',
+ Dialog: 'Overlay',
+ Layer: 'Overlay',
+};
+
+const CATEGORY_ORDER = ['Layout', 'Display', 'Form', 'Action', 'Navigation', 'Overlay'];
+const SKIP_DIRS = new Set(['theme', 'hooks', 'utils', '__tests__', 'node_modules']);
+
+/**
+ * Auto-discover components by scanning for XDS*.tsx files in core/src/.
+ * Groups them by category using the DIR_TO_CATEGORY mapping.
+ */
+export function discoverComponents(coreDir) {
+ const srcDir = path.join(coreDir, 'src');
+ const categories = {};
+
+ function collectXDSFiles(dirPath) {
+ const results = [];
+ if (!fs.existsSync(dirPath)) return results;
+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+ for (const entry of entries) {
+ if (entry.isDirectory()) {
+ results.push(...collectXDSFiles(path.join(dirPath, entry.name)));
+ } else if (
+ /^XDS[A-Z]\w+\.tsx$/.test(entry.name) &&
+ !entry.name.includes('.test.') &&
+ !entry.name.includes('Context.')
+ ) {
+ results.push(entry.name);
+ }
+ }
+ return results;
+ }
+
+ const topEntries = fs.readdirSync(srcDir, {withFileTypes: true});
+ for (const entry of topEntries) {
+ if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+
+ const category = DIR_TO_CATEGORY[entry.name] || 'Other';
+ const xdsFiles = collectXDSFiles(path.join(srcDir, entry.name));
+
+ for (const fileName of xdsFiles) {
+ const componentName = fileName.replace(/^XDS/, '').replace(/\.tsx$/, '');
+ if (!categories[category]) categories[category] = [];
+ if (!categories[category].includes(componentName)) {
+ categories[category].push(componentName);
+ }
+ }
+ }
+
+ // Sort components within each category
+ for (const cat of Object.keys(categories)) {
+ categories[cat].sort();
+ }
+
+ // Return in defined order
+ const ordered = {};
+ for (const cat of CATEGORY_ORDER) {
+ if (categories[cat]) ordered[cat] = categories[cat];
+ }
+ // Append any categories not in CATEGORY_ORDER (e.g. "Other")
+ for (const cat of Object.keys(categories)) {
+ if (!ordered[cat]) ordered[cat] = categories[cat];
+ }
+
+ return ordered;
+}
+
+/**
+ * Merge a TranslationDoc overlay onto a base ComponentDoc.
+ * Replaces prose fields (description, features, notes, accessibility, keyboard,
+ * prop descriptions) while keeping structure (props, examples, types, defaults).
+ */
+export function findComponentReadme(coreDir, name) {
+ const srcDir = path.join(coreDir, 'src');
+ // Preferred: {Name}.doc.mjs, then README.md
+ const docNames = [`${name}.doc.mjs`, 'README.md'];
+
+ for (const docName of docNames) {
+ // Direct match: src/{name}/{Name}.doc.mjs (or README.md)
+ const direct = path.join(srcDir, name, docName);
+ if (fs.existsSync(direct)) return direct;
+ }
+
+ // Nested match: src/*/{name}/{Name}.doc.mjs (or README.md)
+ const entries = fs.readdirSync(srcDir, {withFileTypes: true});
+ for (const docName of docNames) {
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const nested = path.join(srcDir, entry.name, name, docName);
+ if (fs.existsSync(nested)) return nested;
+ }
+ }
+
+ // Fallback: find the directory containing XDS{name}.tsx,
+ // then return the doc file in that directory or nearest parent
+ const sourcePath = findComponentSource(coreDir, name);
+ if (sourcePath) {
+ let dir = path.dirname(sourcePath);
+ while (dir.startsWith(srcDir)) {
+ for (const docName of docNames) {
+ const docFile = path.join(dir, docName);
+ if (fs.existsSync(docFile)) return docFile;
+ }
+ dir = path.dirname(dir);
+ }
+ }
+
+ return null;
+}
+
+/**
+ * Find the main source file for a component (XDS*.tsx, excluding tests).
+ * For "Button" finds src/Button/XDSButton.tsx
+ * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
+ * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
+ */
+export function findComponentSource(coreDir, name) {
+ const srcDir = path.join(coreDir, 'src');
+ const xdsName = `XDS${name}.tsx`;
+
+ function searchDir(dirPath) {
+ if (!fs.existsSync(dirPath)) return null;
+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+
+ // Check for exact match first
+ const exact = path.join(dirPath, xdsName);
+ if (fs.existsSync(exact)) return exact;
+
+ // Recurse into subdirectories
+ for (const entry of entries) {
+ if (entry.isDirectory()) {
+ const found = searchDir(path.join(dirPath, entry.name));
+ if (found) return found;
+ }
+ }
+ return null;
+ }
+
+ // Search in the component's directory
+ const directDir = path.join(srcDir, name);
+ if (fs.existsSync(directDir)) {
+ const found = searchDir(directDir);
+ if (found) return found;
+ }
+
+ // Search nested (component might be under a parent dir)
+ const entries = fs.readdirSync(srcDir, {withFileTypes: true});
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const nestedDir = path.join(srcDir, entry.name, name);
+ if (fs.existsSync(nestedDir)) {
+ const found = searchDir(nestedDir);
+ if (found) return found;
+ }
+ }
+
+ // Fallback: search entire src tree for the file
+ return searchDir(srcDir);
+}
+
+/**
+ * Compute the Levenshtein (edit) distance between two strings.
+ * Used for fuzzy-matching component names. Dependency-free.
+ */
+export function resolveImportPath(coreDir, componentName) {
+ const srcDir = path.join(coreDir, 'src');
+ const sourcePath = findComponentSource(coreDir, componentName);
+ if (!sourcePath) return '@xds/core';
+
+ // Get the top-level directory under src/ from the source path
+ const relToSrc = path.relative(srcDir, sourcePath);
+ const topDir = relToSrc.split(path.sep)[0];
+
+ // Check package.json exports for ./${topDir}
+ const pkgPath = path.join(coreDir, 'package.json');
+ if (fs.existsSync(pkgPath)) {
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+ if (pkg.exports && pkg.exports[`./${topDir}`]) {
+ return `@xds/core/${topDir}`;
+ }
+ }
+
+ return '@xds/core';
+}
+
+// ── Legacy markdown-parsing functions ────────────────────────────────
+// These are kept for backward compatibility with existing tests.
+// The CLI action handler uses the new format functions below instead.
+
+/**
+ * Minimal cleanup for full docs (default mode).
+ * Strips SYNC comments, rewrites title, collapses blank lines.
+ */
\ No newline at end of file
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
new file mode 100644
index 0000000000..069515374e
--- /dev/null
+++ b/packages/cli/src/lib/component-format.mjs
@@ -0,0 +1,292 @@
+/**
+ * @file Component doc formatting — render ComponentDoc objects to text
+ */
+
+import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
+import {loadDocs} from './component-loader.mjs';
+import {extractBrief} from './component-legacy.mjs';
+import * as fs from 'node:fs';
+
+function formatPropsTable(props) {
+ if (!props || props.length === 0) return '';
+ const lines = [];
+ lines.push('| Prop | Type | Default | Description |');
+ lines.push('|------|------|---------|-------------|');
+ for (const p of props) {
+ const def = p.default ? `\`${p.default}\`` : '—';
+ const req = p.required ? ' **(required)**' : '';
+ lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
+ }
+ return lines.join('\n');
+}
+
+/**
+ * Format full component docs (default mode, replaces cleanReadme).
+ */
+export function formatFull(docs) {
+ const sections = [];
+
+ sections.push(`# ${docs.name}\n`);
+ sections.push(docs.description + '\n');
+
+ if (docs.features?.length) {
+ sections.push('## Features\n');
+ sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');
+ }
+
+ // Single component props
+ if ('props' in docs) {
+ sections.push('## Props\n');
+ sections.push(formatPropsTable(docs.props) + '\n');
+ }
+
+ // Multi-component
+ if ('components' in docs) {
+ sections.push('## Components\n');
+ for (const comp of docs.components) {
+ sections.push(`### ${comp.name}\n`);
+ sections.push(comp.description + '\n');
+ sections.push(formatPropsTable(comp.props) + '\n');
+ if (comp.examples?.length) {
+ for (const ex of comp.examples) {
+ if (ex.label) sections.push(`#### ${ex.label}\n`);
+ sections.push('```tsx\n' + ex.code + '\n```\n');
+ }
+ }
+ }
+ }
+
+ if (docs.examples?.length) {
+ sections.push('## Examples\n');
+ for (const ex of docs.examples) {
+ if (ex.label) sections.push(`### ${ex.label}\n`);
+ sections.push('```tsx\n' + ex.code + '\n```\n');
+ }
+ }
+
+ if (docs.theming) {
+ sections.push('## Theming\n');
+ sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);
+ if (docs.theming.surfaces?.length) {
+ const surfaceLines = [];
+ surfaceLines.push('| Surface | Description |');
+ surfaceLines.push('|---------|-------------|');
+ for (const s of docs.theming.surfaces) {
+ surfaceLines.push(`| \`${s.name}\` | ${s.description} |`);
+ }
+ sections.push(surfaceLines.join('\n') + '\n');
+ }
+ }
+
+ if (docs.accessibility?.length) {
+ sections.push('## Accessibility\n');
+ sections.push(docs.accessibility.map(a => `- ${a}`).join('\n') + '\n');
+ }
+
+ if (docs.keyboard) {
+ sections.push('## Keyboard\n');
+ sections.push(docs.keyboard + '\n');
+ }
+
+ if (docs.notes?.length) {
+ sections.push('## Notes\n');
+ sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');
+ }
+
+ return sections.join('\n');
+}
+
+/**
+ * Format compact docs for LLM consumption (replaces extractCompact + ensureImportStatement).
+ * Includes: import, features, props, limited examples, keyboard, notes.
+ */
+export function formatCompact(docs, componentName, importHint) {
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ const sections = [];
+
+ sections.push(`# ${docs.name}\n`);
+ sections.push(docs.description + '\n');
+
+ // Import statement
+ if (importHint) {
+ sections.push('## Import\n');
+ sections.push(`\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`);
+ }
+
+ if (docs.features?.length) {
+ sections.push('## Features\n');
+ sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');
+ }
+
+ // Props
+ if ('props' in docs) {
+ sections.push('## Props\n');
+ sections.push(formatPropsTable(docs.props) + '\n');
+ }
+
+ if ('components' in docs) {
+ for (const comp of docs.components) {
+ sections.push(`### ${comp.name}\n`);
+ sections.push(comp.description + '\n');
+ sections.push(formatPropsTable(comp.props) + '\n');
+ }
+ }
+
+ // Limited examples (max 3)
+ const examples = docs.examples?.slice(0, 3) || [];
+ if (examples.length) {
+ sections.push('## Usage\n');
+ for (const ex of examples) {
+ if (ex.label) sections.push(`### ${ex.label}\n`);
+ sections.push('```tsx\n' + ex.code + '\n```\n');
+ }
+ }
+
+ if (docs.keyboard) {
+ sections.push('## Keyboard\n');
+ sections.push(docs.keyboard + '\n');
+ }
+
+ if (docs.notes?.length) {
+ sections.push('## Notes\n');
+ sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');
+ }
+
+ return sections.join('\n');
+}
+
+/**
+ * Format a brief, LLM-optimized summary (replaces extractBrief).
+ *
+ * Format: component signature + key props + one usage example.
+ * Targets ~200-400 chars per component (vs ~2-3KB for --compact).
+ *
+ * For multi-component docs, extracts the entry matching componentName.
+ */
+export function formatBrief(docs, componentName, importHint) {
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ // Find the right props and examples for this component
+ let props = [];
+ let description = docs.description;
+ let examples = docs.examples || [];
+
+ if ('props' in docs) {
+ props = docs.props;
+ } else if ('components' in docs) {
+ const entry = docs.components.find(c => c.name === displayName);
+ if (entry) {
+ props = entry.props;
+ description = entry.description;
+ examples = entry.examples || docs.examples || [];
+ }
+ }
+
+ // Build signature from union-type props
+ const signatureProps = [];
+ const otherProps = [];
+
+ for (const prop of props) {
+ if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
+ const values = prop.type
+ .replace(/['"]/g, '')
+ .split('|')
+ .map(v => v.trim())
+ .join('|');
+ signatureProps.push(`${prop.name}: ${values}`);
+ } else if (prop.required) {
+ otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
+ } else {
+ otherProps.push(prop.name);
+ }
+ }
+
+ // Build output
+ const output = [];
+
+ // Signature line
+ const sigStr =
+ signatureProps.length > 0
+ ? `${displayName}(${signatureProps.join(', ')})`
+ : displayName;
+ output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);
+
+ // Description (shortened)
+ if (description) {
+ const shortDesc =
+ description.length > 80
+ ? description.slice(0, 77) + '...'
+ : description;
+ output.push(` ${shortDesc}`);
+ }
+
+ // Other props
+ if (otherProps.length > 0) {
+ output.push(` ${otherProps.join(' · ')}`);
+ }
+
+ // First code example
+ if (examples.length > 0) {
+ const code = examples[0].code;
+ const codeLine =
+ code.split('\n').find(l => l.trim().startsWith('<XDS')) ||
+ code.split('\n')[0];
+ output.push(` ${codeLine.trim()}`);
+ }
+
+ return output.join('\n') + '\n';
+}
+
+/**
+ * Format only the props tables (replaces extractProps).
+ */
+export function formatProps(docs, componentName) {
+ if ('props' in docs) {
+ return `## Props\n\n${formatPropsTable(docs.props)}\n`;
+ }
+
+ if ('components' in docs) {
+ const sections = [];
+ for (const comp of docs.components) {
+ sections.push(`### ${comp.name} Props\n`);
+ sections.push(formatPropsTable(comp.props) + '\n');
+ }
+ return sections.join('\n');
+ }
+
+ return `No props documentation found for ${componentName}.\n`;
+}
+
+/**
+ * Format brief summaries for ALL components in one output.
+ */
+export async function formatBriefAll(coreDir, {zh = false, lang} = {}) {
+ const components = discoverComponents(coreDir);
+ const output = [];
+
+ for (const [category, comps] of Object.entries(components)) {
+ output.push(`## ${category}\n`);
+ for (const comp of comps) {
+ const readmePath = findComponentReadme(coreDir, comp);
+ if (readmePath && readmePath.endsWith('.doc.mjs')) {
+ const docs = await loadDocs(readmePath, {zh, lang});
+ const importPath = resolveImportPath(coreDir, comp);
+ output.push(formatBrief(docs, comp, importPath));
+ } else if (readmePath) {
+ // Legacy README.md path
+ const content = fs.readFileSync(readmePath, 'utf-8');
+ const importPath = resolveImportPath(coreDir, comp);
+ output.push(extractBrief(content, comp, importPath));
+ } else {
+ output.push(`XDS${comp}\n (no docs)\n`);
+ }
+ }
+ }
+
+ return output.join('\n');
+}
diff --git a/packages/cli/src/lib/component-legacy.mjs b/packages/cli/src/lib/component-legacy.mjs
new file mode 100644
index 0000000000..c1ef139879
--- /dev/null
+++ b/packages/cli/src/lib/component-legacy.mjs
@@ -0,0 +1,501 @@
+/**
+ * @file Legacy README.md parsing — extract docs from markdown files
+ *
+ * These functions parse raw README.md content using regex.
+ * They exist for backward compatibility with components that
+ * haven't been converted to .doc.mjs format yet.
+ * Delete this file when all components have .doc.mjs files.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
+
+export function cleanReadme(content, componentName) {
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : componentName.charAt(0).toUpperCase() + componentName.slice(1);
+
+ const lines = content.split('\n');
+ const output = [];
+
+ for (const line of lines) {
+ if (line.includes('<!-- SYNC:') || line.includes('SYNC:')) continue;
+
+ if (line.startsWith('# /')) {
+ output.push(`# ${displayName}`);
+ continue;
+ }
+
+ output.push(line);
+ }
+
+ // Collapse consecutive blank lines
+ const cleaned = [];
+ let prevEmpty = false;
+ for (const line of output) {
+ const isEmpty = line.trim() === '';
+ if (isEmpty && prevEmpty) continue;
+ cleaned.push(line);
+ prevEmpty = isEmpty;
+ }
+
+ // Trim trailing blank lines
+ while (cleaned.length > 0 && cleaned[cleaned.length - 1].trim() === '') {
+ cleaned.pop();
+ }
+
+ return cleaned.join('\n') + '\n';
+}
+
+// Sections to skip in compact mode
+const COMPACT_SKIP_SECTIONS = [
+ 'Files',
+ 'RTL Support',
+ 'Related',
+ 'Dividers',
+ 'Components',
+ 'Overview',
+];
+const MAX_EXAMPLES = 3;
+
+/**
+ * Extract compact docs for LLM consumption.
+ * Keeps: title, description, Features, Usage (limited examples), Props, Implementation Notes.
+ * Drops: Files, RTL Support, Related, ASCII art, overflow code blocks.
+ */
+export function extractCompact(content, componentName) {
+ const lines = content.split('\n');
+ const output = [];
+ let inSkipSection = false;
+ let inCodeBlock = false;
+ let codeBlockCount = 0;
+ let skipCurrentBlock = false;
+ let currentSection = null;
+
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : componentName.charAt(0).toUpperCase() + componentName.slice(1);
+
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i];
+
+ if (line.startsWith('```')) {
+ if (!inCodeBlock) {
+ inCodeBlock = true;
+ const nextLine = lines[i + 1] || '';
+ const isAsciiBlock =
+ /^[┌┐└┘├┤┬┴┼─│\s]+$/.test(nextLine) ||
+ /^\s*[│├└┌]/.test(nextLine);
+ if (isAsciiBlock) {
+ skipCurrentBlock = true;
+ continue;
+ }
+ if (codeBlockCount >= MAX_EXAMPLES) {
+ skipCurrentBlock = true;
+ continue;
+ }
+ codeBlockCount++;
+ skipCurrentBlock = false;
+ } else {
+ inCodeBlock = false;
+ if (skipCurrentBlock) {
+ skipCurrentBlock = false;
+ continue;
+ }
+ }
+ }
+
+ if (inCodeBlock && skipCurrentBlock) continue;
+
+ const sectionMatch = line.match(/^##\s+(.+)$/);
+ if (sectionMatch) {
+ const sectionName = sectionMatch[1].trim();
+ codeBlockCount = 0;
+
+ if (COMPACT_SKIP_SECTIONS.some(s => sectionName.includes(s))) {
+ inSkipSection = true;
+ currentSection = sectionName;
+ continue;
+ }
+ inSkipSection = false;
+ currentSection = sectionName;
+ }
+
+ const subsectionMatch = line.match(/^###\s+(.+)$/);
+ if (
+ subsectionMatch &&
+ currentSection === 'Usage' &&
+ codeBlockCount >= MAX_EXAMPLES
+ ) {
+ continue;
+ }
+
+ if (inSkipSection) continue;
+ if (line.includes('<!-- SYNC:') || line.includes('SYNC:')) continue;
+ if (
+ /^[┌┐└┘├┤┬┴┼─│\s]+$/.test(line) ||
+ /^\s*[│├└┌]\s*/.test(line)
+ ) {
+ continue;
+ }
+
+ if (line.startsWith('# /')) {
+ output.push(`# ${displayName}`);
+ continue;
+ }
+
+ output.push(line);
+ }
+
+ while (output.length > 0 && output[output.length - 1].trim() === '') {
+ output.pop();
+ }
+
+ const cleaned = [];
+ let prevEmpty = false;
+ for (const line of output) {
+ const isEmpty = line.trim() === '';
+ if (isEmpty && prevEmpty) continue;
+ cleaned.push(line);
+ prevEmpty = isEmpty;
+ }
+
+ return cleaned.join('\n') + '\n';
+}
+
+/**
+ * Extract a brief, LLM-optimized summary from a README.
+ *
+ * Format: component signature + key props + one usage example.
+ * Targets ~200-400 chars per component (vs ~2-3KB for --compact).
+ *
+ * Example output:
+ * Button(variant: primary|secondary|ghost|destructive, size: sm|md|lg)
+ * label: string (required) · isLoading isDisabled icon tooltip children
+ * <XDSButton variant="primary" onClick={fn}>Save</XDSButton>
+ */
+export function extractBrief(content, componentName, importHint) {
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ const lines = content.split('\n');
+
+ // 1. Extract first paragraph as description
+ let description = '';
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i].trim();
+ if (line.startsWith('#')) continue;
+ if (line === '') continue;
+ if (line.startsWith('|') || line.startsWith('```')) break;
+ description = line;
+ break;
+ }
+
+ // 2. Extract props from the Props table
+ // Supports two README layouts:
+ // a) Single-component: `## Props` section with a table
+ // b) Multi-component: `### XDSComponentName` subsection with a table
+ const props = [];
+ let inPropsTable = false;
+ let headerParsed = false;
+ let inComponentSection = false;
+
+ // For multi-component READMEs, find the section for this specific component
+ const componentSectionRe = new RegExp(
+ `^###\\s+${displayName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`
+ );
+
+ for (const line of lines) {
+ // Detect `## Props` (single-component layout)
+ if (/^#{2,3}\s+Props/.test(line)) {
+ inPropsTable = true;
+ headerParsed = false;
+ continue;
+ }
+
+ // Detect `### XDSComponentName` (multi-component layout)
+ if (componentSectionRe.test(line)) {
+ inComponentSection = true;
+ continue;
+ }
+
+ // Exit component section when hitting another ### heading
+ if (inComponentSection && /^###\s+/.test(line) && !componentSectionRe.test(line)) {
+ inComponentSection = false;
+ if (inPropsTable) inPropsTable = false;
+ continue;
+ }
+
+ // Within a component section, a pipe-delimited table is a props table
+ if (inComponentSection && !inPropsTable && /^\|\s*`?Prop/.test(line)) {
+ inPropsTable = true;
+ headerParsed = false;
+ // Don't continue — let the header row logic below handle it
+ }
+
+ if (inPropsTable && /^#{2,3}\s+/.test(line) && !/Props/.test(line) && !inComponentSection) {
+ inPropsTable = false;
+ continue;
+ }
+ if (!inPropsTable) continue;
+
+ // Skip table header separator
+ if (/^\|\s*-/.test(line)) {
+ headerParsed = true;
+ continue;
+ }
+ // Skip the header row itself
+ if (!headerParsed && /^\|\s*`?Prop/.test(line)) continue;
+
+ // Parse prop row: | `name` | `type` | `default` | description |
+ const cells = line
+ .split('|')
+ .map(c => c.trim().replace(/`/g, ''))
+ .filter(Boolean);
+ if (cells.length >= 3) {
+ const name = cells[0];
+ const type = cells[1];
+ const defaultVal = cells[2] || '';
+ const desc = cells[3] || '';
+
+ // Skip internal/style props
+ if (['xstyle', 'data-testid', 'className', 'style'].includes(name))
+ continue;
+
+ props.push({name, type, defaultVal, desc});
+ }
+ }
+
+ // 3. Build signature line from variant/size/type/level props
+ const signatureProps = [];
+ const otherProps = [];
+
+ for (const prop of props) {
+ // Props with union types go in the signature
+ if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
+ const values = prop.type
+ .replace(/['"]/g, '')
+ .split('|')
+ .map(v => v.trim())
+ .join('|');
+ signatureProps.push(`${prop.name}: ${values}`);
+ } else if (prop.desc.includes('required') || prop.defaultVal === '—' || prop.defaultVal === '-') {
+ otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
+ } else {
+ otherProps.push(prop.name);
+ }
+ }
+
+ // 4. Extract first code example
+ // For multi-component READMEs, prefer examples from the component's section
+ let example = '';
+ let fallbackExample = '';
+ let inCode = false;
+ let inCompSection = false;
+
+ for (const line of lines) {
+ // Track whether we're in this component's subsection
+ if (componentSectionRe.test(line)) {
+ inCompSection = true;
+ continue;
+ }
+ if (inCompSection && /^###\s+/.test(line) && !componentSectionRe.test(line)) {
+ inCompSection = false;
+ }
+
+ if (line.startsWith('```tsx') || line.startsWith('```jsx')) {
+ inCode = true;
+ continue;
+ }
+ if (inCode && line.startsWith('```')) {
+ inCode = false;
+ continue;
+ }
+ if (inCode) {
+ const trimmed = line.trim();
+ // Take the first substantial JSX line
+ if (trimmed.startsWith('<XDS') || trimmed.startsWith('<')) {
+ if (inCompSection && !example) {
+ // Prefer example from this component's section
+ example = trimmed;
+ } else if (!fallbackExample) {
+ // Fallback: first example from anywhere in the README
+ fallbackExample = trimmed;
+ }
+ if (example) break; // Found one in the right section, done
+ }
+ }
+ }
+ // Use component-section example if found, otherwise fallback
+ if (!example) example = fallbackExample;
+
+ // 5. Build output
+ const output = [];
+
+ // Signature line
+ const sigStr =
+ signatureProps.length > 0
+ ? `${displayName}(${signatureProps.join(', ')})`
+ : displayName;
+ output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);
+
+ // Description (shortened)
+ if (description) {
+ const shortDesc =
+ description.length > 80
+ ? description.slice(0, 77) + '...'
+ : description;
+ output.push(` ${shortDesc}`);
+ }
+
+ // Other props
+ if (otherProps.length > 0) {
+ output.push(` ${otherProps.join(' · ')}`);
+ }
+
+ // Example
+ if (example) {
+ output.push(` ${example}`);
+ }
+
+ // Warn on stderr when extraction is incomplete (doesn't pollute brief output)
+ if (props.length === 0) {
+ console.warn(
+ `⚠️ No props found for ${displayName}. Ensure README has a '### ${displayName}' section with a props table.`,
+ );
+ }
+ if (!example) {
+ console.warn(`⚠️ No code example found for ${displayName}.`);
+ }
+
+ return output.join('\n') + '\n';
+}
+
+/**
+ * Extract brief summaries for ALL components in one output.
+ * One read, zero round-trips — the LLM gets enough to use any component.
+ */
+export function extractBriefAll(coreDir) {
+ const components = discoverComponents(coreDir);
+ const output = [];
+
+ // Add xstyle override hint at the top
+ output.push(
+ `> **Style overrides:** Most components accept an \`xstyle\` prop.`,
+ `> Use inline objects for simple overrides: \`xstyle={{ maxWidth: 300 }}\``,
+ `> Use \`stylex.create()\` for pseudo-classes/media queries or 3+ properties.`,
+ `> See \`npx xds docs principles\` for details.\n`,
+ );
+
+ for (const [category, comps] of Object.entries(components)) {
+ output.push(`## ${category}\n`);
+ for (const comp of comps) {
+ const readmePath = findComponentReadme(coreDir, comp);
+ if (readmePath) {
+ const content = fs.readFileSync(readmePath, 'utf-8');
+ const importPath = resolveImportPath(coreDir, comp);
+ output.push(extractBrief(content, comp, importPath));
+ } else {
+ output.push(`XDS${comp}\n (no docs)\n`);
+ }
+ }
+ }
+
+ return output.join('\n');
+}
+
+/**
+ * Ensure compact output includes an import statement.
+ * If the output already contains `from '@xds/core`, returns as-is.
+ * Otherwise, injects an ## Import section after the title/description,
+ * before the first ## section.
+ */
+export function ensureImportStatement(compactOutput, componentName, coreDir) {
+ // Already has an Import section — return as-is
+ if (/^## Import$/m.test(compactOutput)) {
+ return compactOutput;
+ }
+
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ const importPath = resolveImportPath(coreDir, componentName);
+ const importBlock = `## Import\n\n\`\`\`tsx\nimport { ${displayName} } from '${importPath}';\n\`\`\`\n`;
+
+ // Find the first ## section and inject before it
+ const lines = compactOutput.split('\n');
+ const output = [];
+ let injected = false;
+
+ for (let i = 0; i < lines.length; i++) {
+ if (!injected && lines[i].startsWith('## ')) {
+ output.push(importBlock);
+ injected = true;
+ }
+ output.push(lines[i]);
+ }
+
+ // If no ## section found, append at the end
+ if (!injected) {
+ output.push('');
+ output.push(importBlock);
+ }
+
+ return output.join('\n');
+}
+
+/**
+ * Extract only the Props section(s) from a README.
+ * Useful for quick reference and LLM context.
+ */
+export function extractProps(content, componentName) {
+ const lines = content.split('\n');
+ const output = [];
+ let inPropsSection = false;
+ let sectionDepth = 0;
+
+ for (const line of lines) {
+ // Detect Props section (## Props or ### XDSFoo Props)
+ if (/^#{2,3}\s+.*Props/.test(line)) {
+ inPropsSection = true;
+ sectionDepth = line.match(/^(#+)/)[1].length;
+ output.push(line);
+ continue;
+ }
+
+ // Exit props section when hitting another section at same or higher level
+ if (inPropsSection && /^#{2,3}\s+/.test(line) && !line.includes('Props')) {
+ const depth = line.match(/^(#+)/)[1].length;
+ if (depth <= sectionDepth) {
+ inPropsSection = false;
+ continue;
+ }
+ }
+
+ if (inPropsSection) {
+ output.push(line);
+ }
+ }
+
+ if (output.length === 0) {
+ return `No props documentation found for ${componentName}.\n`;
+ }
+
+ // Trim trailing blank lines
+ while (output.length > 0 && output[output.length - 1].trim() === '') {
+ output.pop();
+ }
+
+ return output.join('\n') + '\n';
+}
+
+// ── Format functions ────────────────────────────────────────────────
+// These operate on the typed ComponentDoc object directly.
+// Used by the CLI action handler for .doc.mjs files.
+
+/**
+ * Render a props array as a markdown table.
+ */
\ No newline at end of file
diff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjs
new file mode 100644
index 0000000000..7da3df958d
--- /dev/null
+++ b/packages/cli/src/lib/component-loader.mjs
@@ -0,0 +1,79 @@
+/**
+ * @file Component doc loader — load and merge translations
+ */
+
+import {pathToFileURL} from 'node:url';
+
+function mergeTranslation(docs, translation) {
+ if (!translation) return docs;
+
+ const merged = {...docs};
+ if (translation.description) merged.description = translation.description;
+ if (translation.features) merged.features = translation.features;
+ if (translation.notes) merged.notes = translation.notes;
+ if (translation.accessibility) merged.accessibility = translation.accessibility;
+ if (translation.keyboard) merged.keyboard = translation.keyboard;
+
+ // Merge prop descriptions for single-component docs
+ if (translation.propDescriptions && merged.props) {
+ merged.props = merged.props.map(prop => {
+ const desc = translation.propDescriptions[prop.name];
+ return desc != null ? {...prop, description: desc} : prop;
+ });
+ }
+
+ // Merge sub-component translations
+ if (translation.components && merged.components) {
+ merged.components = merged.components.map((comp, i) => {
+ const trans = translation.components.find(t => t.name === comp.name)
+ || translation.components[i];
+ if (!trans) return comp;
+
+ const mergedComp = {...comp};
+ if (trans.description) mergedComp.description = trans.description;
+ if (trans.propDescriptions && comp.props) {
+ mergedComp.props = comp.props.map(prop => {
+ const desc = trans.propDescriptions[prop.name];
+ return desc != null ? {...prop, description: desc} : prop;
+ });
+ }
+ return mergedComp;
+ });
+ }
+
+ return merged;
+}
+
+/**
+ * Load the typed docs object from a .doc.mjs file.
+ * Supports --lang flag: 'zh' for Chinese, 'dense' for compressed format.
+ * Also supports legacy --zh and --dense flags.
+ * Translations are merged onto the base docs, keeping structure intact.
+ */
+export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {}) {
+ const mod = await import(pathToFileURL(readmePath).href);
+ const docs = mod.docs;
+
+ // Resolve which translation to use (--lang takes priority over legacy flags)
+ const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
+ if (!locale) return docs;
+
+ const translationKey = locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
+ if (!translationKey || !mod[translationKey]) return docs;
+
+ const translation = mod[translationKey];
+
+ // If the translation is a full ComponentDoc (legacy docsZh shape), return it directly
+ if (translation.props || translation.components?.some(c => c.props)) {
+ return translation;
+ }
+
+ // Otherwise it's a TranslationDoc — merge it onto docs
+ return mergeTranslation(docs, translation);
+}
+
+/**
+ * Find the doc file for a component, checking both top-level
+ * and nested directories. Prefers {Name}.doc.mjs, then README.md
+ * (for backward compatibility).
+ */
\ No newline at end of file
diff --git a/packages/cli/src/lib/string-utils.mjs b/packages/cli/src/lib/string-utils.mjs
new file mode 100644
index 0000000000..ffac63abfe
--- /dev/null
+++ b/packages/cli/src/lib/string-utils.mjs
@@ -0,0 +1,42 @@
+/**
+ * @file String utilities — fuzzy matching for component names
+ */
+
+export function levenshteinDistance(a, b) {
+ const m = a.length, n = b.length;
+ const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
+ for (let i = 0; i <= m; i++) dp[i][0] = i;
+ for (let j = 0; j <= n; j++) dp[0][j] = j;
+ for (let i = 1; i <= m; i++) {
+ for (let j = 1; j <= n; j++) {
+ dp[i][j] = a[i-1] === b[j-1]
+ ? dp[i-1][j-1]
+ : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+ }
+ }
+ return dp[m][n];
+}
+
+/**
+ * Find the closest component names to a given (possibly misspelled) name.
+ * Returns matches sorted by distance, filtered to maxDistance.
+ */
+export function findClosestComponents(name, components, maxDistance = 3) {
+ const allNames = Object.values(components).flat();
+ const needle = name.toLowerCase();
+
+ const matches = allNames
+ .map(comp => ({
+ name: comp,
+ distance: levenshteinDistance(needle, comp.toLowerCase()),
+ }))
+ .filter(m => m.distance <= maxDistance)
+ .sort((a, b) => a.distance - b.distance);
+
+ return matches;
+}
+
+/**
+ * Resolve the import path for a component.
+ * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.
+ */
\ No newline at end of file