Skip to content

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

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

/**
 * @file The main searcher: ranks every entry by a weighted sum of plain
 * signals (see _features.mjs): the lexical ranker's score and rank, BM25 over
 * each entry's name, docs text and source-built card, query-word coverage,
 * whether the query holds the entry's name, and the router's guess of the
 * domain the query wants. Its weights are static numbers in
 * _main-searcher.weights.json.
 * @input {query, options} and the gathered catalog with its static data
 * @output the search response, the lexical response's shape and count
 * @position api/search; a child of the root dispatcher in tree.mjs
 */

import {routeKit} from '../../foundation/route/route.mjs';
import {rank, signals} from './_features.mjs';
import {entryTable} from './_entries.mjs';
import {FIT_PLACES, withFitOrder, withLimit} from './_fit-order.mjs';
import {orderMatches} from './_order.mjs';
import {routeProbs} from './_query-words.mjs';
import {namesWhole, rankLexical} from './_lexical.mjs';

/** @typedef {{w: number[], mu: number[], sd: number[]}} SearcherWeights */

/**
 * A tuning override for a searcher, or null for its shipped weights.
 * @param {unknown} weights
 * @returns {SearcherWeights | null}
 */
export const asWeights = weights =>
  /** @type {SearcherWeights | null} */ (weights);

/**
 * A name read loosely: lowercase, with dashes, underscores and slashes read as
 * spaces.
 * @param {string} text
 * @returns {string}
 */
const looseName = text =>
  text
    .toLowerCase()
    .replace(/[-_/]+/g, ' ')
    .replace(/\s+/g, ' ')
    .trim();

/**
 * True when the query, read loosely, is the candidate's name, another name of
 * it, its title, or the last part of its route (`use-a-theme` typed as
 * `use a theme`). Such a query names that entry too, though the lexical
 * ranker's own gate (namesWhole) needs the name exactly.
 * @param {import('./_lexical.mjs').Candidate} candidate
 * @param {string} loose the query, read loosely
 * @returns {boolean}
 */
function namesLoosely(candidate, loose) {
  if (!loose) return false;
  const names = [
    candidate.name,
    ...(candidate.aliases ?? []),
    candidate._title,
    candidate._topic,
    candidate._resultName,
    candidate._commandName,
  ];
  return names.some(name => {
    if (!name) return false;
    const whole = looseName(String(name));
    const last = looseName(String(name).split('/').pop() ?? '');
    return whole === loose || last === loose;
  });
}

/**
 * Ranks with one searcher's weights. Shared by the main searcher and every
 * topic searcher, which differ only in their weights.
 * @param {import('./tree.mjs').SearchRequest} request
 * @param {import('./tree.mjs').SearchCatalog} catalog
 * @param {SearcherWeights} weights
 * @returns {import('./search.type.mjs').SearchResponse}
 */
export function rankWith(request, catalog, weights) {
  const {query, options} = request;
  // A query that is an entry's whole name gets the lexical answer as is: that
  // entry first, with no near siblings added beside it.
  const term = String(query).trim().toLowerCase();
  const loose = looseName(term);
  if (catalog.all.some(c => namesWhole(c, term) || namesLoosely(c, loose))) {
    return rankLexical(query, options, catalog);
  }
  const table = entryTable(catalog.all, catalog.data.cards);
  const lexical = rankLexical(
    query,
    {...options, limit: Number.MAX_SAFE_INTEGER},
    catalog,
  );
  const route = routeProbs(catalog.data.router, query);
  const rows = signals(table, query, lexical.data.results, route);
  const limit = options.limit ?? 20;
  // The fit pass reads the first FIT_PLACES results at every limit, so a
  // smaller limit shows the top of that order.
  const ordered = withFitOrder(
    orderMatches(
      table,
      rank(table, rows, weights),
      lexical,
      query,
      Math.max(limit, FIT_PLACES),
    ),
    catalog.all,
    query,
    () => catalog.data.picker,
  );
  return withLimit(ordered, limit);
}

/** @type {import('./tree.mjs').SearchKit} */
const {defineSearcher} = routeKit;

export const main = defineSearcher({
  id: 'main',
  summary:
    'Ranks every component, hook, doc, template, and theme by a weighted sum of plain word-match signals.',
  run: (request, catalog, weights) =>
    rankWith(request, catalog, asWeights(weights) ?? catalog.data.main),
});