@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/component/component.mjs

@@ -4,10 +4,10 @@
  * @file Programmatic API for the component command — DISPATCHER + BARREL.
  *
  * Returns the same typed envelope { type, data } that `astryx --json component`
- * outputs. `component(name, opts)` parses the (name, options) pair, resolves the
- * subject once via `_adapter`, and routes to the correct leaf
- * (list · detail · detail.props/source/showcase/blocks), returning that leaf's
- * envelope. The CLI command handler is a thin wrapper around this function.
+ * outputs. `component(name, opts)` parses one selector or an ordered selector
+ * list, resolves each subject through `_adapter`, and routes to the correct leaf
+ * (list · detail · detail.props/source/showcase/blocks). The CLI command handler
+ * is a thin wrapper around this function.
  *
  * Every leaf is also re-exported for direct scripting use.
  */
@@ -26,6 +26,8 @@ import {
   resolveUnscopedDoc,
   loadComponentDoc,
   scopeSubComponent,
+  ComponentAmbiguityError,
+  installedComponentPackageVersion,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -34,8 +36,199 @@ import {componentDetailSource} from './detail/source/source.mjs';
 import {componentDetailShowcase} from './detail/showcase/showcase.mjs';
 import {componentDetailBlocks} from './detail/blocks/blocks.mjs';
 
+/** Maximum selectors accepted before any component resolution starts. */
+export const COMPONENT_BATCH_SELECTOR_LIMIT = 100;
+
+/** @type {ReadonlyArray<string>} */
+const DETAIL_LEVELS = ['full', 'compact', 'brief'];
+/** @type {ReadonlyArray<string>} */
+const LANGS = ['en', 'zh', 'dense'];
+/** @type {Set<string>} */
+const NOT_FOUND_CODES = new Set([
+  ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+  ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+  ERROR_CODES.ERR_NOT_FOUND,
+]);
+
+/**
+ * Discover-compatible package target grammar. Versions belong to the package
+ * head, never the item after the package slash.
+ * @param {string} selector
+ * @returns {{scoped: boolean, name: string, version?: string, item?: string}}
+ */
+function splitSelector(selector) {
+  const scoped = selector.startsWith('@');
+  const firstSlash = selector.indexOf('/');
+  let head = selector;
+  /** @type {string | undefined} */
+  let rest;
+  const split = scoped
+    ? firstSlash < 0
+      ? -1
+      : selector.indexOf('/', firstSlash + 1)
+    : firstSlash;
+  if (split > 0) {
+    head = selector.slice(0, split);
+    rest = selector.slice(split + 1) || undefined;
+  }
+  const at = head.indexOf('@', 1);
+  return {
+    scoped,
+    name: at > 0 ? head.slice(0, at) : head,
+    ...(at > 0 && head.slice(at + 1) ? {version: head.slice(at + 1)} : {}),
+    ...(rest ? {item: rest} : {}),
+  };
+}
+
+/**
+ * Resolve one component selector into the existing single-component API inputs.
+ * @param {unknown} value
+ * @param {string|undefined} packageScope
+ * @returns {{selector: string, name: string, package?: string, version?: string}}
+ */
+function parseComponentSelector(value, packageScope) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new AstryxError(
+      `Invalid component selector "${String(value)}"`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  const target = splitSelector(value);
+  const packageShaped =
+    target.scoped || target.item != null || target.version != null;
+  if (!packageShaped) {
+    return {selector: value, name: target.name, package: packageScope};
+  }
+  if (!target.item) {
+    throw new AstryxError(
+      `Component selector "${value}" names a package but no component`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  if (packageScope && packageScope !== target.name) {
+    throw new AstryxError(
+      `Component selector "${value}" conflicts with --package "${packageScope}"`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  return {
+    selector: value,
+    name: target.item,
+    package: target.name,
+    ...(target.version ? {version: target.version} : {}),
+  };
+}
+
+/**
+ * A version-qualified selector never falls through to another installed
+ * version. Its structured suggestion points at the command that can discover
+ * the requested package release.
+ * @param {{package?: string, version?: string}} target
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @returns {void}
+ */
+function requireInstalledSelectorVersion(target, coreDir, loadedIntegrations) {
+  if (!target.version) return;
+  const packageName = /** @type {string} */ (target.package);
+  const installed = installedComponentPackageVersion(
+    coreDir,
+    loadedIntegrations,
+    packageName,
+  );
+  if (installed === target.version) return;
+  const exact = `${packageName}@${target.version}`;
+  throw new AstryxError(
+    `Package "${exact}" is not installed`,
+    [
+      {
+        name: `astryx discover ${exact}`,
+        reason: 'look up this package version',
+      },
+    ],
+    ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+  );
+}
+
+/**
+ * Turn a single-lookup failure into one complete batch row.
+ * @param {string} selector
+ * @param {unknown} error
+ * @returns {import('./component.type.mjs').ComponentBatchResult}
+ */
+function batchFailure(selector, error) {
+  const err =
+    error instanceof AstryxError
+      ? error
+      : new AstryxError(
+          error instanceof Error ? error.message : String(error),
+          undefined,
+          ERROR_CODES.ERR_UNKNOWN,
+        );
+  if (err instanceof ComponentAmbiguityError) {
+    return {
+      selector,
+      status: 'ambiguous',
+      code: err.code,
+      error: err.message,
+      candidates: err.candidates,
+    };
+  }
+  return {
+    selector,
+    status: NOT_FOUND_CODES.has(err.code) ? 'not_found' : 'error',
+    code: err.code,
+    error: err.message,
+    ...(err.suggestions ? {suggestions: err.suggestions} : {}),
+  };
+}
+
 /**
- * @param {string} [name]
+ * @param {unknown[]} selectors
+ * @param {object} options
+ * @param {string} options.cwd
+ * @param {string} [options.package]
+ * @param {boolean} [options.props]
+ * @param {boolean} [options.source]
+ * @param {boolean} [options.showcase]
+ * @param {boolean} [options.blocks]
+ * @param {'full'|'compact'|'brief'} [options.detail]
+ * @param {string|null} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @param {string} coreDir
+ * @returns {Promise<import('./component.type.mjs').ComponentBatchResponse>}
+ */
+async function componentBatch(selectors, options, coreDir) {
+  const loadedIntegrations = await loadIntegrationsSafely(options.cwd);
+  /** @type {import('./component.type.mjs').ComponentBatchResult[]} */
+  const results = [];
+  for (const value of selectors) {
+    const selector = typeof value === 'string' ? value : String(value);
+    try {
+      const target = parseComponentSelector(value, options.package);
+      requireInstalledSelectorVersion(target, coreDir, loadedIntegrations);
+      const result =
+        /** @type {import('./component.type.mjs').ComponentSingleResponse} */ (
+          await component(target.name, {
+            ...options,
+            lang: options.lang ?? undefined,
+            package: target.package,
+          })
+        );
+      results.push({selector, status: 'found', result});
+    } catch (error) {
+      results.push(batchFailure(selector, error));
+    }
+  }
+  return {type: 'component.batch', data: {count: results.length, results}};
+}
+
+/**
+ * @param {string|string[]} [name]
  * @param {object} [options]
  * @param {string} [options.cwd]
  * @param {boolean} [options.list]
@@ -51,6 +244,7 @@ import {componentDetailBlocks} from './detail/blocks/blocks.mjs';
  * @param {boolean} [options.dense]
  * @returns {Promise<(
  *   import('./component.type.mjs').ComponentListResponse
+ *   | import('./component.type.mjs').ComponentBatchResponse
  *   | import('./component.type.mjs').ComponentDetailResponse
  *   | import('./component.type.mjs').ComponentDetailPropsResponse
  *   | import('./component.type.mjs').ComponentDetailSourceResponse
@@ -74,13 +268,43 @@ export async function component(name, options = {}) {
     dense = false,
   } = options;
 
+  const selectorList = Array.isArray(name) ? name : null;
+  const noName = selectorList == null && !name;
+
   // Default detail level mirrors the CLI (see commands/component/index.mjs):
   // single-component views default to 'full', list-style views (--list,
   // --category, or no name) default to 'brief' (scannable name lists).
-  // Keeping this in sync with the CLI is what the API↔CLI parity test checks.
-  const isListView = list || category != null || !name;
+  // An explicit array remains a batch even when it is empty or a caller also
+  // passes a list-only option.
+  const isListView =
+    selectorList == null && (list || category != null || noName);
   const detail = detailOption ?? (isListView ? 'brief' : 'full');
 
+  // Same accepted values and codes as the CLI's --detail and --lang, checked
+  // first as the CLI parser does.
+  if (!DETAIL_LEVELS.includes(detail)) {
+    throw new AstryxError(
+      `Invalid detail "${String(detail)}". Valid levels: ${DETAIL_LEVELS.join(', ')}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DETAIL,
+    );
+  }
+  if (lang != null && !LANGS.includes(lang)) {
+    throw new AstryxError(
+      `Invalid lang "${String(lang)}". Valid values: ${LANGS.join(', ')}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_LANG,
+    );
+  }
+
+  if (selectorList && selectorList.length > COMPONENT_BATCH_SELECTOR_LIMIT) {
+    throw new AstryxError(
+      `Component batch accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors; received ${selectorList.length}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+
   const coreDir = requireCoreDir(cwd);
 
   // A public API caller could pass a non-string category; the list leaf does
@@ -94,11 +318,46 @@ export async function component(name, options = {}) {
     );
   }
 
+  // ── Explicit batch selector list ─────────────────────────────────
+  // Array shape owns cardinality even if a caller also supplies a list-only
+  // option. The aggregate limit above is checked before core or integrations
+  // are resolved, so an oversized request can never emit a partial receipt.
+  if (selectorList) {
+    return componentBatch(
+      selectorList,
+      {
+        cwd,
+        package: packageScope,
+        props,
+        source,
+        showcase,
+        blocks,
+        detail,
+        lang,
+        zh,
+        dense,
+      },
+      coreDir,
+    );
+  }
+
   // ── List mode ──────────────────────────────────────────────────
-  if (category || list || !name) {
+  if (category || list || noName) {
     return componentList(coreDir, {cwd, category, detail, zh, dense, lang});
   }
 
+  if (typeof name === 'string') {
+    const target = parseComponentSelector(name, packageScope);
+    if (target.version) {
+      const loadedIntegrations = await loadIntegrationsSafely(cwd);
+      requireInstalledSelectorVersion(target, coreDir, loadedIntegrations);
+    }
+    if (target.name !== name || target.package !== packageScope) {
+      return component(target.name, {...options, package: target.package});
+    }
+    name = target.name;
+  }
+
   // ── Single component ───────────────────────────────────────────
   if (typeof name !== 'string') {
     throw new AstryxError(
@@ -121,14 +380,20 @@ export async function component(name, options = {}) {
   // Searches that package first — critical for names that exist in both core
   // and an external package (AppShell, Button, SideNav).
   if (packageScope) {
-    const scoped = classifyScope(packageScope, {owners, loadedIntegrations, cwd, name});
+    const scoped = classifyScope(packageScope, {
+      owners,
+      loadedIntegrations,
+      cwd,
+      name,
+    });
 
     if (scoped.kind === 'core' || scoped.kind === 'integration') {
       const owner = scoped.owner;
       if (source) {
         return componentDetailSource(dirName, owner.sourcePath, {
           name,
-          notFoundInPackage: scoped.kind === 'integration' ? packageScope : null,
+          notFoundInPackage:
+            scoped.kind === 'integration' ? packageScope : null,
         });
       }
       // showcase/blocks were previously dropped on the scoped path — a
@@ -143,7 +408,7 @@ export async function component(name, options = {}) {
           : componentDetailShowcase(dirName, {cwd, name, resolve: false});
       }
       if (blocks) {
-        return componentDetailBlocks(dirName);
+        return componentDetailBlocks(dirName, cwd);
       }
       const docs = await loadComponentDoc(owner.docPath, docOpts);
       if (props) return componentDetailProps(docs);
@@ -156,19 +421,60 @@ export async function component(name, options = {}) {
     }
     const extDocPath = resolveLegacyExternalDoc(scoped.ext, dirName);
     if (extDocPath) {
+      // Legacy packages ship docs, never source.
+      if (source) {
+        return componentDetailSource(dirName, null, {
+          name,
+          notFoundInPackage: packageScope,
+        });
+      }
+      if (blocks) {
+        return componentDetailBlocks(dirName, cwd);
+      }
       const docs = await loadComponentDoc(extDocPath, docOpts);
       if (props) return componentDetailProps(docs);
-      return componentDetail(docs, {package: scoped.ext.name, sourcePath: null}, dirName, coreDir);
+      return componentDetail(
+        docs,
+        {package: scoped.ext.name, sourcePath: null},
+        dirName,
+        coreDir,
+      );
+    }
+    throw new AstryxError(
+      `No component "${name}" in package "${packageScope}"`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  // Invalid integration metadata does not create ambiguity against a valid
+  // owner. Keep raw owners only when no doc owner is valid, so an integration-
+  // only component still exposes its source and returns ERR_INVALID_DOC for
+  // detail instead of degrading to an unrelated unknown-component error.
+  const validOwners = [];
+  for (const owner of owners) {
+    if (owner.package === CORE_PACKAGE) {
+      validOwners.push(owner);
+      continue;
+    }
+    try {
+      await loadComponentDoc(owner.docPath);
+      validOwners.push(owner);
+    } catch {
+      // Project/Doctor report invalid metadata; it is not an effective owner.
     }
-    throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
   }
+  const effectiveOwners = validOwners.length > 0 ? validOwners : owners;
 
-  // ── Ambiguity: owned by MORE THAN ONE package, no --package ─────
-  assertUnambiguousOwners(owners, dirName);
+  // ── Ambiguity: owned by MORE THAN ONE valid package, no --package ──
+  assertUnambiguousOwners(effectiveOwners, dirName);
 
   // ── Single non-core owner (an integration provides it, core does not) ──
-  if (owners.length === 1 && owners[0].package !== CORE_PACKAGE) {
-    const owner = owners[0];
+  if (
+    effectiveOwners.length === 1 &&
+    effectiveOwners[0].package !== CORE_PACKAGE
+  ) {
+    const owner = effectiveOwners[0];
     if (source) {
       return componentDetailSource(dirName, owner.sourcePath, {name});
     }
@@ -184,7 +490,11 @@ export async function component(name, options = {}) {
   // ── No-scope core path ─────────────────────────────────────────
   // `--source` reads core directly (no external/fuzzy fallback).
   if (source) {
-    return componentDetailSource(dirName, resolveCoreSourcePath(coreDir, dirName), {name});
+    return componentDetailSource(
+      dirName,
+      resolveCoreSourcePath(coreDir, dirName),
+      {name},
+    );
   }
   if (showcase) {
     return componentDetailShowcase(dirName, {cwd, name});
@@ -195,7 +505,7 @@ export async function component(name, options = {}) {
 
   // ── Blocks mode ──────────────────────────────────────────────
   if (blocks) {
-    return componentDetailBlocks(dirName);
+    return componentDetailBlocks(dirName, cwd);
   }
 
   // ── Sub-component scoping ────────────────────────────────────
@@ -203,10 +513,14 @@ export async function component(name, options = {}) {
   // scope the response to just the matching sub-component.
   const sub = scopeSubComponent(docs, dirName, coreDir);
   if (sub) {
-    if (props) return componentDetailProps({props: sub.matchingComponent.props});
+    if (props)
+      return componentDetailProps({props: sub.matchingComponent.props});
     return componentDetail(
       sub.scoped,
-      {package: resolved.resolvedOwnerPackage, sourcePath: resolved.resolvedSourcePath},
+      {
+        package: resolved.resolvedOwnerPackage,
+        sourcePath: resolved.resolvedSourcePath,
+      },
       dirName,
       coreDir,
     );
@@ -215,7 +529,10 @@ export async function component(name, options = {}) {
   if (props) return componentDetailProps(docs);
   return componentDetail(
     docs,
-    {package: resolved.resolvedOwnerPackage, sourcePath: resolved.resolvedSourcePath},
+    {
+      package: resolved.resolvedOwnerPackage,
+      sourcePath: resolved.resolvedSourcePath,
+    },
     resolved.resolvedName,
     coreDir,
   );

package/api/component/component.test.mjs

@@ -14,6 +14,7 @@ import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {component} from './component.mjs';
 import {AstryxError} from '../error.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
 
 // api/component/ -> up 4 = repo root (has packages/core, which findCoreDir walks to).
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
@@ -161,3 +162,40 @@ describe('component dispatcher — category guard', () => {
     }
   }, SLOW);
 });
+
+describe('component dispatcher — detail and lang guards', () => {
+  // `detail` and `lang` are the same controls as the CLI's --detail and --lang:
+  // same accepted values, same error codes.
+  it('rejects a detail level the CLI rejects, with the same code', async () => {
+    const cliRun = await runCli(['--json', 'component', '--list', '--detail', 'bogus'], cwd);
+    expect(cliRun.code).toBe(1);
+    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_DETAIL');
+
+    const bogus = /** @type {any} */ ('bogus');
+    for (const call of [
+      () => component(undefined, {cwd, list: true, detail: bogus}),
+      () => component('Button', {cwd, detail: bogus}),
+    ]) {
+      const err = await call().catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_INVALID_DETAIL');
+    }
+  }, SLOW);
+
+  it('rejects a lang the CLI rejects, with the same code', async () => {
+    const cliRun = await runCli(['--json', 'component', 'Button', '--lang', 'fr'], cwd);
+    expect(cliRun.code).toBe(1);
+    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_LANG');
+
+    for (const call of [
+      () => component('Button', {cwd, lang: 'fr'}),
+      () => component(undefined, {cwd, list: true, detail: 'compact', lang: 'fr'}),
+    ]) {
+      const err = await call().catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_INVALID_LANG');
+    }
+    const zh = await component('Button', {cwd, lang: 'zh'});
+    expect(zh.type).toBe('component.detail');
+  }, SLOW);
+});

package/api/component/component.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json component [--list] [--category X] [--detail names|compact|full]
+ * astryx --json component [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `component.list` type across all three detail levels;
  * the depth is carried in `data.detail` and `data.components` holds the grouped
@@ -28,12 +28,38 @@ export type ComponentListData = ({
     detail: "full";
     components: Record<string, import("@astryxdesign/cli/authoring").ComponentDoc[]>;
 });
+/**
+ * `component(string[])` always returns this type, including empty and one-item
+ * arrays. The CLI returns it for two or more positional selectors.
+ */
+export type ComponentBatchResponse = import("../../foundation/response/batch.type.mjs").BatchResponse<"component.batch", ComponentSingleResponse, ComponentBatchCandidate>;
+/**
+ * One installed component that makes an unqualified selector ambiguous.
+ * Keys match a component row in `discover.search` so a caller does not learn a
+ * second candidate shape.
+ */
+export type ComponentBatchCandidate = {
+    package: string;
+    component: string;
+    kind: "component";
+    installed: true;
+};
+/**
+ * The response a successful single selector would have returned.
+ */
+export type ComponentSingleResponse = (ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse);
+/**
+ * One row per requested selector, in argument order. Duplicate selectors keep
+ * duplicate rows.
+ */
+export type ComponentBatchResult = import("../../foundation/response/batch.type.mjs").BatchRow<ComponentSingleResponse, ComponentBatchCandidate>;
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  */
 export type ComponentListEntry = {
     name: string;
@@ -42,7 +68,7 @@ export type ComponentListEntry = {
      */
     package: string;
     /**
-     * - Import specifier; present for integration components, absent for core.
+     * - Import specifier; present for integration and legacy package components, absent for core.
      */
     import?: string | undefined;
 };
@@ -55,11 +81,21 @@ export type ComponentBriefEntry = {
     import: string;
 };
 /**
- * xds --json component <name>
+ * astryx --json component <name>
  */
 export type ComponentDetailResponse = {
     type: "component.detail";
-    data: import("@astryxdesign/cli/authoring").ComponentDoc & ComponentOwnership;
+    data: import("@astryxdesign/cli/authoring").ComponentDoc & ComponentOwnership & ComponentDetailScope;
+};
+/**
+ * Present only when the requested name is a sub-component documented inside a
+ * parent's doc (e.g. `HStack` in the `Stack` doc); the payload is scoped to it.
+ */
+export type ComponentDetailScope = {
+    /**
+     * - Name of the parent doc the payload was scoped from, e.g. 'Stack'.
+     */
+    parentDoc?: string | undefined;
 };
 /**
  * Ownership metadata attached to every `component.detail` payload. Exposes the
@@ -81,14 +117,14 @@ export type ComponentOwnership = {
     sourceAvailable: boolean;
 };
 /**
- * xds --json component <name> --props
+ * astryx --json component <name> --props
  */
 export type ComponentDetailPropsResponse = {
     type: "component.detail.props";
     data: import("@astryxdesign/cli/authoring").ComponentPropDoc[];
 };
 /**
- * xds --json component <name> --source
+ * astryx --json component <name> --source
  */
 export type ComponentDetailSourceResponse = {
     type: "component.detail.source";
@@ -98,7 +134,7 @@ export type ComponentDetailSourceResponse = {
     };
 };
 /**
- * xds --json component <name> --showcase
+ * astryx --json component <name> --showcase
  */
 export type ComponentDetailShowcaseResponse = {
     type: "component.detail.showcase";
@@ -109,7 +145,7 @@ export type ComponentDetailShowcaseResponse = {
     };
 };
 /**
- * xds --json component <name> --blocks
+ * astryx --json component <name> --blocks
  */
 export type ComponentDetailBlocksResponse = {
     type: "component.detail.blocks";