@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

package/clients/cli/commands/component/index.mjs

@@ -38,6 +38,7 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
  *
  * @typedef {(
  *   | import('../../../../api/component/component.type.mjs').ComponentListResponse
+ *   | import('../../../../api/component/component.type.mjs').ComponentBatchResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailPropsResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailSourceResponse
@@ -67,6 +68,11 @@ function summarize(result) {
       );
       return resultSet({count, resultKind: 'component'});
     }
+    case 'component.batch':
+      return resultSet({
+        count: result.data.results.filter(row => row.status === 'found').length,
+        resultKind: 'component',
+      });
     case 'component.detail':
     case 'component.detail.props':
     case 'component.detail.source':
@@ -82,19 +88,103 @@ function summarize(result) {
   }
 }
 
+/**
+ * Project one single-component API result through the existing formatter kit.
+ * @param {import('../../../../api/component/component.type.mjs').ComponentSingleResponse} result
+ * @param {string} requestedName
+ * @param {'full'|'compact'|'brief'} detail
+ * @param {ReturnType<typeof resolveTheme>} themeData
+ * @returns {import('../../formatters/index.mjs').Block[]}
+ */
+function componentDetailBlocks(result, requestedName, detail, themeData) {
+  const resolvedName = (requestedName.split('/').pop() ?? requestedName).replace(
+    /^XDS/,
+    '',
+  );
+  switch (result.type) {
+    case 'component.detail': {
+      /** @type {import('../../formatters/index.mjs').Block[]} */
+      const out = [];
+      if (result.data.parentDoc) {
+        out.push(record(result.data, {fields: ['parentDoc']}));
+      }
+      out.push(
+        detail === 'brief'
+          ? code(
+              formatBrief(result.data, resolvedName, result.data.import, {
+                themeData,
+              }),
+            )
+          : detail === 'compact'
+            ? code(
+                formatCompact(result.data, resolvedName, result.data.import),
+              )
+            : code(
+                formatFull(result.data, {
+                  themeData,
+                  importHint: result.data.import,
+                }),
+              ),
+      );
+      return out;
+    }
+    case 'component.detail.props':
+      return [code(formatProps({props: result.data}, resolvedName))];
+    case 'component.detail.source':
+    case 'component.detail.showcase':
+      return [code(result.data.source)];
+    case 'component.detail.blocks': {
+      const {showcase, examples, related} = result.data;
+      /** @type {import('../../formatters/index.mjs').Block[]} */
+      const out = [];
+      if (showcase) {
+        out.push(
+          section('Showcase'),
+          record(showcase, {fields: ['displayName', 'description']}),
+        );
+      }
+      if (examples.length > 0) {
+        out.push(
+          section('Examples'),
+          records(examples, {fields: ['name', 'description']}),
+        );
+      }
+      if (related.length > 0) {
+        out.push(
+          section(
+            `Related: ${related.length} blocks that use ${result.data.component}`,
+          ),
+          list(related.map(block => block.name)),
+        );
+      }
+      if (!showcase && examples.length === 0 && related.length === 0) {
+        out.push(text(`No blocks found for ${result.data.component}`));
+      }
+      return out;
+    }
+    default:
+      return [];
+  }
+}
+
 /**
  * @param {import('commander').Command} program
  */
 export function registerComponent(program) {
   defineCommand(program, componentCommand, {
     fn: componentFn,
-    action: async (/** @type {string | undefined} */ name, /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options) => {
+    action: async (
+      /** @type {string[] | undefined} */ names,
+      /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options,
+    ) => {
       const run = getCliInvocation();
+      const name = names?.length === 1 ? names[0] : undefined;
+      const apiInput = !names?.length ? undefined : name ?? names;
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
       const lang = program.opts().lang || null;
       const detailSource = program.getOptionValueSource('detail');
-      const isListView = options.list || options.category || !name;
+      const isListView = options.list || options.category || !names?.length;
       // 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';
@@ -119,7 +209,7 @@ export function registerComponent(program) {
       /** @type {ComponentResult} */
       let result;
       try {
-        result = /** @type {ComponentResult} */ (await componentApi(name, {
+        result = /** @type {ComponentResult} */ (await componentApi(apiInput, {
           cwd: process.cwd(),
           list: options.list,
           category: options.category,
@@ -137,6 +227,12 @@ export function registerComponent(program) {
       }
 
       const answered = summarize(result);
+      if (
+        result.type === 'component.batch' &&
+        result.data.results.some(row => row.status !== 'found')
+      ) {
+        process.exitCode = 1;
+      }
       if (json) {
         jsonOut(result);
         return answered;
@@ -152,7 +248,7 @@ export function registerComponent(program) {
       const listFooter = text(
         [
           `Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`,
-          `Usage: ${run} component <name>`,
+          `Usage: ${run} component <name> [name...]`,
         ].join('\n'),
       );
 
@@ -231,64 +327,65 @@ export function registerComponent(program) {
           break;
         }
 
-        case 'component.detail': {
-          const resolvedName = (name || '').replace(/^XDS/, '');
-          const importHint = result.data.import;
-          if (result.data.parentDoc) emit(record(result.data, {fields: ['parentDoc']}));
-          const doc =
-            detail === 'brief'
-              ? code(formatBrief(result.data, resolvedName, importHint, {themeData}))
-              : detail === 'compact'
-                ? code(formatCompact(result.data, resolvedName, importHint))
-                : code(formatFull(result.data, {themeData, importHint}));
-          emit(doc);
-          break;
-        }
-
-        case 'component.detail.props': {
-          const resolvedName = (name || '').replace(/^XDS/, '');
-          emit(code(formatProps({props: result.data}, resolvedName)));
-          break;
-        }
-
-        case 'component.detail.source': {
-          emit(code(result.data.source));
-          break;
-        }
-
-        case 'component.detail.showcase': {
-          emit(code(result.data.source));
-          break;
-        }
-
-        case 'component.detail.blocks': {
-          const {showcase, examples, related} = result.data;
+        case 'component.batch': {
           /** @type {import('../../formatters/index.mjs').Block[]} */
-          const out = [];
-          if (showcase) {
-            out.push(
-              section('Showcase'),
-              record(showcase, {fields: ['displayName', 'description']}),
-            );
-          }
-          if (examples.length > 0) {
-            out.push(
-              section('Examples'),
-              records(examples, {fields: ['name', 'description']}),
-            );
-          }
-          if (related.length > 0) {
+          const out = [
+            section('Component batch'),
+            record({count: result.data.count}),
+            section('Results'),
+          ];
+          for (const row of result.data.results) {
+            out.push(section(row.selector));
+            if (row.status === 'found') {
+              out.push(
+                record(row, {fields: ['selector', 'status']}),
+                section('Result'),
+                ...componentDetailBlocks(
+                  row.result,
+                  row.selector,
+                  detail,
+                  themeData,
+                ),
+              );
+              continue;
+            }
             out.push(
-              section(`Related: ${related.length} blocks that use ${result.data.component}`),
-              list(related.map(b => b.name)),
+              record(row, {
+                fields: ['selector', 'status', 'code', 'error'],
+              }),
             );
-          }
-          if (!showcase && examples.length === 0 && related.length === 0) {
-            out.push(text(`No blocks found for ${result.data.component}`));
+            if (row.status === 'ambiguous') {
+              out.push(
+                section('Candidates'),
+                records(row.candidates, {
+                  fields: ['package', 'component', 'kind', 'installed'],
+                }),
+              );
+            } else if (row.suggestions?.length) {
+              out.push(
+                section('Suggestions'),
+                records(row.suggestions, {fields: ['name', 'reason']}),
+              );
+            }
           }
           emit(...out);
           break;
         }
+
+        case 'component.detail':
+        case 'component.detail.props':
+        case 'component.detail.source':
+        case 'component.detail.showcase':
+        case 'component.detail.blocks':
+          emit(
+            ...componentDetailBlocks(
+              result,
+              name ?? '',
+              detail,
+              themeData,
+            ),
+          );
+          break;
       }
       return answered;
     },

package/clients/cli/commands/component-batch.test.mjs

@@ -0,0 +1,341 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Multi-selector component lookup contract: one ordered batch envelope,
+ * complete per-selector states, unchanged single-selector responses, and matching
+ * text/JSON exit behavior.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {
+  component,
+  COMPONENT_BATCH_SELECTOR_LIMIT,
+} from '../../../api/component/component.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const REPO_ROOT = path.resolve(import.meta.dirname, '../../../../..');
+const SLOW = 60_000;
+
+describe('component() batch lookup', () => {
+  it(
+    'keeps one found row per selector, in order, including duplicates',
+    async () => {
+      const result = await component(['Button', 'Badge', 'Button'], {
+        cwd: REPO_ROOT,
+        detail: 'brief',
+      });
+
+      expect(result.type).toBe('component.batch');
+      expect(result.data.count).toBe(3);
+      expect(result.data.results.map(row => row.selector)).toEqual([
+        'Button',
+        'Badge',
+        'Button',
+      ]);
+      expect(result.data.results.map(row => row.status)).toEqual([
+        'found',
+        'found',
+        'found',
+      ]);
+      expect(
+        result.data.results.map(row =>
+          row.status === 'found' ? row.result.type : null,
+        ),
+      ).toEqual(['component.detail', 'component.detail', 'component.detail']);
+    },
+    SLOW,
+  );
+
+  it(
+    'applies every focused projection to each found row',
+    async () => {
+      const projections = [
+        {options: {props: true}, expectedType: 'component.detail.props'},
+        {options: {source: true}, expectedType: 'component.detail.source'},
+        {options: {showcase: true}, expectedType: 'component.detail.showcase'},
+        {options: {blocks: true}, expectedType: 'component.detail.blocks'},
+      ];
+      for (const projection of projections) {
+        const result = await component(['Button', 'Card'], {
+          cwd: REPO_ROOT,
+          ...projection.options,
+        });
+        expect(result.type).toBe('component.batch');
+        expect(
+          result.data.results.map(row =>
+            row.status === 'found' ? row.result.type : null,
+          ),
+        ).toEqual([projection.expectedType, projection.expectedType]);
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'uses input shape to distinguish catalog, single, and batch calls',
+    async () => {
+      expect((await component(undefined, {cwd: REPO_ROOT})).type).toBe(
+        'component.list',
+      );
+      expect((await component('Button', {cwd: REPO_ROOT})).type).toBe(
+        'component.detail',
+      );
+
+      const emptyBatch = await component([], {cwd: REPO_ROOT});
+      expect(emptyBatch).toEqual({
+        type: 'component.batch',
+        data: {count: 0, results: []},
+      });
+      expect(
+        await component([], {
+          cwd: REPO_ROOT,
+          list: true,
+          category: 'Form',
+        }),
+      ).toEqual(emptyBatch);
+
+      const oneRowBatch = await component(['Button'], {
+        cwd: REPO_ROOT,
+        detail: 'brief',
+      });
+      expect(oneRowBatch).toMatchObject({
+        type: 'component.batch',
+        data: {
+          count: 1,
+          results: [
+            {
+              selector: 'Button',
+              status: 'found',
+              result: {type: 'component.detail'},
+            },
+          ],
+        },
+      });
+    },
+    SLOW,
+  );
+
+  it('rejects an oversized array before component resolution starts', async () => {
+    const selectors = Array.from(
+      {length: COMPONENT_BATCH_SELECTOR_LIMIT + 1},
+      () => 'Button',
+    );
+    await expect(
+      component(selectors, {
+        cwd: path.join(REPO_ROOT, 'missing-batch-cwd'),
+      }),
+    ).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: `Component batch accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors; received ${selectors.length}`,
+    });
+  });
+
+  it(
+    'keeps receipt invariants across a deterministic selector chaos matrix',
+    async () => {
+      const found = new Set(['Button', 'Card']);
+      const selectorCases = [
+        [],
+        ['Button'],
+        ['ZzzNope99'],
+        ['Button', 'Button'],
+        ['ZzzNope98', 'ZzzNope99'],
+        ['Button', 'ZzzNope99', 'Card'],
+        ['ZzzNope99', 'Button', 'ZzzNope99', 'Button'],
+        ['Card', 'Button', 'Card', 'ZzzNope98', 'Button'],
+      ];
+
+      for (const selectors of selectorCases) {
+        const result = await component(selectors, {
+          cwd: REPO_ROOT,
+          detail: 'brief',
+        });
+        expect(result.type).toBe('component.batch');
+        expect(result.data.count).toBe(selectors.length);
+        expect(result.data.results.map(row => row.selector)).toEqual(selectors);
+        expect(result.data.results.map(row => row.status)).toEqual(
+          selectors.map(selector =>
+            found.has(selector) ? 'found' : 'not_found',
+          ),
+        );
+        for (const row of result.data.results) {
+          if (row.status === 'found') {
+            expect(row.result.type).toBe('component.detail');
+          } else {
+            expect(row.code).toBe('ERR_UNKNOWN_COMPONENT');
+          }
+        }
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'composes every detail and language control over a batch',
+    async () => {
+      /** @type {Array<{detail?: 'full'|'compact'|'brief'; lang?: string; zh?: boolean; dense?: boolean}>} */
+      const controls = [
+        {detail: 'brief'},
+        {detail: 'compact'},
+        {detail: 'full'},
+        {lang: 'en'},
+        {lang: 'dense'},
+        {zh: true},
+        {dense: true},
+      ];
+      for (const control of controls) {
+        const result = await component(['Button', 'Card'], {
+          cwd: REPO_ROOT,
+          ...control,
+        });
+        expect(result.type).toBe('component.batch');
+        expect(result.data.results).toHaveLength(2);
+        expect(
+          result.data.results.every(
+            row =>
+              row.status === 'found' && row.result.type === 'component.detail',
+          ),
+        ).toBe(true);
+      }
+    },
+    SLOW,
+  );
+});
+
+describe('astryx component batch lookup', () => {
+  it('documents variadic selector grammar in --help', async () => {
+    const run = await runCli(['component', '--help'], REPO_ROOT);
+    expect(run.code).toBe(0);
+    expect(run.stdout).toContain(
+      'Usage: astryx component [options] [names...]',
+    );
+    expect(run.stdout).toContain('@scope/package@version/Name');
+    expect(run.stdout).toContain('Two or more return one ordered batch');
+    expect(run.stdout).toContain('At most 100 selectors');
+  });
+
+  it(
+    'keeps catalog and single-result CLI envelopes at zero and one selectors',
+    async () => {
+      const catalog = await runCli(['--json', 'component'], REPO_ROOT);
+      expect(catalog.code).toBe(0);
+      expect(JSON.parse(catalog.stdout).type).toBe('component.list');
+
+      const single = await runCli(
+        ['--json', '--detail', 'brief', 'component', 'Button'],
+        REPO_ROOT,
+      );
+      expect(single.code).toBe(0);
+      expect(JSON.parse(single.stdout).type).toBe('component.detail');
+    },
+    SLOW,
+  );
+
+  it(
+    'emits one component.batch JSON envelope for several found selectors',
+    async () => {
+      const run = await runCli(
+        ['--json', '--detail', 'brief', 'component', 'Button', 'Badge'],
+        REPO_ROOT,
+      );
+      expect(run.code).toBe(0);
+      const envelope = JSON.parse(run.stdout);
+      expect(envelope.type).toBe('component.batch');
+      expect(envelope.data.count).toBe(2);
+      expect(envelope.data.results.map(row => row.selector)).toEqual([
+        'Button',
+        'Badge',
+      ]);
+      expect(envelope.data.results.every(row => row.status === 'found')).toBe(
+        true,
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'rejects an oversized batch before emitting JSON or text results',
+    async () => {
+      const selectors = Array.from(
+        {length: COMPONENT_BATCH_SELECTOR_LIMIT + 1},
+        () => 'Button',
+      );
+      const json = await runCli(
+        ['--json', 'component', ...selectors],
+        REPO_ROOT,
+      );
+      expect(json.code).toBe(1);
+      expect(JSON.parse(json.stdout)).toMatchObject({
+        code: 'ERR_INVALID_ARGUMENT',
+        error: `Component batch accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors; received ${selectors.length}`,
+      });
+      expect(JSON.parse(json.stdout).type).toBeUndefined();
+
+      const text = await runCli(['component', ...selectors], REPO_ROOT);
+      expect(text.code).toBe(1);
+      expect(text.stdout + text.stderr).toContain(
+        `accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors`,
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'emits every row and exits 1 when one selector is not found',
+    async () => {
+      const run = await runCli(
+        ['--json', '--detail', 'brief', 'component', 'Button', 'ZzzNope99'],
+        REPO_ROOT,
+      );
+      expect(run.code).toBe(1);
+      const envelope = JSON.parse(run.stdout);
+      expect(envelope.type).toBe('component.batch');
+      expect(envelope.data.results).toMatchObject([
+        {selector: 'Button', status: 'found'},
+        {
+          selector: 'ZzzNope99',
+          status: 'not_found',
+          code: 'ERR_UNKNOWN_COMPONENT',
+        },
+      ]);
+    },
+    SLOW,
+  );
+
+  it(
+    'emits every failed row and exits 1 when no selector resolves',
+    async () => {
+      const run = await runCli(
+        ['--json', 'component', 'ZzzNope98', 'ZzzNope99'],
+        REPO_ROOT,
+      );
+      expect(run.code).toBe(1);
+      const envelope = JSON.parse(run.stdout);
+      expect(envelope.type).toBe('component.batch');
+      expect(envelope.data.count).toBe(2);
+      expect(envelope.data.results).toMatchObject([
+        {selector: 'ZzzNope98', status: 'not_found'},
+        {selector: 'ZzzNope99', status: 'not_found'},
+      ]);
+    },
+    SLOW,
+  );
+
+  it(
+    'projects every row in text and keeps the same failing exit status',
+    async () => {
+      const run = await runCli(
+        ['--detail', 'brief', 'component', 'Button', 'ZzzNope99'],
+        REPO_ROOT,
+      );
+      expect(run.code).toBe(1);
+      expect(run.stdout).toContain('count: 2');
+      expect(run.stdout).toMatch(/selector: Button\nstatus:\s+found/);
+      expect(run.stdout).toMatch(
+        /selector: ZzzNope99\nstatus:\s+not_found\ncode:\s+ERR_UNKNOWN_COMPONENT/,
+      );
+    },
+    SLOW,
+  );
+});