@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/component/_adapter.mjs

@@ -22,27 +22,62 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {
-  findCoreDir,
+  requireCoreDir as requireAnswerCoreDir,
   discoverExternalPackages,
 } from '../../foundation/fs/paths.mjs';
 import {
   CORE_PACKAGE,
   discoverComponents,
+  docStem,
   findComponentReadme,
   findComponentSource,
   findExternalComponentDoc,
-  findIntegrationComponentDoc,
-  findIntegrationComponentSource,
+  findIntegrationComponent,
+  integrationMemberEntry,
+  isIntegrationMember,
+  recordedDocName,
   resolveImportPath,
   resolveIntegrationImportPath as resolveIntegrationImport,
+  unscopedComponentOwners,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {Project} from '../../foundation/config/project.mjs';
 import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
 import {resolveComponentReplacements} from '../../foundation/discovery/component-replacement.mjs';
 import {searchComponents} from '../../foundation/text/string-utils.mjs';
-import {AstryxError} from '../error.mjs';
+import {
+  rankComponentSuggestions,
+  synonymMatches,
+} from '../../foundation/text/suggest-order.mjs';
+import {AstryxError, coreDirOrThrow} from '../error.mjs';
+import {
+  componentLinkProvider,
+  linkComponentDoc,
+  loadDocsCatalog,
+} from '../docs/_adapter.mjs';
 
-export {CORE_PACKAGE};
+/** @type {Record<string, {synonyms?: string[]}> | undefined} */
+let cards;
+/**
+ * Search's component cards (each component's other names), read once.
+ * @returns {Record<string, {synonyms?: string[]}>}
+ */
+function searchCards() {
+  if (!cards) {
+    try {
+      cards = JSON.parse(
+        fs.readFileSync(
+          new URL('../search/_cards.json', import.meta.url),
+          'utf8',
+        ),
+      );
+    } catch {
+      cards = {};
+    }
+  }
+  return /** @type {Record<string, {synonyms?: string[]}>} */ (cards);
+}
+
+export {CORE_PACKAGE, unscopedComponentOwners};
 
 /**
  * A loaded component doc. The shared validated loader accepts stamped and legacy
@@ -71,6 +106,8 @@ export {CORE_PACKAGE};
  * @property {string|null} sourcePath
  * @property {string|undefined} issuesUrl
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
+ * @property {import('../../foundation/discovery/component-discovery.mjs').NameHold} hold
+ *   how the owner holds the name, for the owner rule
  */
 
 /**
@@ -110,15 +147,7 @@ export {CORE_PACKAGE};
  * @returns {string}
  */
 export function requireCoreDir(cwd) {
-  const coreDir = findCoreDir(cwd);
-  if (!coreDir) {
-    throw new AstryxError(
-      'Could not find @astryxdesign/core package',
-      undefined,
-      ERROR_CODES.ERR_CORE_NOT_FOUND,
-    );
-  }
-  return coreDir;
+  return coreDirOrThrow(requireAnswerCoreDir, cwd);
 }
 
 /**
@@ -240,17 +269,19 @@ export function resolveOwners(coreDir, dirName, loadedIntegrations) {
       sourcePath: findComponentSource(coreDir, dirName),
       issuesUrl: undefined,
       integration: null,
+      hold: 'core',
     });
   }
   for (const integration of loadedIntegrations) {
-    const docPath = findIntegrationComponentDoc(integration, dirName);
-    if (!docPath) continue;
+    const found = findIntegrationComponent(integration, dirName);
+    if (!found) continue;
     owners.push({
       package: integration.name,
-      docPath,
-      sourcePath: findIntegrationComponentSource(integration, dirName),
+      docPath: found.docPath,
+      sourcePath: found.sourcePath,
       issuesUrl: integration.issuesUrl,
       integration,
+      hold: found.hold,
     });
   }
   return owners;
@@ -361,6 +392,39 @@ export function resolveLegacyExternalDoc(ext, dirName) {
   return extDocPath && extDocPath.endsWith('.doc.mjs') ? extDocPath : null;
 }
 
+/**
+ * Whether a legacy external package documents `dirName`.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @returns {boolean}
+ */
+export function legacyExternalDocuments(cwd, dirName) {
+  return discoverExternalPackages(cwd).some(
+    ext => resolveLegacyExternalDoc(ext, dirName) != null,
+  );
+}
+
+/**
+ * Whether a legacy docs package keeps `dirName` over these owners, each of which
+ * holds it only as an export a doc records.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @param {Array<{hold?: string, docPath?: string | null}>} owners
+ * @returns {boolean}
+ */
+export function legacyExternalKeeps(cwd, dirName, owners) {
+  return (
+    owners.length > 0 &&
+    owners.every(
+      owner =>
+        owner.hold === 'doc' &&
+        owner.docPath != null &&
+        docStem(owner.docPath).toLowerCase() !== dirName.toLowerCase(),
+    ) &&
+    legacyExternalDocuments(cwd, dirName)
+  );
+}
+
 /**
  * The core source file for `dirName` (the no-scope `--source` path reads core
  * directly — it does NOT fall back to externals or fuzzy search).
@@ -425,12 +489,20 @@ export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
         resolvedOwnerPackage = CORE_PACKAGE;
         resolvedSourcePath = findComponentSource(coreDir, resolvedName);
       } else {
+        // How many to suggest: the near-top results, at most five and at
+        // least two. Which ones, and in what order, is the suggestion
+        // ranking's call.
         const threshold = Math.max(topScore - 20, 1);
-        const candidates = results
-          .filter(r => r.score >= threshold)
-          .slice(0, 5);
-        if (candidates.length < 2)
-          candidates.push(...results.slice(candidates.length, 2));
+        const count = Math.max(
+          results.filter(r => r.score >= threshold).slice(0, 5).length,
+          Math.min(2, results.length),
+        );
+        const candidates = rankComponentSuggestions(
+          dirName,
+          results,
+          Object.values(components).flat(),
+          synonymMatches(dirName, searchCards()),
+        ).slice(0, count);
         throw new AstryxError(
           `No component named "${name}"`,
           candidates.map(c => ({name: c.name, reason: c.reason})),
@@ -583,3 +655,159 @@ export function scopeSubComponent(docs, dirName, coreDir) {
 
   return {scoped, matchingComponent};
 }
+
+/**
+ * The doc an integration owner shows for `dirName`: when `dirName` is a member
+ * its family doc lists under its own name (`AcmeSlide` in an `AcmeCarousel`
+ * doc), the doc scoped to that member as {@link scopeSubComponent} scopes
+ * Core's, keeping the import the family doc states; otherwise `docs` itself.
+ * @param {LoadedComponentDoc} docs
+ * @param {OwnershipSubject} owner
+ * @param {string} dirName
+ * @returns {LoadedComponentDoc & {parentDoc?: string, import?: string}}
+ */
+export function scopeIntegrationMember(docs, owner, dirName) {
+  const record = {name: dirName, docPath: owner.docPath ?? null};
+  if (!isIntegrationMember(record)) return docs;
+  const entry = integrationMemberEntry(docs, record);
+  // The files list the member but the doc this process loaded has no entry
+  // for it (the doc changed after it loaded): never answer with the family.
+  if (entry == null) {
+    throw new AstryxError(
+      `No component named "${dirName}": its family doc changed after this process loaded it.`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+  // Built from the entry, as scopeSubComponent scopes Core's, so a member that
+  // shares the doc's own `name` is scoped too.
+  /** @type {LoadedComponentDoc & {parentDoc?: string, import?: string}} */
+  const scoped = {
+    name: dirName,
+    description: entry.description,
+    props: entry.props,
+    components: [entry],
+    // The name the family doc opens under, for every member.
+    parentDoc:
+      owner.integration && record.docPath
+        ? recordedDocName(owner.integration, record.docPath)
+        : docs.name === dirName && record.docPath
+          ? docStem(record.docPath)
+          : docs.name,
+  };
+  if (docs.usage) scoped.usage = docs.usage;
+  if (docs.theming) scoped.theming = docs.theming;
+  if (docs.import) scoped.import = docs.import;
+  return scoped;
+}
+
+/**
+ * A search response with every inline `{@link <target>}` in a component
+ * result's description resolved to the command that opens the doc it names,
+ * as `astryx component` prints it (spec:AST-047 FR9). The response object is
+ * kept, with its results replaced.
+ * @template {{data: {results: any[]}}} R
+ * @param {R} response
+ * @param {string} cwd
+ * @returns {Promise<R>}
+ */
+export async function linkSearchResponse(response, cwd) {
+  const results = response.data.results;
+  if (
+    !results.some(
+      result =>
+        result?.domain === 'component' &&
+        typeof result.description === 'string' &&
+        result.description.includes('{@link'),
+    )
+  ) {
+    return response;
+  }
+  const linked = [];
+  for (const result of results) {
+    if (
+      result?.domain !== 'component' ||
+      typeof result.description !== 'string' ||
+      !result.description.includes('{@link')
+    ) {
+      linked.push(result);
+      continue;
+    }
+    const read = await linkComponentResponse(
+      {
+        type: 'component.detail',
+        package: result.package,
+        data: {description: result.description},
+      },
+      cwd,
+    );
+    linked.push({...result, description: read.data.description});
+  }
+  response.data = {...response.data, results: linked};
+  return response;
+}
+
+/**
+ * A component read with every inline `{@link <target>}` in its doc text
+ * resolved to the command that opens the doc it names (spec:AST-047 FR9), in
+ * the detail, its props projection, and each list entry. A Core component's
+ * links resolve against the CLI's own docs; an integration's against that
+ * integration's. A link that names no doc prints as written.
+ * @template {{type: string, package?: string, data?: any}} R
+ * @param {R} response
+ * @param {string} cwd
+ * @returns {Promise<R>}
+ */
+export async function linkComponentResponse(response, cwd) {
+  const {type} = response;
+  if (
+    type !== 'component.detail' &&
+    type !== 'component.detail.props' &&
+    type !== 'component.list'
+  ) {
+    return response;
+  }
+  if (!JSON.stringify(response.data ?? null).includes('{@link')) {
+    return response;
+  }
+  const catalog = await loadDocsCatalog(cwd);
+  /** @type {Map<string, string>} */
+  const declared = new Map();
+  for (const integration of await loadIntegrationsSafely(cwd)) {
+    const id = /** @type {any} */ (integration).providerId;
+    if (typeof id === 'string') declared.set(integration.name, id);
+  }
+  /**
+   * @param {any} doc
+   * @param {string | undefined} owner
+   */
+  const link = async (doc, owner) => {
+    if (typeof owner !== 'string') return doc;
+    try {
+      return (
+        await linkComponentDoc(
+          catalog,
+          componentLinkProvider(owner, declared.get(owner)),
+          doc,
+        )
+      ).doc;
+    } catch {
+      // An owner that is not a provider id links nothing; its text reads as
+      // written.
+      return doc;
+    }
+  };
+  if (type !== 'component.list') {
+    return {...response, data: await link(response.data, response.package)};
+  }
+  /** @type {Record<string, any[]>} */
+  const components = {};
+  for (const [group, entries] of Object.entries(
+    response.data.components ?? {},
+  )) {
+    const linked = [];
+    for (const entry of entries) linked.push(await link(entry, entry?.package));
+    components[group] = linked;
+  }
+  return {...response, data: {...response.data, components}};
+}

package/api/component/component-replacement.test.mjs

@@ -64,6 +64,7 @@ function writeIntegration(name, components, peers) {
         type: 'component',
         name: componentName,
         displayName: componentName,
+        import: `${name}/components/${componentName}`,
         ...(replaces ? {replaces} : {}),
         keywords: ['acme'],
         usage: {description: `${componentName} for Acme apps.`},

package/api/component/component.doc.mjs

@@ -24,7 +24,8 @@ export const doc = {
     'showcase, or example blocks. An integration component that replaces a Core ' +
     'component (its doc sets replaces, and its package declares the CLI range that ' +
     'turns replacement on) answers to the Core name in detail, batch, and list ' +
-    "results; use options.package '@astryxdesign/core' for the original.",
+    "results; use options.package '@astryxdesign/core' for the original." +
+    " In global mode: with `cwd` outside a project, components from integrations installed next to this CLI package globally resolve too; inside a project, only the project's own integrations count. See {@link namespace:global} and {@link generic:computer-integrations}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'component(name?: string | string[], options?: ComponentOptions): Promise<ComponentListResponse | ComponentBatchResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
@@ -164,6 +165,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: '@astryxdesign/core cannot be resolved from cwd',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'outside a project, or in a project with nothing installed, the Core of the release that answers is not beside it or cached, and cannot be installed into the per-user cache (offline, a registry without it, or an unwritable cache)',
+    },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
       when: 'options.category is not a string or matches no component group',

package/api/component/component.mjs

@@ -19,9 +19,11 @@ import {
   requireCoreDir,
   loadIntegrationsSafely,
   resolveOwners,
+  scopeIntegrationMember,
   classifyScope,
   assertUnambiguousOwners,
   resolveLegacyExternalDoc,
+  legacyExternalKeeps,
   resolveCoreSourcePath,
   resolveUnscopedDoc,
   loadComponentDoc,
@@ -29,6 +31,8 @@ import {
   ComponentAmbiguityError,
   installedComponentPackageVersion,
   resolveComponentReplacement,
+  unscopedComponentOwners,
+  linkComponentResponse,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -254,6 +258,23 @@ async function componentBatch(selectors, options, coreDir) {
  * )>}
  */
 export async function component(name, options = {}) {
+  // Every read resolves the links in the doc text it returns (spec:AST-047
+  // FR9); a batch's results are each a read of their own.
+  return /** @type {any} */ (
+    await linkComponentResponse(
+      await componentRead(name, options),
+      options.cwd ?? process.cwd(),
+    )
+  );
+}
+
+/**
+ * {@link component}, with each `{@link}` in its doc text as written.
+ * @param {string|string[]} [name]
+ * @param {Parameters<typeof component>[1]} [options]
+ * @returns {ReturnType<typeof component>}
+ */
+async function componentRead(name, options = {}) {
   const {
     cwd = process.cwd(),
     list = false,
@@ -272,7 +293,7 @@ export async function component(name, options = {}) {
   const selectorList = Array.isArray(name) ? name : null;
   const noName = selectorList == null && !name;
 
-  // Default detail level mirrors the CLI (see commands/component/index.mjs):
+  // Default detail level mirrors the CLI (see commands/component.mjs):
   // single-component views default to 'full', list-style views (--list,
   // --category, or no name) default to 'brief' (scannable name lists).
   // An explicit array remains a batch even when it is empty or a caller also
@@ -354,7 +375,7 @@ export async function component(name, options = {}) {
       requireInstalledSelectorVersion(target, coreDir, loadedIntegrations);
     }
     if (target.name !== name || target.package !== packageScope) {
-      return component(target.name, {...options, package: target.package});
+      return componentRead(target.name, {...options, package: target.package});
     }
     name = target.name;
   }
@@ -393,7 +414,10 @@ export async function component(name, options = {}) {
         dirName,
       );
       if (replacement?.package === packageScope) {
-        return component(replacement.name, {...options, package: packageScope});
+        return componentRead(replacement.name, {
+          ...options,
+          package: packageScope,
+        });
       }
     }
     const scoped = classifyScope(packageScope, {
@@ -421,20 +445,54 @@ export async function component(name, options = {}) {
       // a showcase, so skip discovery entirely.
       if (showcase) {
         return scoped.kind === 'core'
-          ? componentDetailShowcase(dirName, {cwd, name, ownerPackage: owner.package})
-          : componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
+          ? componentDetailShowcase(dirName, {
+              cwd,
+              name,
+              ownerPackage: owner.package,
+            })
+          : componentDetailShowcase(dirName, {
+              cwd,
+              name,
+              resolve: false,
+              ownerPackage: owner.package,
+            });
       }
       if (blocks) {
         return componentDetailBlocks(dirName, cwd, owner.package);
       }
-      const docs = await loadComponentDoc(owner.docPath, docOpts);
+      const loaded = await loadComponentDoc(owner.docPath, docOpts);
+      // A family member reads as that member, scoped the way the unscoped
+      // lookup scopes it: an integration member by its own entry, a Core
+      // sub-component (HStack in the Stack doc) by scopeSubComponent.
+      const sub =
+        scoped.kind === 'core'
+          ? scopeSubComponent(loaded, dirName, coreDir)
+          : null;
+      if (sub) {
+        if (props) {
+          return componentDetailProps(
+            {props: sub.matchingComponent.props},
+            owner.package,
+          );
+        }
+        return componentDetail(sub.scoped, owner, dirName, coreDir);
+      }
+      const docs =
+        scoped.kind === 'integration'
+          ? scopeIntegrationMember(loaded, owner, dirName)
+          : loaded;
       if (props) return componentDetailProps(docs, owner.package);
       return componentDetail(docs, owner, dirName, coreDir);
     }
 
     // Legacy `pkg.astryx.docs` external package.
     if (showcase) {
-      return componentDetailShowcase(dirName, {cwd, name, packageScope, ownerPackage: packageScope});
+      return componentDetailShowcase(dirName, {
+        cwd,
+        name,
+        packageScope,
+        ownerPackage: packageScope,
+      });
     }
     const extDocPath = resolveLegacyExternalDoc(scoped.ext, dirName);
     if (extDocPath) {
@@ -475,18 +533,20 @@ export async function component(name, options = {}) {
     dirName,
   );
   if (replacement) {
-    return component(replacement.name, {
+    return componentRead(replacement.name, {
       ...options,
       package: replacement.package,
     });
   }
 
+  // The owner rule runs first, over valid and invalid owners alike.
+  const ruled = unscopedComponentOwners(owners);
   // Invalid integration metadata does not create ambiguity against a valid
-  // owner. Keep raw owners only when no doc owner is valid, so an integration-
+  // owner. Keep ruled 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) {
+  for (const owner of ruled) {
     if (owner.package === CORE_PACKAGE) {
       validOwners.push(owner);
       continue;
@@ -498,7 +558,12 @@ export async function component(name, options = {}) {
       // Project/Doctor report invalid metadata; it is not an effective owner.
     }
   }
-  const effectiveOwners = validOwners.length > 0 ? validOwners : owners;
+  const loadable = validOwners.length > 0 ? validOwners : ruled;
+  // A legacy docs package's exact doc keeps its name over an export name a doc
+  // records, as Core and file-named owners do.
+  const effectiveOwners = legacyExternalKeeps(cwd, dirName, loadable)
+    ? []
+    : loadable;
 
   // ── Ambiguity: owned by MORE THAN ONE valid package, no --package ──
   assertUnambiguousOwners(effectiveOwners, dirName);
@@ -510,13 +575,22 @@ export async function component(name, options = {}) {
   ) {
     const owner = effectiveOwners[0];
     if (source) {
-      return componentDetailSource(dirName, owner.sourcePath, {name, ownerPackage: owner.package});
+      return componentDetailSource(dirName, owner.sourcePath, {
+        name,
+        ownerPackage: owner.package,
+      });
     }
     if (showcase) {
       // Integration components don't carry showcases — fail without scanning.
-      return componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
+      return componentDetailShowcase(dirName, {
+        cwd,
+        name,
+        resolve: false,
+        ownerPackage: owner.package,
+      });
     }
-    const docs = await loadComponentDoc(owner.docPath, docOpts);
+    const loaded = await loadComponentDoc(owner.docPath, docOpts);
+    const docs = scopeIntegrationMember(loaded, owner, dirName);
     if (props) return componentDetailProps(docs, owner.package);
     return componentDetail(docs, owner, dirName, coreDir);
   }
@@ -531,7 +605,11 @@ export async function component(name, options = {}) {
     );
   }
   if (showcase) {
-    return componentDetailShowcase(dirName, {cwd, name, ownerPackage: CORE_PACKAGE});
+    return componentDetailShowcase(dirName, {
+      cwd,
+      name,
+      ownerPackage: CORE_PACKAGE,
+    });
   }
 
   const resolved = await resolveUnscopedDoc(dirName, {coreDir, cwd, name});
@@ -548,7 +626,10 @@ export async function component(name, options = {}) {
   const sub = scopeSubComponent(docs, dirName, coreDir);
   if (sub) {
     if (props)
-      return componentDetailProps({props: sub.matchingComponent.props}, resolved.resolvedOwnerPackage);
+      return componentDetailProps(
+        {props: sub.matchingComponent.props},
+        resolved.resolvedOwnerPackage,
+      );
     return componentDetail(
       sub.scoped,
       {