An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): correct --detail level ordering on list views (#2522)
Joey8e953819953b
diff --git a/packages/cli/README.md b/packages/cli/README.mdindex da9dc56185..ca09f81b37 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -30,7 +30,7 @@ npx xds template --listThese flags work with any command:- `--json` — Output as typed JSON envelope: `{ type, data }`-- `--detail <level>` — Detail level: `full`, `compact`, or `brief`+- `--detail <level>` — Detail level for list views, increasing in size: `brief` (names only, default for `--list`) < `compact` (names + 1-line descriptions) < `full` (full docs per entry). Single-item views default to `full`.- `--zh` — Output docs in Chinese Simplified- `--dense` — Compressed format (token-efficient, useful for AI agents)- `--lang <locale>` — Language/format shorthand (`en`, `zh`, `dense`)@@ -111,37 +111,40 @@ detail.data.name; // already narrowedEvery response has a `type` string that uniquely identifies it:-| Command | Type | Response |-| ----------------------------------------- | --------------------------- | --------------------------------- |-| `xds --json component [--list]` | `component.list` | `ComponentListResponse` |-| `xds --json component --detail brief` | `component.brief` | `ComponentBriefResponse` |-| `xds --json component <name>` | `component.detail` | `ComponentDetailResponse` |-| `xds --json component <name> --props` | `component.detail.props` | `ComponentDetailPropsResponse` |-| `xds --json component <name> --source` | `component.detail.source` | `ComponentDetailSourceResponse` |-| `xds --json component <name> --showcase` | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |-| `xds --json component <name> --blocks` | `component.detail.blocks` | `ComponentDetailBlocksResponse` |-| `xds --json discover` | `discover.list` | `DiscoverListResponse` |-| `xds --json discover @scope/name` | `discover.detail` | `DiscoverDetailResponse` |-| `xds --json discover @scope/name/Comp` | `discover.detail.doc` | `DiscoverDetailDocResponse` |-| `xds --json discover <search>` | `discover.search` | `DiscoverSearchResponse` |-| `xds --json docs` | `docs.list` | `DocsListResponse` |-| `xds --json docs <topic>` | `docs.detail` | `DocsDetailResponse` |-| `xds --json docs <topic> <section>` | `docs.detail.section` | `DocsDetailSectionResponse` |-| `xds --json template [--list]` | `template.list` | `TemplateListResponse` |-| `xds --json template <name>` | `template.show` | `TemplateShowResponse` |-| `xds --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` |-| `xds --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` |-| `xds --json hook [--list]` | `hook.list` | `HookListResponse` |-| `xds --json hook <name>` | `hook.detail` | `HookDetailResponse` |-| `xds --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` |-| `xds --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` |-| `xds --json theme build <file>` | `theme.build` | `ThemeBuildResponse` |-| `xds --json upgrade --list` | `upgrade.list` | `UpgradeListResponse` |-| `xds --json upgrade [--apply]` | `upgrade.run` | `UpgradeRunResponse` |-| `xds --json gap-report --list-categories` | `gap-report.categories` | `GapReportCategoriesResponse` |-| `xds --json gap-report --component X ...` | `gap-report.file` | `GapReportFileResponse` |-| any error | — | `CLIError` |-| unsupported command | — | `CLIUnsupportedError` |+| Command | Type | Response |+| ---------------------------------------------- | --------------------------- | --------------------------------- |+| `xds --json component [--list]` | `component.list` | `ComponentListResponse` |+| `xds --json component --list --detail compact` | `component.brief` | `ComponentBriefResponse` |+| `xds --json component --list --detail full` | `component.full` | `ComponentFullResponse` |+| `xds --json component <name>` | `component.detail` | `ComponentDetailResponse` |+| `xds --json component <name> --props` | `component.detail.props` | `ComponentDetailPropsResponse` |+| `xds --json component <name> --source` | `component.detail.source` | `ComponentDetailSourceResponse` |+| `xds --json component <name> --showcase` | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |+| `xds --json component <name> --blocks` | `component.detail.blocks` | `ComponentDetailBlocksResponse` |+| `xds --json discover` | `discover.list` | `DiscoverListResponse` |+| `xds --json discover @scope/name` | `discover.detail` | `DiscoverDetailResponse` |+| `xds --json discover @scope/name/Comp` | `discover.detail.doc` | `DiscoverDetailDocResponse` |+| `xds --json discover <search>` | `discover.search` | `DiscoverSearchResponse` |+| `xds --json docs` | `docs.list` | `DocsListResponse` |+| `xds --json docs <topic>` | `docs.detail` | `DocsDetailResponse` |+| `xds --json docs <topic> <section>` | `docs.detail.section` | `DocsDetailSectionResponse` |+| `xds --json template [--list]` | `template.list` | `TemplateListResponse` |+| `xds --json template <name>` | `template.show` | `TemplateShowResponse` |+| `xds --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` |+| `xds --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` |+| `xds --json hook [--list]` | `hook.list` | `HookListResponse` |+| `xds --json hook --list --detail compact` | `hook.brief` | (untyped envelope) |+| `xds --json hook --list --detail full` | `hook.full` | (untyped envelope) |+| `xds --json hook <name>` | `hook.detail` | `HookDetailResponse` |+| `xds --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` |+| `xds --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` |+| `xds --json theme build <file>` | `theme.build` | `ThemeBuildResponse` |+| `xds --json upgrade --list` | `upgrade.list` | `UpgradeListResponse` |+| `xds --json upgrade [--apply]` | `upgrade.run` | `UpgradeRunResponse` |+| `xds --json gap-report --list-categories` | `gap-report.categories` | `GapReportCategoriesResponse` |+| `xds --json gap-report --component X ...` | `gap-report.file` | `GapReportFileResponse` |+| any error | — | `CLIError` |+| unsupported command | — | `CLIUnsupportedError` |## Configurationdiff --git a/packages/cli/src/api/component.mjs b/packages/cli/src/api/component.mjsindex 4efe4b95b0..1288b9b24d 100644--- a/packages/cli/src/api/component.mjs+++ b/packages/cli/src/api/component.mjs@@ -88,7 +88,7 @@ export async function component(name, options = {}) {);}- if (detail === 'brief') {+ if (detail === 'compact') {const entries = [];for (const comp of match[1]) {const readme = findComponentReadme(coreDir, comp);@@ -106,11 +106,29 @@ export async function component(name, options = {}) {return {type: 'component.brief', data: {[match[0]]: entries}};}+ if (detail === 'full') {+ const entries = [];+ for (const comp of match[1]) {+ const readme = findComponentReadme(coreDir, comp);+ if (readme && readme.endsWith('.doc.mjs')) {+ try {+ entries.push(await loadDocs(readme, {zh, lang, dense}));+ } catch {+ entries.push({name: `XDS${comp}`, description: ''});+ }+ } else {+ entries.push({name: `XDS${comp}`, description: ''});+ }+ }+ return {type: 'component.full', data: {[match[0]]: entries}};+ }++ // Default: brief — names onlyreturn {type: 'component.list', data: {[match[0]]: match[1]}};}// All components — merge core + external packages with grouped subcategories- if (detail === 'brief') {+ if (detail === 'compact') {/** @type {Record<string, Array<import('../types/component').ComponentBriefEntry>>} */const result = {};for (const [cat, comps] of Object.entries(components)) {@@ -132,6 +150,28 @@ export async function component(name, options = {}) {return {type: 'component.brief', data: result};}+ if (detail === 'full') {+ /** @type {Record<string, Array<unknown>>} */+ const result = {};+ for (const [cat, comps] of Object.entries(components)) {+ result[cat] = [];+ for (const comp of comps) {+ const readme = findComponentReadme(coreDir, comp);+ if (readme && readme.endsWith('.doc.mjs')) {+ try {+ result[cat].push(await loadDocs(readme, {zh, lang, dense}));+ } catch {+ result[cat].push({name: `XDS${comp}`, description: ''});+ }+ } else {+ result[cat].push({name: `XDS${comp}`, description: ''});+ }+ }+ }+ return {type: 'component.full', data: result};+ }++ // Default: brief — names only (with externals merged in)const externals = discoverExternalPackages(cwd);for (const ext of externals) {const grouped = discoverExternalComponentsGrouped(ext.docsDir);diff --git a/packages/cli/src/api/hook.mjs b/packages/cli/src/api/hook.mjsindex 1311a5bc90..7778ae202f 100644--- a/packages/cli/src/api/hook.mjs+++ b/packages/cli/src/api/hook.mjs@@ -57,7 +57,7 @@ export async function hook(name, options = {}) {);}- if (detail === 'brief') {+ if (detail === 'compact') {const entries = [];for (const hookName of match[1]) {const docPath = findHookDoc(coreDir, hookName);@@ -79,11 +79,29 @@ export async function hook(name, options = {}) {return {type: 'hook.brief', data: {[match[0]]: entries}};}+ if (detail === 'full') {+ const entries = [];+ for (const hookName of match[1]) {+ const docPath = findHookDoc(coreDir, hookName);+ if (docPath) {+ try {+ entries.push(await loadDocs(docPath, {zh, lang}));+ } catch {+ entries.push({name: hookName});+ }+ } else {+ entries.push({name: hookName});+ }+ }+ return {type: 'hook.full', data: {[match[0]]: entries}};+ }++ // Default: brief — names onlyreturn {type: 'hook.list', data: {[match[0]]: match[1]}};}// All hooks- if (detail === 'brief') {+ if (detail === 'compact') {/** @type {Record<string, Array<{name: string, description: string, import: string}>>} */const result = {};for (const [cat, hookNames] of Object.entries(hooks)) {@@ -109,6 +127,28 @@ export async function hook(name, options = {}) {return {type: 'hook.brief', data: result};}+ if (detail === 'full') {+ /** @type {Record<string, Array<unknown>>} */+ const result = {};+ for (const [cat, hookNames] of Object.entries(hooks)) {+ result[cat] = [];+ for (const hookName of hookNames) {+ const docPath = findHookDoc(coreDir, hookName);+ if (docPath) {+ try {+ result[cat].push(await loadDocs(docPath, {zh, lang}));+ } catch {+ result[cat].push({name: hookName});+ }+ } else {+ result[cat].push({name: hookName});+ }+ }+ }+ return {type: 'hook.full', data: result};+ }++ // Default: brief — names onlyreturn {type: 'hook.list', data: hooks};}diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjsindex 1dfa6200cc..0f6423033d 100644--- a/packages/cli/src/commands/component/index.mjs+++ b/packages/cli/src/commands/component/index.mjs@@ -44,7 +44,12 @@ export function registerComponent(program) {const zh = program.opts().zh || false;const dense = program.opts().dense || false;const lang = program.opts().lang || null;- const detail = program.opts().detail || 'full';+ const detailSource = program.getOptionValueSource('detail');+ const isListView = options.list || options.category || !name;+ // Default detail level is full for single-component view, brief for list views.+ // (List views are scannable name lists; users can opt into compact/full.)+ let detail = program.opts().detail || 'full';+ if (isListView && detailSource === 'default') detail = 'brief';const json = program.opts().json || false;const validDetails = ['full', 'compact', 'brief'];@@ -80,6 +85,7 @@ export function registerComponent(program) {switch (result.type) {case 'component.list': {+ // --detail brief (default for list views) — names only.if (options.category) {const [cat, comps] = Object.entries(result.data)[0];humanLog(`\n${cat}:`);@@ -104,13 +110,28 @@ export function registerComponent(program) {}case 'component.brief': {- if (options.category || options.list || !name) {- humanLog(await formatBriefAll(coreDir, {zh, lang, themeData}));- } else {- const resolvedName = (name || '').replace(/^XDS/, '');- const importHint = resolveImportPath(coreDir, resolvedName);- humanLog(formatBrief(result.data, resolvedName, importHint, {themeData}));+ // --detail compact — name + 1-line description per entry.+ humanLog('');+ const entries = Object.entries(result.data);+ for (const [cat, items] of entries) {+ // Skip the synthetic group header when there's only one ungrouped category+ const isUngrouped =+ entries.length === 1 && items.length === 1 && items[0]?.name === cat;+ if (!isUngrouped) humanLog(cat);+ for (const item of items) {+ const desc = item.description ? ` — ${item.description}` : '';+ humanLog(` XDS${item.name}${desc}`);+ }+ humanLog('');}+ humanLog(`Usage: ${run} xds component <name>`);+ humanLog('');+ break;+ }++ case 'component.full': {+ // --detail full — dense per-component docs (signature, props, theming, examples).+ humanLog(await formatBriefAll(coreDir, {zh, lang, themeData}));break;}diff --git a/packages/cli/src/commands/detail-levels.test.mjs b/packages/cli/src/commands/detail-levels.test.mjsnew file mode 100644index 0000000000..0bce269f7d--- /dev/null+++ b/packages/cli/src/commands/detail-levels.test.mjs@@ -0,0 +1,133 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Integration tests for the --detail level contract on list views.+ *+ * Spawns the CLI as a subprocess against the real monorepo core dir and+ * asserts the documented size ordering for both `component --list` and+ * `hook --list`:+ *+ * brief (names only) < smallest+ * compact (name + 1-line desc) < middle+ * full (dense per-entry docs) largest+ *+ * All three levels must produce DISTINCT output. This guards against the+ * historically-inverted behavior where `brief` was densest and `full`+ * duplicated `compact`.+ */++import {describe, it, expect} from 'vitest';+import {spawnSync} from 'node:child_process';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const CLI_BIN = path.resolve(__dirname, '../../bin/xds.mjs');+// Repo root holds packages/core, which findCoreDir() walks up to locate.+const REPO_ROOT = path.resolve(__dirname, '../../../..');++function runCli(args) {+ const res = spawnSync('node', [CLI_BIN, ...args], {+ cwd: REPO_ROOT,+ encoding: 'utf-8',+ timeout: 60_000,+ // component.full JSON can exceed the default 1MB stdout buffer.+ maxBuffer: 64 * 1024 * 1024,+ });+ return {+ status: res.status,+ stdout: res.stdout || '',+ stderr: res.stderr || '',+ };+}++function listOutputs(cmd) {+ const brief = runCli([cmd, '--list', '--detail', 'brief']).stdout;+ const compact = runCli([cmd, '--list', '--detail', 'compact']).stdout;+ const full = runCli([cmd, '--list', '--detail', 'full']).stdout;+ return {brief, compact, full};+}++describe('--detail level ordering: component --list', () => {+ const {brief, compact, full} = listOutputs('component');++ it('produces strictly increasing output size: brief < compact < full', () => {+ expect(brief.length).toBeGreaterThan(0);+ expect(compact.length).toBeGreaterThan(brief.length);+ expect(full.length).toBeGreaterThan(compact.length);+ });++ it('produces three distinct outputs', () => {+ expect(brief).not.toEqual(compact);+ expect(compact).not.toEqual(full);+ expect(brief).not.toEqual(full);+ });++ it('brief is names-only (no targets, import hints, or prose descriptions)', () => {+ expect(brief).not.toMatch(/Targets:/);+ expect(brief).not.toMatch(/\u2190 from/);+ // Names only — should contain XDS component names but no " — " desc separator.+ expect(brief).toMatch(/Button/);+ expect(brief).not.toMatch(/ \u2014 /);+ });++ it('compact has 1-line descriptions (name + em-dash separator)', () => {+ expect(compact).toMatch(/ \u2014 /);+ });++ it('full has dense per-entry docs (props, targets, and import hints)', () => {+ expect(full).toMatch(/Targets:/);+ expect(full).toMatch(/\u2190 from/);+ // Prop name lists appear in the dense brief-all rendering.+ expect(full).toMatch(/children/);+ });++ it('full --json returns a valid component.full envelope', () => {+ const {stdout} = runCli(['component', '--list', '--detail', 'full', '--json']);+ const parsed = JSON.parse(stdout);+ expect(parsed.type).toBe('component.full');+ expect(parsed.apiVersion).toBe(1);+ expect(typeof parsed.data).toBe('object');+ });+});++describe('--detail level ordering: hook --list', () => {+ const {brief, compact, full} = listOutputs('hook');++ it('produces strictly increasing output size: brief < compact < full', () => {+ expect(brief.length).toBeGreaterThan(0);+ expect(compact.length).toBeGreaterThan(brief.length);+ expect(full.length).toBeGreaterThan(compact.length);+ });++ it('produces three distinct outputs', () => {+ expect(brief).not.toEqual(compact);+ expect(compact).not.toEqual(full);+ expect(brief).not.toEqual(full);+ });++ it('brief is names-only (no param tables or import blocks)', () => {+ expect(brief).not.toMatch(/\| Param \|/);+ expect(brief).not.toMatch(/## Parameters/);+ expect(brief).not.toMatch(/import \{/);+ expect(brief).toMatch(/use[A-Z]/);+ expect(brief).not.toMatch(/ \u2014 /);+ });++ it('compact has 1-line descriptions (name + em-dash separator)', () => {+ expect(compact).toMatch(/ \u2014 /);+ });++ it('full has dense docs (param tables and import statements)', () => {+ expect(full).toMatch(/\| Param \|/);+ expect(full).toMatch(/import \{/);+ });++ it('full --json returns a valid hook.full envelope', () => {+ const {stdout} = runCli(['hook', '--list', '--detail', 'full', '--json']);+ const parsed = JSON.parse(stdout);+ expect(parsed.type).toBe('hook.full');+ expect(parsed.apiVersion).toBe(1);+ expect(typeof parsed.data).toBe('object');+ });+});diff --git a/packages/cli/src/commands/hook/index.mjs b/packages/cli/src/commands/hook/index.mjsindex b3e0172e9b..5d9a32ec3f 100644--- a/packages/cli/src/commands/hook/index.mjs+++ b/packages/cli/src/commands/hook/index.mjs@@ -13,7 +13,6 @@ import {formatHookFull,formatHookCompact,formatHookBrief,- formatHookBriefAll,formatHookParams,} from '../../lib/hook-format.mjs';import {getRunPrefix} from '../../utils/package-manager.mjs';@@ -33,7 +32,11 @@ export function registerHook(program) {const run = getRunPrefix();const zh = program.opts().zh || false;const lang = program.opts().lang || null;- const detail = program.opts().detail || 'full';+ const detailSource = program.getOptionValueSource('detail');+ const isListView = options.list || options.category || !name;+ // Default detail level is full for single-hook view, brief for list views.+ let detail = program.opts().detail || 'full';+ if (isListView && detailSource === 'default') detail = 'brief';const json = program.opts().json || false;const validDetails = ['full', 'compact', 'brief'];@@ -64,6 +67,7 @@ export function registerHook(program) {switch (result.type) {case 'hook.list': {+ // --detail brief (default for list views) — names only.if (options.category) {const [cat, hookNames] = Object.entries(result.data)[0];humanLog(`\n${cat}:`);@@ -83,10 +87,31 @@ export function registerHook(program) {}case 'hook.brief': {- if (options.category || options.list || !name) {- humanLog(await formatHookBriefAll(coreDir));- } else {- humanLog(formatHookBrief(result.data));+ // --detail compact — name + 1-line description per entry.+ humanLog('');+ for (const [cat, items] of Object.entries(result.data)) {+ humanLog(cat);+ for (const item of items) {+ const desc = item.description ? ` — ${item.description}` : '';+ humanLog(` ${item.name}${desc}`);+ }+ humanLog('');+ }+ humanLog(`Usage: ${run} xds hook <name>`);+ humanLog('');+ break;+ }++ case 'hook.full': {+ // --detail full — dense per-hook docs grouped by category+ // (import block, best practices, full params + returns tables, related).+ humanLog('');+ for (const [cat, items] of Object.entries(result.data)) {+ humanLog(`## ${cat}\n`);+ for (const item of items) {+ const importPath = item.importPath || '@xds/core/hooks';+ humanLog(formatHookCompact(item, importPath));+ }}break;}diff --git a/packages/cli/src/types/api.d.ts b/packages/cli/src/types/api.d.tsindex 2618a112ed..05c199d64d 100644--- a/packages/cli/src/types/api.d.ts+++ b/packages/cli/src/types/api.d.ts@@ -10,6 +10,7 @@import type {ComponentListResponse,ComponentBriefResponse,+ ComponentFullResponse,ComponentDetailResponse,ComponentDetailPropsResponse,ComponentDetailSourceResponse,@@ -61,6 +62,7 @@ export interface ComponentOptions {type ComponentResult =| ComponentListResponse| ComponentBriefResponse+ | ComponentFullResponse| ComponentDetailResponse| ComponentDetailPropsResponse| ComponentDetailSourceResponsediff --git a/packages/cli/src/types/component.d.ts b/packages/cli/src/types/component.d.tsindex 426d722151..722d47ae57 100644--- a/packages/cli/src/types/component.d.ts+++ b/packages/cli/src/types/component.d.ts@@ -3,12 +3,18 @@/*** Component command JSON responses.*+ * Detail-level contract for list views (brief < compact < full):+ * --detail brief Names only. Smallest, most scannable. (DEFAULT for --list)+ * --detail compact Names + 1-line description + import path.+ * --detail full Full ComponentDoc per entry (props, theming, examples, etc.).+ ** Invocation -> type discriminator* ------------------------------------------------------------------* xds --json component -> component.list* xds --json component --list -> component.list* xds --json component --category Form -> component.list (filtered)- * xds --json component --detail brief -> component.brief+ * xds --json component --list --detail compact -> component.brief+ * xds --json component --list --detail full -> component.full* xds --json component Button -> component.detail* xds --json component Button --props -> component.detail.props* xds --json component Button --source -> component.detail.source@@ -19,13 +25,13 @@import type {ComponentDoc, PropDoc} from '../../../core/src/docs-types';-/** xds --json component [--list] [--category X] */+/** xds --json component [--list] [--category X] [--detail brief] */export interface ComponentListResponse {type: 'component.list';data: Record<string, string[]>;}-/** xds --json component --detail brief [--category X] */+/** xds --json component --list --detail compact */export interface ComponentBriefResponse {type: 'component.brief';data: Record<string, ComponentBriefEntry[]>;@@ -37,6 +43,12 @@ export interface ComponentBriefEntry {import: string;}+/** xds --json component --list --detail full */+export interface ComponentFullResponse {+ type: 'component.full';+ data: Record<string, ComponentDoc[]>;+}+/** xds --json component <name> */export interface ComponentDetailResponse {type: 'component.detail';