Skip to content

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

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

/**
 * @file discover.detail.doc leaf — resolve one external component's docs.
 *
 * Two entry points, both producing the discover.detail.doc envelope:
 *   - {@link doc} resolves a `@scope/name/Component` query (package + component
 *     lookup, with ERR_UNKNOWN_PACKAGE / ERR_UNKNOWN_COMPONENT suggestions).
 *   - {@link docFromResult} wraps an already-resolved component (used by the
 *     search leaf when a free-text query narrows to exactly one component).
 *
 * @position api/discover/detail/doc — projection over ../../_adapter's resolver
 *   + doc loader; owns the discover.detail.doc envelope.
 */

import {findComponent, loadValidatedDoc} from '../../_adapter.mjs';
import {linkComponentResponse} from '../../../component/_adapter.mjs';
import {levenshteinDistance} from '../../../../foundation/text/string-utils.mjs';
import {AstryxError} from '../../../error.mjs';
import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';

/**
 * Wrap an already-resolved component in the discover.detail.doc envelope by
 * loading + validating its docs. The single place the envelope is built.
 *
 * @param {import('../../_adapter.mjs').ComponentResolution} result
 * @param {{lang?: string | null, zh?: boolean}} opts
 * @returns {Promise<import('../../discover.type.mjs').DiscoverDetailDocResponse>}
 */
export async function docFromResult(result, opts) {
  const data = await loadValidatedDoc(result, opts);
  // Its `{@link}`s read as the commands that open their docs, as
  // `astryx component` prints them (spec:AST-047 FR9).
  const linked = await linkComponentResponse(
    {type: 'component.detail', package: result.pkg.name, data},
    process.cwd(),
  );
  return {
    type: 'discover.detail.doc',
    package: result.pkg.name,
    data: linked.data,
  };
}

/**
 * Resolve a `@scope/name/Component` query to its validated docs. Throws
 * AstryxError (ERR_UNKNOWN_PACKAGE) when the scope is unknown, or
 * (ERR_UNKNOWN_COMPONENT) — with substring/fuzzy suggestions — when the
 * component is not in the package.
 *
 * @param {import('../../_package-scanner.mjs').ScannedPackage[]} packages
 * @param {string} pkgName
 * @param {string} compName
 * @param {{lang?: string | null, zh?: boolean}} opts
 * @returns {Promise<import('../../discover.type.mjs').DiscoverDetailDocResponse>}
 */
export async function doc(packages, pkgName, compName, {lang, zh}) {
  const pkg = packages.find(p => p.name === pkgName);
  if (!pkg)
    throw new AstryxError(
      `Package "${pkgName}" not found`,
      undefined,
      ERROR_CODES.ERR_UNKNOWN_PACKAGE,
    );

  const result = findComponent([pkg], compName);
  if (!result) {
    const lower = compName.toLowerCase();
    const hits = pkg.components.filter(c => c.toLowerCase().includes(lower));
    const suggestions =
      hits.length > 0
        ? hits
        : pkg.components
            .map(c => ({
              name: c,
              distance: levenshteinDistance(lower, c.toLowerCase()),
            }))
            .filter(m => m.distance <= 3)
            .sort((a, b) => a.distance - b.distance)
            .slice(0, 5)
            .map(m => m.name);
    throw new AstryxError(
      `Component "${compName}" not found in ${pkgName}`,
      suggestions.map(s => ({name: s, reason: 'similar name'})),
      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
    );
  }

  return docFromResult(result, {lang, zh});
}