Skip to content

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.md
index da9dc56185..ca09f81b37 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -30,7 +30,7 @@ npx xds template --list
These 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 narrowed
Every 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` |
## Configuration
diff --git a/packages/cli/src/api/component.mjs b/packages/cli/src/api/component.mjs
index 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 only
return {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.mjs
index 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 only
return {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 only
return {type: 'hook.list', data: hooks};
}
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.ts
index 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
| ComponentDetailSourceResponse
diff --git a/packages/cli/src/types/component.d.ts b/packages/cli/src/types/component.d.ts
index 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';