Skip to content

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

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

/**
 * @file discover.search leaf — free-text search across installed packages and,
 * when the project has discover sources, everything it could add.
 *
 * A free-text query always answers with a list, so its response type depends
 * on the form of the query and never on what the project has:
 *   1. any matches, a near-miss name included -> discover.search (a one- to
 *      three-edit miss counts when both words are long enough: 5, 8 and 11
 *      letters)
 *   2. other fuzzy hits (distance <= 3)        -> throw ERR_NOT_FOUND with
 *      suggestions
 *   3. otherwise                               -> throw ERR_NOT_FOUND
 * Matches are installed components, the project's other installed items,
 * packages, and every item a source lists for a package the project could add.
 * A caller opens one item by its package path, which ../detail answers.
 *
 * @position api/discover/search — pure ranking over the installed component
 *   names and ../_catalog-view's search items.
 */

import {levenshteinDistance} from '../../../foundation/text/string-utils.mjs';
import {AstryxError} from '../../error.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {DISCOVER_KINDS} from '../../../authoring/discover/parse.mjs';

/**
 * @typedef {import('../_package-scanner.mjs').ScannedPackage} ScannedPackage
 * @typedef {import('../_catalog-view.mjs').SearchItem} SearchItem
 */

const KIND_ORDER = ['package', ...DISCOVER_KINDS];

/**
 * How well an item matches: 0 exact name, 1 name prefix, 2 name substring,
 * 3 a near-miss name (3.0, 3.1, 3.2 for one, two or three edits), 4 title,
 * summary, keyword, or description; null for no match.
 * @param {SearchItem} item
 * @param {string} lower
 * @returns {number | null}
 */
function rank(item, lower) {
  const name = item.name.toLowerCase();
  if (name === lower) return 0;
  if (name.startsWith(lower)) return 1;
  if (name.includes(lower)) return 2;
  // A near-miss name ranks above a match in the title or text: how closely
  // the name matches decides first (AST-051 FR4).
  // Typo tolerance: same minimum-length guards as search (api/search/search.mjs).
  // A one-edit miss is a typo only on words long enough that one edit rarely
  // makes a different real word.
  const dist = levenshteinDistance(lower, name);
  if (dist >= 1 && dist <= 3) {
    /** @type {Record<number, number>} */
    const MIN_LENGTHS = {1: 5, 2: 8, 3: 11};
    if (Math.min(lower.length, name.length) >= MIN_LENGTHS[dist]) {
      return 3 + (dist - 1) / 10;
    }
  }
  const text = [
    item.title,
    item.summary,
    item.description,
    ...(item.keywords ?? []),
  ]
    .filter(Boolean)
    .join('\n')
    .toLowerCase();
  if (text.includes(lower)) return 4;
  return null;
}

/**
 * Search all packages for `query` (a free-text term that never starts with
 * `@`). Resolves to a search response when anything matches, even a single
 * item, an exact component name or a near-miss name long enough to be a
 * typo, or throws AstryxError (ERR_NOT_FOUND) — with fuzzy suggestions when
 * any exist.
 *
 * @param {ScannedPackage[]} packages installed packages
 * @param {string} query
 * @param {{
 *   items?: SearchItem[],
 *   type?: import('../../../authoring/discover/type').DiscoverKind,
 *   only?: 'installed' | 'available',
 *   limit?: number,
 * }} opts
 * @returns {Promise<import('../discover.type.mjs').DiscoverSearchResponse>}
 */
export async function search(packages, query, opts) {
  const {items = [], type, only, limit} = opts;
  // An empty query must error, not match every component via `.includes('')`
  // (parity with the api/search leaf). The discover() dispatcher already routes
  // an empty query to list, but the leaf must be safe on its own.
  if (!query || !String(query).trim()) {
    throw new AstryxError(
      'A search query is required',
      [{name: 'astryx discover button', reason: 'example'}],
      ERROR_CODES.ERR_INVALID_ARGUMENT,
    );
  }
  const lower = query.toLowerCase();

  /** @type {SearchItem[]} */
  const installedComponents = packages.flatMap(pkg =>
    pkg.components.map(name => ({
      package: pkg.name,
      kind: /** @type {const} */ ('component'),
      name,
      installed: true,
    })),
  );

  const ranked = [...installedComponents, ...items]
    .filter(item => (type == null ? true : item.kind === type))
    .filter(item =>
      only === 'installed'
        ? item.installed
        : only === 'available'
          ? !item.installed
          : true,
    )
    .map(item => ({item, score: rank(item, lower)}))
    .filter(
      /** @returns {m is {item: SearchItem, score: number}} */
      m => m.score != null,
    )
    .sort(
      (a, b) =>
        a.score - b.score ||
        Number(b.item.installed) - Number(a.item.installed) ||
        KIND_ORDER.indexOf(a.item.kind) - KIND_ORDER.indexOf(b.item.kind) ||
        a.item.package.localeCompare(b.item.package) ||
        a.item.name.localeCompare(b.item.name),
    );

  if (ranked.length > 0) {
    const matches = ranked.map(({item}) => ({
      package: item.package,
      component: item.name,
      kind: item.kind,
      installed: item.installed,
      ...(item.title ? {title: item.title} : {}),
      ...(item.summary ? {summary: item.summary} : {}),
    }));
    const shown = limit == null ? matches : matches.slice(0, limit);
    return {
      type: 'discover.search',
      data: {
        query,
        matches: shown,
        ...(shown.length < matches.length ? {total: matches.length} : {}),
      },
    };
  }

  // Fuzzy fallback over installed components.
  const fuzzyMatches = installedComponents
    .map(entry => ({
      ...entry,
      distance: levenshteinDistance(lower, entry.name.toLowerCase()),
    }))
    .filter(m => m.distance <= 3)
    .sort((a, b) => a.distance - b.distance)
    .slice(0, 5);

  if (fuzzyMatches.length > 0) {
    throw new AstryxError(
      `"${query}" not found`,
      fuzzyMatches.map(m => ({
        name: m.package + '/' + m.name,
        reason: 'similar name',
      })),
      ERROR_CODES.ERR_NOT_FOUND,
    );
  }

  throw new AstryxError(
    `"${query}" not found in any package`,
    undefined,
    ERROR_CODES.ERR_NOT_FOUND,
  );
}