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

package/api/build/kit/kit.mjs

@@ -28,6 +28,9 @@
  */
 
 import {search} from '../../search/search.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {getResultCoverage} from '../../search/coverage.mjs';
 import {loadPageTemplates} from '../_adapter.mjs';
 import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
@@ -188,12 +191,30 @@ function chooseStart(ranked, pages, directMatch, catalog) {
  */
 export async function buildKit(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 60} = options;
+  // A kit is built from Core's components, hooks, and templates. An open
+  // search without core covers the docs alone, so the kit asks for core here.
+  if (type !== 'doc' && !findCoreDir(cwd)) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
   // search()'s JSDoc @returns widens results to object[]; the SearchResponse
   // shape is the contract (api/search/search.type.mjs). Cast locally rather than
   // tightening the search @returns (a separate follow-up).
   const result =
     /** @type {import('../../search/search.type.mjs').SearchResponse} */ (
-      await search(query, {cwd, type, limit})
+      await search(query, {
+        cwd,
+        type,
+        // Search wider than the surfaced kit so a flood of doc matches cannot
+        // bury the page templates past the cutoff; the caller's `limit` still
+        // caps the kit below. A non-positive or non-integer limit is passed
+        // through unchanged so search rejects it (ERR_INVALID_ARGUMENT).
+        limit:
+          Number.isInteger(limit) && limit > 0 ? Math.max(limit, 200) : limit,
+      })
     );
   const results = result.data.results;
   // The TOTAL number of matches, not the number that survived `limit`. The kit
@@ -257,6 +278,24 @@ export async function buildKit(query, options = {}) {
         command: `${page.command} --skeleton`,
       }));
 
+  // The caller's `limit` caps the surfaced kit, even though the search above
+  // ran wider to find templates that a flood of doc matches would otherwise
+  // bury past the cutoff. Keep pages first, then blocks, then components.
+  let budget = limit;
+  /**
+   * @template T
+   * @param {T[]} arr
+   * @returns {T[]}
+   */
+  const toLimit = arr => {
+    const out = arr.slice(0, Math.max(0, budget));
+    budget -= out.length;
+    return out;
+  };
+  const pagesKept = toLimit(pages);
+  const blocksKept = toLimit(blocks);
+  const domainKept = toLimit(domain);
+
   // A kit narrowed to components or hooks has no page to start from; every
   // other kit does, so the reader is never left to compose a page from scratch.
   const wantsPages = !type || type === 'template';
