Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
28.2 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Shared resolver for the `component` command leaves.
 *
 * @input  a component name (+ cwd / package scope) and doc-load options
 * @output resolved subjects the leaves project into their one `{type, data}`
 *         envelope — owners across core/integration, the scoped/legacy/fuzzy
 *         resolution, and the doc-loading / prop-extraction / ownership shaping
 * @position api/component (internal; NOT a response-type leaf, not exported
 *           from ./api). Every view of a component agrees because it resolves
 *           the subject HERE once; the leaves never re-resolve or do I/O of
 *           their own beyond fetching their single subject.
 *
 * This is a PURE REORG of the resolution that used to be inlined (and
 * duplicated across branches) in component.mjs: the core/external/scoped/
 * integration lookup, ambiguity handling, and fuzzy search now live here,
 * 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 {
  requireCoreDir as requireAnswerCoreDir,
  discoverExternalPackages,
} from '../../foundation/fs/paths.mjs';
import {
  CORE_PACKAGE,
  discoverComponents,
  docStem,
  findComponentReadme,
  findComponentSource,
  findExternalComponentDoc,
  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 {
  rankComponentSuggestions,
  synonymMatches,
} from '../../foundation/text/suggest-order.mjs';
import {AstryxError, coreDirOrThrow} from '../error.mjs';
import {levenshteinDistance} from '../../foundation/text/levenshtein.mjs';
import {
  componentLinkProvider,
  linkComponentDoc,
  loadDocsCatalog,
} from '../docs/_adapter.mjs';

/** How far below the first suggestion's score a later one may be. */
const NEAR_FIRST = 10;

/** @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
 * component docs; this loose view captures the fields the API reads across both.
 * @typedef {object} LoadedComponentDoc
 * @property {string} [name]
 * @property {string} [description]
 * @property {any[]} [props]
 * @property {any[]} [components]
 * @property {{description?: string}} [usage]
 * @property {any} [theming]
 * @property {string} [import] set when the doc states its own import specifier
 */

/**
 * Options object for the shared component-doc loader.
 * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
 */

/**
 * An OWNER package that provides a component with a given name: the doc/source
 * paths and the issues URL a later integration-component swizzle needs.
 * @typedef {object} ComponentOwner
 * @property {string} package
 * @property {string} docPath
 * @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
 */

/**
 * What ownership shaping needs from an owner. The core and legacy-external
 * paths synthesize a bare `{package, sourcePath}` rather than resolving a full
 * {@link ComponentOwner}, so everything past those two is optional here.
 * @typedef {Partial<ComponentOwner> & {package: string, sourcePath: string|null}} OwnershipSubject
 */

/**
 * A back-compat external package discovered via `pkg.astryx.docs`.
 * @typedef {{name: string, category: string, docsDir: string}} ExternalPackageRef
 */

/**
 * The outcome of scoping a lookup to a specific `--package`.
 * @typedef {(
 *   | {kind: 'core', owner: ComponentOwner}
 *   | {kind: 'integration', owner: ComponentOwner}
 *   | {kind: 'legacy', ext: ExternalPackageRef}
 * )} ScopeResolution
 */

/**
 * The result of resolving a bare (unscoped) name to a doc: which file, under
 * which resolved name/owner, and where its swizzleable source lives.
 * @typedef {object} ResolvedUnscopedDoc
 * @property {string} readmePath
 * @property {string} resolvedName
 * @property {string} resolvedOwnerPackage
 * @property {string|null} resolvedSourcePath
 */

/**
 * Locate `@astryxdesign/core`, throwing the stable not-found error when absent.
 * @param {string} cwd
 * @returns {string}
 */
export function requireCoreDir(cwd) {
  return coreDirOrThrow(requireAnswerCoreDir, cwd);
}

/**
 * Load the configured integrations for `cwd`, swallowing any config errors so
 * component discovery never hard-fails on a malformed/absent integration. An
 * empty list means "core only".
 * @param {string} cwd
 * @returns {Promise<import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]>}
 */
export async function loadIntegrationsSafely(cwd) {
  try {
    const project = await Project.load(cwd);
    return /** @type {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} */ (
      project.loadedIntegrations
    );
  } catch {
    return [];
  }
}

/**
 * Every component replacement the loaded integrations declare
 * (spec:AST-035 FR10–FR15): the active one for each replaced Core component,
 * and the findings Doctor reports. With no Core directory, only the opt-in
 * and value findings are computed.
 * @param {string|null} coreDir
 * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
 * @returns {Promise<import('../../foundation/discovery/component-replacement.mjs').ComponentReplacements>}
 */
export function loadComponentReplacements(coreDir, loadedIntegrations) {
  return resolveComponentReplacements(coreDir, loadedIntegrations);
}

/**
 * The integration component that answers to the Core component name
 * `dirName` for unqualified lookup, or undefined when none replaces it.
 * @param {string} coreDir
 * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
 * @param {string} dirName
 * @returns {Promise<import('../../foundation/discovery/component-replacement.mjs').ActiveComponentReplacement | undefined>}
 */
export async function resolveComponentReplacement(
  coreDir,
  loadedIntegrations,
  dirName,
) {
  if (loadedIntegrations.length === 0) return undefined;
  return (
    await resolveComponentReplacements(coreDir, loadedIntegrations)
  ).forTarget(dirName);
}

/**
 * Resolve a loaded integration by package name.
 * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
 * @param {string} packageName
 * @returns {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null}
 */
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'
 * @param {string} cwd
 * @returns {ExternalPackageRef | null}
 */
function resolveExternalPackage(packageName, cwd) {
  const externals = discoverExternalPackages(cwd);
  return externals.find(ext => ext.name === packageName) ?? 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
 * disambiguate by package and expose the owner's source + issuesUrl.
 * @param {string} coreDir
 * @param {string} dirName - bare component name (no `XDS` prefix)
 * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
 * @returns {ComponentOwner[]}
 */
export function resolveOwners(coreDir, dirName, loadedIntegrations) {
  const coreDocPath = findComponentReadme(coreDir, dirName);
  /** @type {ComponentOwner[]} */
  const owners = [];
  if (coreDocPath) {
    owners.push({
      package: CORE_PACKAGE,
      docPath: coreDocPath,
      sourcePath: findComponentSource(coreDir, dirName),
      issuesUrl: undefined,
      integration: null,
      hold: 'core',
    });
  }
  for (const integration of loadedIntegrations) {
    const found = findIntegrationComponent(integration, dirName);
    if (!found) continue;
    owners.push({
      package: integration.name,
      docPath: found.docPath,
      sourcePath: found.sourcePath,
      issuesUrl: integration.issuesUrl,
      integration,
      hold: found.hold,
    });
  }
  return owners;
}

/**
 * Classify a `--package`-scoped lookup. Searches the scoped package first so a
 * component that exists in both core and an external package (e.g. AppShell,
 * Button, SideNav) resolves to the package the caller asked for.
 * @param {string} packageScope
 * @param {{owners: ComponentOwner[], loadedIntegrations: import('../../foundation/integrations/integrations.mjs').LoadedIntegration[], cwd: string, name: string}} ctx
 * @returns {ScopeResolution}
 */
export function classifyScope(
  packageScope,
  {owners, loadedIntegrations, cwd, name},
) {
  // Core scope: resolve from core directly.
  if (packageScope === CORE_PACKAGE) {
    const owner = owners.find(o => o.package === CORE_PACKAGE);
    if (!owner) {
      throw new AstryxError(
        `No component "${name}" in package "${packageScope}"`,
        undefined,
        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
      );
    }
    return {kind: 'core', owner};
  }

  // Integration scope (authoritative): resolve from the loaded integration.
  const integration = findLoadedIntegration(loadedIntegrations, packageScope);
  if (integration) {
    const owner = owners.find(o => o.package === packageScope);
    if (!owner) {
      throw new AstryxError(
        `No component "${name}" in package "${packageScope}"`,
        undefined,
        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
      );
    }
    return {kind: 'integration', owner};
  }

  // Legacy fallback: node_modules `pkg.astryx.docs` external package.
  const ext = resolveExternalPackage(packageScope, cwd);
  if (!ext) {
    throw new AstryxError(
      `External package "${packageScope}" not found`,
      undefined,
      ERROR_CODES.ERR_UNKNOWN_PACKAGE,
    );
  }
  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_AMBIGUOUS_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
 * `pkg.astryx.docs` externals are intentionally NOT part of this ambiguity set.
 * @param {ComponentOwner[]} owners
 * @param {string} dirName
 * @returns {void}
 */
export function assertUnambiguousOwners(owners, dirName) {
  if (owners.length > 1) {
    throw new ComponentAmbiguityError(owners, dirName);
  }
}

/**
 * Resolve a legacy external package's doc file for `dirName`, or null when the
 * package ships no `.doc.mjs` for it.
 * @param {ExternalPackageRef} ext
 * @param {string} dirName
 * @returns {string | null}
 */
export function resolveLegacyExternalDoc(ext, dirName) {
  const extDocPath = findExternalComponentDoc(ext.docsDir, 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).
 * @param {string} coreDir
 * @param {string} dirName
 * @returns {string | null}
 */
export function resolveCoreSourcePath(coreDir, dirName) {
  return findComponentSource(coreDir, dirName);
}

/**
 * Resolve a bare (unscoped) name to a `.doc.mjs`: core first, then back-compat
 * externals, then a conservative fuzzy search. Throws ERR_UNKNOWN_COMPONENT
 * for a genuinely unknown name, and ERR_AMBIGUOUS_COMPONENT when multiple
 * packages provide the same name
 * (with candidate suggestions when close) or ERR_NO_DOC.
 * @param {string} dirName - bare component name (no `XDS` prefix)
 * @param {{coreDir: string, cwd: string, name: string}} ctx - `name` is the caller's original (prefixed) input, used in error text
 * @returns {Promise<ResolvedUnscopedDoc>}
 */
export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
  let readmePath = findComponentReadme(coreDir, dirName);
  let resolvedName = dirName;
  // Track the resolving owner so the detail payload can carry ownership info.
  // Defaults to core; the legacy-external fallback below may reassign it.
  // Annotated because CORE_PACKAGE's generated declaration carries the literal
  // type, which (unlike a fresh literal) does not widen on assignment.
  /** @type {string} */
  let resolvedOwnerPackage = CORE_PACKAGE;
  let resolvedSourcePath = readmePath
    ? findComponentSource(coreDir, dirName)
    : null;

  if (!readmePath) {
    const externals = discoverExternalPackages(cwd);
    for (const ext of externals) {
      const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
      if (extDocPath) {
        readmePath = extDocPath;
        resolvedOwnerPackage = ext.name;
        resolvedSourcePath = null;
        break;
      }
    }
  }

  if (!readmePath) {
    const components = discoverComponents(coreDir);
    const results = await searchComponents(dirName, coreDir, components);

    if (results.length > 0) {
      const topScore = results[0].score;
      const topTied = results.filter(r => r.score === topScore);
      const secondScore =
        results.length > topTied.length ? results[topTied.length].score : 0;
      const gap = topScore - secondScore;

      if (topScore >= 90 && topTied.length === 1 && gap >= 20) {
        resolvedName = topTied[0].name;
        readmePath = findComponentReadme(coreDir, resolvedName);
        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 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);
        // Past the first two suggestions, only the ones about as close as
        // the first (within NEAR_FIRST points), or a close spelling of the
        // whole typed name (a typo): a weaker match after a strong one reads
        // as noise. The list only gets shorter and keeps at least two.
        const typed = dirName.toLowerCase();
        const nearFirst = candidates.filter(
          (c, i) =>
            i < 2 ||
            c.score >= candidates[0].score - NEAR_FIRST ||
            levenshteinDistance(c.name.toLowerCase(), typed) <= 2,
        );
        throw new AstryxError(
          `No component named "${name}"`,
          nearFirst.map(c => ({name: c.name, reason: c.reason})),
          ERROR_CODES.ERR_UNKNOWN_COMPONENT,
        );
      }
    } else {
      throw new AstryxError(
        `No component named "${name}"`,
        undefined,
        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
      );
    }
  }

  if (!readmePath || !readmePath.endsWith('.doc.mjs')) {
    throw new AstryxError(
      `No .doc.mjs found for "${resolvedName}". The component needs a typed doc file.`,
      undefined,
      ERROR_CODES.ERR_NO_DOC,
    );
  }

  return {readmePath, resolvedName, resolvedOwnerPackage, resolvedSourcePath};
}

/**
 * Load a `.doc.mjs` through the shared loader, applying the API's doc-load
 * options. Centralizes the `LoadedComponentDoc`/`LoadDocsOpts` casts so leaves
 * get a typed doc without re-casting.
 * @param {string} docPath
 * @param {{zh?: boolean, dense?: boolean, lang?: string|null}} [opts]
 * @returns {Promise<LoadedComponentDoc>}
 */
export async function loadComponentDoc(docPath, opts = {}) {
  const {zh = false, dense = false, lang = null} = opts;
  try {
    return /** @type {LoadedComponentDoc} */ (
      await loadValidatedComponentDoc(
        docPath,
        /** @type {LoadDocsOpts} */ ({zh, dense, lang}),
      )
    );
  } catch (err) {
    throw new AstryxError(
      `Cannot load component metadata: ${
        err instanceof Error ? err.message : String(err)
      }`,
      undefined,
      ERROR_CODES.ERR_INVALID_DOC,
    );
  }
}

/**
 * Project a loaded doc down to its props table, flattening a multi-component
 * doc's members when the top-level doc has no direct props.
 * @param {LoadedComponentDoc} docs
 * @returns {any[]}
 */
export function extractProps(docs) {
  return (
    docs.props ||
    (docs.components ? docs.components.flatMap(c => c.props || []) : [])
  );
}

/**
 * Augment a loaded `component.detail` doc with ownership metadata. Adds
 * `package`, the resolved `import` specifier, and `sourceAvailable` (whether a
 * swizzleable source file exists for the owner). Existing doc fields (name,
 * usage, props, …) are preserved.
 * @param {LoadedComponentDoc} docs
 * @param {OwnershipSubject} owner
 * @param {string} componentName
 * @param {string} coreDir
 * @returns {import('./component.type.mjs').ComponentDetailResponse['data']}
 */
export function withOwnership(docs, owner, componentName, coreDir) {
  const importSpec =
    owner.package === CORE_PACKAGE
      ? (docs.import ?? resolveImportPath(coreDir, componentName))
      : resolveIntegrationImportPath(owner, componentName, docs.import);
  return /** @type {any} */ ({
    ...docs,
    package: owner.package,
    import: importSpec,
    sourceAvailable: owner.sourcePath != null,
  });
}

/**
 * Resolve the specifier an integration component is imported from.
 *
 * Thin adapter over the shared resolver in foundation, which `search` also
 * uses; the two surfaces have to report the same specifier for the same
 * component.
 *
 * @param {OwnershipSubject} owner
 * @param {string} componentName
 * @param {string|null} [authoredImport]
 * @returns {string}
 */
function resolveIntegrationImportPath(owner, componentName, authoredImport) {
  return resolveIntegrationImport(
    {
      exportsMap: owner.integration?.__packageExports,
      packageDir: owner.integration?.__packageDir,
      docPath: owner.docPath,
      packageName: owner.package,
    },
    componentName,
    authoredImport,
  );
}

/**
 * When the caller asked for "Code" but the resolved doc is for "CodeBlock"
 * (parent), scope the response to just the matching sub-component. Returns the
 * scoped doc (sans ownership) plus the matched member, or null when the doc is
 * not a scopeable parent.
 * @param {LoadedComponentDoc} docs
 * @param {string} dirName
 * @param {string} coreDir
 * @returns {{scoped: LoadedComponentDoc & {parentDoc?: string, import?: string}, matchingComponent: any} | null}
 */
export function scopeSubComponent(docs, dirName, coreDir) {
  const requestedXDS = `XDS${dirName}`;
  const isParentDoc =
    docs.name && docs.name.toLowerCase() !== dirName.toLowerCase();
  const matchingComponent =
    isParentDoc && docs.components
      ? docs.components.find(c => c.name === requestedXDS || c.name === dirName)
      : null;

  if (!matchingComponent) return null;

  /** @type {LoadedComponentDoc & {parentDoc?: string, import?: string}} */
  const scoped = {
    name: dirName,
    description: matchingComponent.description,
    props: matchingComponent.props,
    // Keep parent context for reference
    components: [matchingComponent],
    parentDoc: docs.name,
    import: resolveImportPath(coreDir, dirName),
  };
  if (docs.usage) scoped.usage = docs.usage;
  if (docs.theming) scoped.theming = docs.theming;

  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('{@'),
    )
  ) {
    return response;
  }
  const linked = [];
  for (const result of results) {
    if (
      result?.domain !== 'component' ||
      typeof result.description !== 'string' ||
      !result.description.includes('{@')
    ) {
      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;
  }
  // Doc tokens render in the same pass as links.
  if (!JSON.stringify(response.data ?? null).includes('{@')) {
    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}};
}