An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): support external library component discovery (#563)
Joey16dddcf6bb77
diff --git a/packages/cli/src/commands/component.test.mjs b/packages/cli/src/commands/component.test.mjsindex 110619873a..fccedd8309 100644--- a/packages/cli/src/commands/component.test.mjs+++ b/packages/cli/src/commands/component.test.mjs@@ -4,6 +4,8 @@ import * as path from 'node:path';import * as os from 'node:os';import {discoverComponents,+ discoverExternalComponents,+ findExternalComponentDoc,cleanReadme,extractCompact,extractProps,@@ -391,3 +393,115 @@ describe('extractProps', () => {expect(result).toMatch(/\n$/);});});++describe('discoverExternalComponents', () => {+ it('finds .doc.mjs files in the docs directory', () => {+ const docsDir = path.join(tmpDir, 'src');+ const compDir = path.join(docsDir, 'Employee');+ fs.mkdirSync(compDir, {recursive: true});+ fs.writeFileSync(path.join(compDir, 'EmployeeHoverCard.doc.mjs'), '');+ fs.writeFileSync(path.join(compDir, 'EmployeeLink.doc.mjs'), '');++ const result = discoverExternalComponents(docsDir);+ expect(result).toEqual(['EmployeeHoverCard', 'EmployeeLink']);+ });++ it('scans nested directories recursively', () => {+ const docsDir = path.join(tmpDir, 'src');+ const deepDir = path.join(docsDir, 'a', 'b', 'c');+ fs.mkdirSync(deepDir, {recursive: true});+ fs.writeFileSync(path.join(deepDir, 'DeepComponent.doc.mjs'), '');++ const result = discoverExternalComponents(docsDir);+ expect(result).toEqual(['DeepComponent']);+ });++ it('ignores non-.doc.mjs files', () => {+ const docsDir = path.join(tmpDir, 'src');+ fs.mkdirSync(docsDir, {recursive: true});+ fs.writeFileSync(path.join(docsDir, 'Foo.doc.mjs'), '');+ fs.writeFileSync(path.join(docsDir, 'Foo.tsx'), '');+ fs.writeFileSync(path.join(docsDir, 'README.md'), '');+ fs.writeFileSync(path.join(docsDir, 'index.mjs'), '');++ const result = discoverExternalComponents(docsDir);+ expect(result).toEqual(['Foo']);+ });++ it('skips node_modules and __tests__ directories', () => {+ const docsDir = path.join(tmpDir, 'src');+ const nmDir = path.join(docsDir, 'node_modules', 'dep');+ const testDir = path.join(docsDir, '__tests__');+ fs.mkdirSync(nmDir, {recursive: true});+ fs.mkdirSync(testDir, {recursive: true});+ fs.writeFileSync(path.join(nmDir, 'Hidden.doc.mjs'), '');+ fs.writeFileSync(path.join(testDir, 'TestOnly.doc.mjs'), '');+ fs.writeFileSync(path.join(docsDir, 'Visible.doc.mjs'), '');++ const result = discoverExternalComponents(docsDir);+ expect(result).toEqual(['Visible']);+ });++ it('returns empty array for nonexistent directory', () => {+ const result = discoverExternalComponents(path.join(tmpDir, 'nope'));+ expect(result).toEqual([]);+ });++ it('returns sorted results', () => {+ const docsDir = path.join(tmpDir, 'src');+ fs.mkdirSync(docsDir, {recursive: true});+ fs.writeFileSync(path.join(docsDir, 'Zebra.doc.mjs'), '');+ fs.writeFileSync(path.join(docsDir, 'Alpha.doc.mjs'), '');+ fs.writeFileSync(path.join(docsDir, 'Middle.doc.mjs'), '');++ const result = discoverExternalComponents(docsDir);+ expect(result).toEqual(['Alpha', 'Middle', 'Zebra']);+ });+});++describe('findExternalComponentDoc', () => {+ it('finds a doc file by component name', () => {+ const docsDir = path.join(tmpDir, 'src');+ const compDir = path.join(docsDir, 'Employee');+ fs.mkdirSync(compDir, {recursive: true});+ const docPath = path.join(compDir, 'EmployeeHoverCard.doc.mjs');+ fs.writeFileSync(docPath, '');++ const result = findExternalComponentDoc(docsDir, 'EmployeeHoverCard');+ expect(result).toBe(docPath);+ });++ it('searches nested directories', () => {+ const docsDir = path.join(tmpDir, 'src');+ const deepDir = path.join(docsDir, 'nested', 'deep');+ fs.mkdirSync(deepDir, {recursive: true});+ const docPath = path.join(deepDir, 'DeepThing.doc.mjs');+ fs.writeFileSync(docPath, '');++ const result = findExternalComponentDoc(docsDir, 'DeepThing');+ expect(result).toBe(docPath);+ });++ it('returns null when component not found', () => {+ const docsDir = path.join(tmpDir, 'src');+ fs.mkdirSync(docsDir, {recursive: true});++ const result = findExternalComponentDoc(docsDir, 'NonExistent');+ expect(result).toBeNull();+ });++ it('returns null for nonexistent directory', () => {+ const result = findExternalComponentDoc(path.join(tmpDir, 'nope'), 'Foo');+ expect(result).toBeNull();+ });++ it('skips node_modules and __tests__', () => {+ const docsDir = path.join(tmpDir, 'src');+ const nmDir = path.join(docsDir, 'node_modules', 'dep');+ fs.mkdirSync(nmDir, {recursive: true});+ fs.writeFileSync(path.join(nmDir, 'Hidden.doc.mjs'), '');++ const result = findExternalComponentDoc(docsDir, 'Hidden');+ expect(result).toBeNull();+ });+});diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjsindex 14fef2b7b2..88c08ccf72 100644--- a/packages/cli/src/commands/component/index.mjs+++ b/packages/cli/src/commands/component/index.mjs@@ -6,11 +6,13 @@import * as fs from 'node:fs';import * as path from 'node:path';-import {findCoreDir} from '../../utils/paths.mjs';+import {findCoreDir, discoverExternalPackages} from '../../utils/paths.mjs';import {discoverComponents,+ discoverExternalComponents,findComponentReadme,findComponentSource,+ findExternalComponentDoc,resolveImportPath,} from '../../lib/component-discovery.mjs';import {loadDocs} from '../../lib/component-loader.mjs';@@ -119,6 +121,19 @@ export function registerComponent(program) {}console.log('');}+ // Show external packages+ const externals = discoverExternalPackages(process.cwd());+ for (const ext of externals) {+ const extComponents = discoverExternalComponents(ext.docsDir);+ if (extComponents.length > 0) {+ console.log(`${ext.category} (${ext.name}):`);+ for (const comp of extComponents) {+ console.log(` ${comp}`);+ }+ console.log('');+ }+ }+console.log('Usage: npx xds component <name>');console.log('');}@@ -141,6 +156,20 @@ export function registerComponent(program) {let readmePath = findComponentReadme(coreDir, dirName);let resolvedName = dirName;+ let fromExternal = null;++ // If not found in core, check external packages+ if (!readmePath) {+ const externals = discoverExternalPackages(process.cwd());+ for (const ext of externals) {+ const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);+ if (extDocPath) {+ readmePath = extDocPath;+ fromExternal = ext;+ break;+ }+ }+ }if (!readmePath) {// Try fuzzy matching@@ -171,7 +200,7 @@ export function registerComponent(program) {if (readmePath.endsWith('.doc.mjs')) {const docs = await loadDocs(readmePath, {zh, dense, lang});- const importHint = resolveImportPath(coreDir, resolvedName);+ const importHint = fromExternal ? fromExternal.name : resolveImportPath(coreDir, resolvedName);if (options.props) {console.log(formatProps(docs, resolvedName));} else if (detail === 'brief') {@@ -201,7 +230,8 @@ export function registerComponent(program) {// 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 {discoverComponents, discoverExternalComponents, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../lib/component-discovery.mjs';+export {discoverExternalPackages} from '../../utils/paths.mjs';export {loadDocs} from '../../lib/component-loader.mjs';export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';export {cleanReadme, extractCompact, extractBrief, ensureImportStatement, extractProps} from '../../lib/component-legacy.mjs';diff --git a/packages/cli/src/lib/component-discovery.mjs b/packages/cli/src/lib/component-discovery.mjsindex 0c39c2f934..f3bc88aa81 100644--- a/packages/cli/src/lib/component-discovery.mjs+++ b/packages/cli/src/lib/component-discovery.mjs@@ -228,6 +228,59 @@ export function resolveImportPath(coreDir, componentName) {return '@xds/core';}+// ── External package discovery ───────────────────────────────────────++/**+ * Discover components from an external package's docs directory.+ * Scans for *.doc.mjs files and returns their names.+ */+export function discoverExternalComponents(docsDir) {+ if (!fs.existsSync(docsDir)) return [];+ const components = [];++ function scanDir(dirPath) {+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});+ for (const entry of entries) {+ if (entry.name === 'node_modules' || entry.name === '__tests__') continue;+ const fullPath = path.join(dirPath, entry.name);+ if (entry.isDirectory()) {+ scanDir(fullPath);+ } else if (entry.name.endsWith('.doc.mjs')) {+ components.push(entry.name.replace('.doc.mjs', ''));+ }+ }+ }++ scanDir(docsDir);+ return components.sort();+}++/**+ * Find a component's doc file in an external package's docs directory.+ * Returns the path to {Name}.doc.mjs or null.+ */+export function findExternalComponentDoc(docsDir, name) {+ if (!fs.existsSync(docsDir)) return null;+ const target = `${name}.doc.mjs`;++ function scanDir(dirPath) {+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});+ for (const entry of entries) {+ if (entry.name === 'node_modules' || entry.name === '__tests__') continue;+ const fullPath = path.join(dirPath, entry.name);+ if (entry.isDirectory()) {+ const found = scanDir(fullPath);+ if (found) return found;+ } else if (entry.name === target) {+ return fullPath;+ }+ }+ return null;+ }++ return scanDir(docsDir);+}+// ── Legacy markdown-parsing functions ────────────────────────────────// These are kept for backward compatibility with existing tests.// The CLI action handler uses the new format functions below instead.diff --git a/packages/cli/src/utils/paths.mjs b/packages/cli/src/utils/paths.mjsindex 2c5d4ee7f6..4077248294 100644--- a/packages/cli/src/utils/paths.mjs+++ b/packages/cli/src/utils/paths.mjs@@ -67,6 +67,72 @@ export function findProjectRoot(startDir = process.cwd()) {return null;}+/**+ * Discover external XDS-compatible packages from node_modules.+ * Scans for packages with an "xds" field in their package.json:+ *+ * { "xds": { "docs": "./src", "category": "Common" } }+ *+ * Returns array of { name, category, docsDir }.+ */+export function discoverExternalPackages(startDir = process.cwd()) {+ const externals = [];+ let dir = startDir;++ // Walk up to find node_modules+ let nodeModulesDir = null;+ for (let i = 0; i < 5; i++) {+ const candidate = path.join(dir, 'node_modules');+ if (fs.existsSync(candidate)) {+ nodeModulesDir = candidate;+ break;+ }+ const parent = path.dirname(dir);+ if (parent === dir) break;+ dir = parent;+ }++ if (!nodeModulesDir) return externals;++ const scanDir = (searchDir) => {+ if (!fs.existsSync(searchDir)) return;+ const entries = fs.readdirSync(searchDir, {withFileTypes: true});++ for (const entry of entries) {+ if (!entry.isDirectory()) continue;+ if (entry.name.startsWith('.') || entry.name === '.bin') continue;++ const fullPath = path.join(searchDir, entry.name);++ // Recurse into scoped packages (@org/*)+ if (entry.name.startsWith('@')) {+ scanDir(fullPath);+ continue;+ }++ const pkgJsonPath = path.join(fullPath, 'package.json');+ if (!fs.existsSync(pkgJsonPath)) continue;++ try {+ const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));+ if (pkg.name === '@xds/core') continue;+ if (pkg.xds && pkg.xds.docs) {+ externals.push({+ name: pkg.name,+ category: pkg.xds.category || pkg.name,+ docsDir: path.resolve(fullPath, pkg.xds.docs),+ });+ }+ } catch {+ // skip invalid JSON+ }+ }+ };++ scanDir(nodeModulesDir);+ return externals;+}+/*** List available component directories in packages/core/src.* Returns directory names that contain XDS*.tsx files.diff --git a/packages/cli/src/utils/paths.test.mjs b/packages/cli/src/utils/paths.test.mjsindex aa4d616423..e9bfdcebe7 100644--- a/packages/cli/src/utils/paths.test.mjs+++ b/packages/cli/src/utils/paths.test.mjs@@ -2,7 +2,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';import * as fs from 'node:fs';import * as path from 'node:path';import * as os from 'node:os';-import {findCoreDir, findProjectRoot, listComponents} from './paths.mjs';+import {findCoreDir, findProjectRoot, listComponents, discoverExternalPackages} from './paths.mjs';let tmpDir;@@ -64,6 +64,132 @@ describe('findProjectRoot', () => {});});+describe('discoverExternalPackages', () => {+ it('finds packages with an "xds" field in package.json', () => {+ const nm = path.join(tmpDir, 'node_modules');+ const extDir = path.join(nm, 'xds-charts');+ fs.mkdirSync(extDir, {recursive: true});+ fs.writeFileSync(+ path.join(extDir, 'package.json'),+ JSON.stringify({+ name: 'xds-charts',+ xds: {docs: './src', category: 'Data Viz'},+ }),+ );++ const result = discoverExternalPackages(tmpDir);+ expect(result).toEqual([+ {+ name: 'xds-charts',+ category: 'Data Viz',+ docsDir: path.join(extDir, 'src'),+ },+ ]);+ });++ it('handles scoped packages (@org/pkg)', () => {+ const nm = path.join(tmpDir, 'node_modules');+ const scopedDir = path.join(nm, '@acme', 'xds-widgets');+ fs.mkdirSync(scopedDir, {recursive: true});+ fs.writeFileSync(+ path.join(scopedDir, 'package.json'),+ JSON.stringify({+ name: '@acme/xds-widgets',+ xds: {docs: './lib', category: 'Widgets'},+ }),+ );++ const result = discoverExternalPackages(tmpDir);+ expect(result).toEqual([+ {+ name: '@acme/xds-widgets',+ category: 'Widgets',+ docsDir: path.join(scopedDir, 'lib'),+ },+ ]);+ });++ it('skips @xds/core', () => {+ const nm = path.join(tmpDir, 'node_modules');+ const coreDir = path.join(nm, '@xds', 'core');+ fs.mkdirSync(coreDir, {recursive: true});+ fs.writeFileSync(+ path.join(coreDir, 'package.json'),+ JSON.stringify({+ name: '@xds/core',+ xds: {docs: './src'},+ }),+ );++ const result = discoverExternalPackages(tmpDir);+ expect(result).toEqual([]);+ });++ it('skips packages without "xds" field', () => {+ const nm = path.join(tmpDir, 'node_modules');+ const extDir = path.join(nm, 'some-lib');+ fs.mkdirSync(extDir, {recursive: true});+ fs.writeFileSync(+ path.join(extDir, 'package.json'),+ JSON.stringify({name: 'some-lib'}),+ );++ const result = discoverExternalPackages(tmpDir);+ expect(result).toEqual([]);+ });++ it('defaults category to package name when not specified', () => {+ const nm = path.join(tmpDir, 'node_modules');+ const extDir = path.join(nm, 'my-components');+ fs.mkdirSync(extDir, {recursive: true});+ fs.writeFileSync(+ path.join(extDir, 'package.json'),+ JSON.stringify({+ name: 'my-components',+ xds: {docs: './docs'},+ }),+ );++ const result = discoverExternalPackages(tmpDir);+ expect(result[0].category).toBe('my-components');+ });++ it('returns empty array when no node_modules found', () => {+ const result = discoverExternalPackages(tmpDir);+ expect(result).toEqual([]);+ });++ it('walks up directories to find node_modules', () => {+ const nm = path.join(tmpDir, 'node_modules');+ const extDir = path.join(nm, 'xds-ext');+ fs.mkdirSync(extDir, {recursive: true});+ fs.writeFileSync(+ path.join(extDir, 'package.json'),+ JSON.stringify({+ name: 'xds-ext',+ xds: {docs: './src'},+ }),+ );++ const nested = path.join(tmpDir, 'packages', 'app');+ fs.mkdirSync(nested, {recursive: true});++ const result = discoverExternalPackages(nested);+ expect(result).toHaveLength(1);+ expect(result[0].name).toBe('xds-ext');+ });++ it('handles invalid JSON in package.json gracefully', () => {+ const nm = path.join(tmpDir, 'node_modules');+ const extDir = path.join(nm, 'bad-json');+ fs.mkdirSync(extDir, {recursive: true});+ fs.writeFileSync(path.join(extDir, 'package.json'), '{not valid json!!!');++ const result = discoverExternalPackages(tmpDir);+ expect(result).toEqual([]);+ });+});+describe('listComponents', () => {it('returns sorted component directory names, skipping hooks/theme/utils', () => {const srcDir = path.join(tmpDir, 'src');diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex da7cdbd7a0..60c74d50a1 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -111,3 +111,17 @@ export * from './utils';// Themeexport * from './theme';++// Doc types — for external library authors writing .doc.mjs files+export type {+ ComponentDoc,+ SingleComponentDoc,+ MultiComponentDoc,+ PropDoc,+ Example,+ ComponentEntry,+ ThemingTarget,+ CSSPropertyDoc,+ ComponentVar,+ TranslationDoc,+} from './docs-types';