@@ -288,7 +327,7 @@ export async function buildKit(query, options = {}) {
   // not resolve — the same defect `getCliInvocation` exists to prevent, and
   // the renderer applies it. A JSON caller gets the parts, not a sentence.
   const hint =
-    pages.length + blocks.length + domain.length < THIN_KIT
+    pagesKept.length + blocksKept.length + domainKept.length < THIN_KIT
       ? {
           reason:
             'Few matches. This is keyword search, not semantic — try other wordings.',
@@ -306,9 +345,9 @@ export async function buildKit(query, options = {}) {
       matchCount,
       directMatch,
       start,
-      pages,
-      blocks,
-      domain,
+      pages: pagesKept,
+      blocks: blocksKept,
+      domain: domainKept,
       frame: FRAME,
       foundation: FOUNDATION,
       hint,

package/api/component/_adapter.d.mts

@@ -68,6 +68,16 @@ export function requireCoreDir(cwd: string): string;
  * @returns {Promise<import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]>}
  */
 export function loadIntegrationsSafely(cwd: string): Promise<import("../../foundation/integrations/integrations.mjs").LoadedIntegration[]>;
+/**
+ * Read the exact installed version available to a package-qualified component
+ * selector. Legacy docs packages do not expose a reliable version here, so a
+ * version-qualified lookup never falls through to them.
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function installedComponentPackageVersion(coreDir: string, loadedIntegrations: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[], packageName: string): string | null;
 /**
  * Build the set of OWNER packages that provide a component with this name
  * across core + every loaded integration. This is what lets the CLI
@@ -180,6 +190,20 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
     matchingComponent: any;
 } | null;
 export { CORE_PACKAGE };
+/**
+ * Internal ambiguity marker. Single-component callers still receive the same
+ * AstryxError code, message, and suggestions; batch callers can additionally
+ * project every installed candidate without parsing prose.
+ */
+export class ComponentAmbiguityError extends AstryxError {
+    /**
+     * @param {ComponentOwner[]} owners
+     * @param {string} dirName
+     */
+    constructor(owners: ComponentOwner[], dirName: string);
+    /** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
+    candidates: import("./component.type.mjs").ComponentBatchCandidate[];
+}
 /**
  * A loaded component doc. The shared validated loader accepts stamped and legacy
  * component docs; this loose view captures the fields the API reads across both.
@@ -258,3 +282,4 @@ export type ResolvedUnscopedDoc = {
     resolvedSourcePath: string | null;
 };
 import { CORE_PACKAGE } from '../../foundation/discovery/component-discovery.mjs';
+import { AstryxError } from '../error.mjs';

package/api/component/_adapter.mjs

@@ -18,6 +18,8 @@
  * deduped, so each leaf stays a thin projection.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {
   findCoreDir,
@@ -146,6 +148,34 @@ function findLoadedIntegration(loadedIntegrations, packageName) {
   return loadedIntegrations.find(i => i.name === packageName) ?? null;
 }
 
+/**
+ * Read the exact installed version available to a package-qualified component
+ * selector. Legacy docs packages do not expose a reliable version here, so a
+ * version-qualified lookup never falls through to them.
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function installedComponentPackageVersion(
+  coreDir,
+  loadedIntegrations,
+  packageName,
+) {
+  if (packageName === CORE_PACKAGE) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(coreDir, 'package.json'), 'utf8'),
+      );
+      return typeof pkg.version === 'string' ? pkg.version : null;
+    } catch {
+      return null;
+    }
+  }
+  const integration = findLoadedIntegration(loadedIntegrations, packageName);
+  return typeof integration?.version === 'string' ? integration.version : null;
+}
+
 /**
  * Resolve an external package by name from the discovered externals list.
  * @param {string} packageName - e.g. '@acme/xds-widgets'
@@ -244,6 +274,34 @@ export function classifyScope(
   return {kind: 'legacy', ext};
 }
 
+/**
+ * Internal ambiguity marker. Single-component callers still receive the same
+ * AstryxError code, message, and suggestions; batch callers can additionally
+ * project every installed candidate without parsing prose.
+ */
+export class ComponentAmbiguityError extends AstryxError {
+  /** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
+  candidates;
+
+  /**
+   * @param {ComponentOwner[]} owners
+   * @param {string} dirName
+   */
+  constructor(owners, dirName) {
+    super(
+      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
+      owners.map(o => ({name: o.package, reason: 'provides this component'})),
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+    this.candidates = owners.map(owner => ({
+      package: owner.package,
+      component: dirName,
+      kind: 'component',
+      installed: true,
+    }));
+  }
+}
+
 /**
  * Refuse to guess when the name is owned by MORE THAN ONE package (core and/or
  * integrations) and the caller did not scope with --package. Legacy
@@ -254,11 +312,7 @@ export function classifyScope(
  */
 export function assertUnambiguousOwners(owners, dirName) {
   if (owners.length > 1) {
-    throw new AstryxError(
-      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
-      owners.map(o => ({name: o.package, reason: 'provides this component'})),
-      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
-    );
+    throw new ComponentAmbiguityError(owners, dirName);
   }
 }
 

package/api/component/component.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @param {string} [name]
+ * @param {string|string[]} [name]
  * @param {object} [options]
  * @param {string} [options.cwd]
  * @param {boolean} [options.list]
@@ -18,6 +18,7 @@
  * @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
@@ -25,7 +26,7 @@
  *   | import('./component.type.mjs').ComponentDetailBlocksResponse
  * )>}
  */
-export function component(name?: string, options?: {
+export function component(name?: string | string[], options?: {
     cwd?: string | undefined;
     list?: boolean | undefined;
     category?: string | undefined;
@@ -38,4 +39,6 @@ export function component(name?: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
-}): Promise<(import("./component.type.mjs").ComponentListResponse | import("./component.type.mjs").ComponentDetailResponse | import("./component.type.mjs").ComponentDetailPropsResponse | import("./component.type.mjs").ComponentDetailSourceResponse | import("./component.type.mjs").ComponentDetailShowcaseResponse | import("./component.type.mjs").ComponentDetailBlocksResponse)>;
+}): 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 | import("./component.type.mjs").ComponentDetailShowcaseResponse | import("./component.type.mjs").ComponentDetailBlocksResponse)>;
+/** Maximum selectors accepted before any component resolution starts. */
+export const COMPONENT_BATCH_SELECTOR_LIMIT: 100;

package/api/component/component.doc.mjs

@@ -15,16 +15,16 @@ export const doc = {
   namespace: 'cli/api',
   displayName: 'component()',
   summary:
-    'Resolve a component by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
+    'Resolve one or several components by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
   description:
-    'Routes on its arguments: a name resolves that component across core and ' +
-    'integration packages and returns its authored ComponentDoc plus ownership ' +
-    'metadata; no name (or `list`/`category`) returns the catalog grouped by ' +
-    'category. Boolean flags narrow a single component to just its props, ' +
-    'source, showcase, or example blocks.',
+    'Routes on its arguments: one string resolves that component across core and ' +
+    'integration packages; an array returns one ordered result row per selector at ' +
+    'every array length; and no name returns the catalog grouped by category. ' +
+    'Boolean flags narrow each resolved component to just its props, source, ' +
+    'showcase, or example blocks.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'component(name?: string, options?: ComponentOptions): Promise<ComponentListResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
+    'component(name?: string | string[], options?: ComponentOptions): Promise<ComponentListResponse | ComponentBatchResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
   keywords: [
     'component',
     'components',
@@ -37,14 +37,15 @@ export const doc = {
   params: [
     {
       name: 'name',
-      type: 'string',
+      type: 'string | string[]',
       description:
-        "Component name to resolve (e.g. 'Button'). Omit to list the catalog.",
+        "Pass one selector string for the existing single-result response, or an array of at most 100 selectors for an ordered component.batch response. The limit counts duplicates in every projection mode. An array always requests a batch, including [] and ['Button']. Use 'Button', 'widgets/Button', '@acme/widgets/Button', or '@acme/widgets@1.2.3/Button'. A version applies to the package and must match the installed version. Omit the argument to list the catalog.",
     },
     {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory to resolve @astryxdesign/core from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.list',
@@ -54,13 +55,14 @@ export const doc = {
     {
       name: 'options.category',
       type: 'string',
-      description: 'List only components in this category.',
+      description:
+        "List only the components in this group: a key of the unfiltered list (each component's group field), such as 'Layout' or 'Button'. It is not the category field of a component detail.",
     },
     {
       name: 'options.package',
       type: 'string',
       description:
-        "Scope lookup to a specific external package (e.g. '@acme/xds-widgets').",
+        "Scope lookup to a specific external package (e.g. '@acme/widgets').",
     },
     {
       name: 'options.props',
@@ -87,7 +89,8 @@ export const doc = {
       name: 'options.detail',
       type: "'full' | 'compact' | 'brief'",
       description: 'Detail level for list views.',
-      default: "'full' for a named component, 'brief' for list views",
+      default:
+        "'full' for a named component; 'brief' for lists (returned as data.detail: 'names')",
     },
     {
       name: 'options.lang',
@@ -110,7 +113,12 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
+        "The catalog grouped by component group. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
+    },
+    {
+      type: 'component.batch',
+      description:
+        'An explicit selector array returns one ordered receipt at every array length: count and one results row per selector, including duplicates. ComponentBatchResponse specializes the shared BatchResponse and BatchRow types. Each row carries selector and status (found, not_found, ambiguous, or error); found rows carry the single-selector result, ambiguous rows carry installed candidates ({package, component, kind, installed}), and failed rows carry code, error, and optional suggestions.',
     },
     {
       type: 'component.detail',
@@ -137,6 +145,10 @@ export const doc = {
     },
   ],
   throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: 'a selector array has more than 100 entries, a package-shaped selector has no component item, or its package conflicts with options.package',
+    },
     {
       code: 'ERR_INVALID_DETAIL',
       when: "options.detail is not 'full', 'compact', or 'brief'",
@@ -151,7 +163,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
-      when: 'options.category is not a string or matches no known category',
+      when: 'options.category is not a string or matches no component group',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',
@@ -159,12 +171,16 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_PACKAGE',
-      when: 'options.package names a legacy external package that cannot be found',
+      when: 'options.package names a legacy external package that cannot be found, or a package-qualified selector requests a version that is not installed',
     },
     {
       code: 'ERR_NO_DOC',
       when: 'the resolved component has no .doc.mjs typed doc file',
     },
+    {
+      code: 'ERR_INVALID_DOC',
+      when: "the resolved component's .doc.mjs fails to load or validate",
+    },
     {
       code: 'ERR_NO_SOURCE',
       when: 'options.source is set but the component has no source file',
@@ -179,10 +195,14 @@ export const doc = {
       label: 'Look up a component',
       code: "const r = await component('Button');",
     },
+    {
+      label: 'Look up several components',
+      code: "await component(['Button', 'Badge']);",
+    },
     {label: 'Props only', code: "await component('Button', {props: true});"},
     {
-      label: 'Browse a category',
-      code: "await component(undefined, {category: 'Form', detail: 'compact'});",
+      label: 'Browse one group',
+      code: "await component(undefined, {category: 'Layout', detail: 'compact'});",
     },
   ],
   command: 'component',