Skip to content

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

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

/**
 * @file A whole query's score against one candidate: the reserved top tier
 * for multi-word queries, then the per-token scores (see _candidate-score.mjs).
 */

import {SYNONYM_INDEX} from './_synonyms.mjs';
import {joined} from './_words.mjs';
import {phraseWords} from './_query.mjs';
import {compoundHit, compoundOf} from './_compound.mjs';
import {scoreCandidate} from './_candidate-score.mjs';
import {
  TITLE_PHRASE_SCORE,
  TITLE_IN_QUERY_SCORE,
  headingWithPhrase,
  titleInQuery,
} from './_titles.mjs';

/** @typedef {import('./_lexical.mjs').Candidate} Candidate */

/**
 * Minimum per-token score (in the multi-word pass) to count as a real match.
 * 50 = a genuine name/keyword/description hit; below that is loose Levenshtein
 * fuzz that would otherwise turn gibberish queries into noise.
 *
 * Guidance (45) is deliberately BELOW this floor, so it never counts as one of
 * the matched concepts in a multi-word query. Measured: letting it count moved
 * `nested menu` from SideNav to List and `explain why a field is required` from
 * Field to TextInput — in both cases a component whose guidance happens to
 * mention the other word displaced the one that IS the answer. Breadth is not
 * relevance, the same reason `weakKeywords` are capped. Guidance still decides
 * single-word queries and still breaks ties, which is where it earns its place.
 */
const MIN_TOKEN_SCORE = 50;

/**
 * Best score for a token against a candidate, fanning out through synonyms
 * (synonym hits are discounted so a direct hit always wins).
 * @param {string} tok
 * @param {Candidate} candidate
 * @param {{fuzzy?: boolean, part?: boolean}} [opts] - see scoreCandidate
 * @returns {{score: number, reason: string} | null}
 */
export function bestForToken(tok, candidate, opts = {}) {
  let best = scoreCandidate(tok, candidate, opts);
  const syns = SYNONYM_INDEX.get(tok);
  if (syns) {
    for (const s of syns) {
      // A synonym of a family's name names no family: its members stay put.
      const h = scoreCandidate(s, candidate, {...opts, synonym: true});
      if (h) {
        const score = Math.round(h.score * 0.85);
        if (!best || score > best.score)
          best = {score, reason: `${h.reason} (~${tok})`};
      }
    }
  }
  return best;
}

/**
 * The score of a candidate that matches every content word of a multi-word
 * query, before a bonus of up to 8 for how strong its strongest match is: just
 * above anything that matches only some of the words. The token-sum path tops
 * out near 150 for a partial match (a 100 on one word, the per-word bonus, and
 * the coverage term), so an AND-match with one keyword-strength hit (see
 * {@link STRONG_TOKEN_SCORE}) always outranks an OR-match, and stays below the
 * title tiers.
 */
export const FULL_COVERAGE_SCORE = 151;

/**
 * The strongest single-word hit an every-word match needs to take that tier: a
 * keyword substring. Two passing mentions in prose, or the components a page
 * happens to render, are breadth, not relevance; they stay on the token sum,
 * below an exact name or keyword hit on one of the words.
 */
export const STRONG_TOKEN_SCORE = 70;

/**
 * @param {string} term - Lowercased full query.
 * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
 * @param {Candidate} candidate
 * @param {string[]} [words] - The query's words for compound names (see
 *   compoundHit); empty when the query names an entry outright.
 * @param {{plain?: boolean}} [opts] - `plain`: score without matches on part
 *   of a name or a joined keyword.
 * @returns {{score: number, reason: string, matched: number, total: number, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
 *   `matched`/`total` are the query concepts this candidate answered, out of
 *   the concepts the query had. Callers that must distinguish "matched one word
 *   of three" from "matched all three" — `build`, which gates its pages group
 *   on coverage — cannot recover that from the score, because a single strong
 *   hit and a broad weak one land on the same number.
 */
export function scoreQuery(
  term,
  tokens,
  candidate,
  words = phraseWords(term),
  {plain = false} = {},
) {
  const total = Math.max(tokens.length, 1);
  // A whole-phrase hit answered the whole query by definition.
  const asFull = (/** @type {{score: number, reason: string}} */ hit) => ({
    ...hit,
    matched: total,
    total,
  });
  // Typo tolerance is for one-word lookups. In a multi-word query a near miss
  // is usually a different word, not a typo. One typed identifier is one
  // word, whatever words it spells.
  const fuzzy = tokens.length <= 1 || !/\s/.test(term);
  const full = scoreCandidate(term, candidate, {
    fuzzy,
    joins: !plain && words.length > 0,
  });
  // A query of several words keeps its phrase tiers below even when stopwords
  // leave one content word: "make an integration" is still the phrase an
  // author declares as a keyword, and "build an integration" still names a
  // title outright, though each tokenizes to `integration` alone.
  const phrase = phraseWords(term).length >= 2 || words.length >= 2;
  let compound = compoundHit(words, candidate);
  if (plain) {
    if (compound?.alias) compound = null;
  } else {
    compoundOf.set(candidate, compound);
  }

  /** 0–1 content tokens: whole-phrase fuzzy matching (typo tolerance for
   *  single words), but if stopwords left exactly one DIFFERENT token (e.g.
   *  "pricing page" → "pricing"), score that token too and take the stronger. */
  const fewTokens = () => {
    const single =
      tokens.length === 1 ? bestForToken(tokens[0], candidate, {fuzzy}) : null;
    if (full && (!single || full.score >= single.score)) return asFull(full);
    return single ? asFull(single) : null;
  };
  if (tokens.length <= 1 && !phrase) return fewTokens();

  // The full (untokenized) query matching a candidate's name or a declared
  // keyword VERBATIM — full.score 90 or 100, the only two scoreCandidate
  // outcomes at or above that mark — is a deliberate, explicit label the
  // author chose for exactly this multi-word concept. Promote it to a
  // reserved top tier, safely above the token-sum path's ceiling below
  // (~151: 100 avg + 36 bonus + 15 coverage), so it always outranks a
  // candidate that merely happens to contain several of the query's
  // individual words. Without this, "table of contents" never surfaces
  // Outline (which declares that exact phrase as a keyword) because dozens
  // of Table-related templates each match "table" and "contents" separately
  // and accumulate a higher raw score (#5239).
  if (full && full.score >= 90) {
    return asFull({
      score: full.score + 100,
      reason: full.reason,
      ...(full.alias ? {alias: full.alias, aliasWords: words.length} : {}),
    });
  }

  // The whole query standing as a phrase in a doc's title or one of its
  // headings is the next tier down, and still above the token-sum path. The
  // reader named what the section is about, in order: `dark mode` is the
  // "Light/Dark Mode" section. Without this, the title scores a keyword
  // substring (70) and loses to a doc that happens to name `mode` exactly in
  // a code tick (90 on one token, 98 with coverage), so API enum docs outrank
  // the guide section.
  const heading = headingWithPhrase(term, candidate.titles);
  if (heading != null) {
    return asFull({
      score: TITLE_PHRASE_SCORE,
      reason: `title "${heading}" holds the whole query`,
    });
  }
  if (tokens.length <= 1) return fewTokens();

  // Multi-word natural language: score each content token, counting only
  // strong hits, then reward coverage so candidates matching more terms win.
  let strongest = 0;
  let matched = 0;
  let tokenSum = 0;
  /** @type {string[]} */
  const hitTerms = [];
  // Adjacent words that join into a name or keyword answer each word they
  // join, as strongly as the joined word matches (see compoundHit).
  // Whether a counted word matched only through part of a name or a keyword
  // read joined, not through the entry's own name or a word of it.
  /** @type {'partial' | 'keyword' | false} */
  let alias = false;
  let aliasWords = 0;
  for (const tok of tokens) {
    let h = bestForToken(tok, candidate, {fuzzy, part: true});
    if (
      compound?.covered.has(joined(tok)) &&
      compound.score > (h?.score ?? 0)
    ) {
      h = compound;
      if (compound.alias && compound.score >= MIN_TOKEN_SCORE) {
        alias = alias === 'partial' ? alias : compound.alias;
        aliasWords = compound.aliasWords ?? 0;
      }
    }
    if (h && h.score >= MIN_TOKEN_SCORE) {
      if (h.score > strongest) strongest = h.score;
      matched++;
      hitTerms.push(tok);
      tokenSum += h.score;
    }
  }
  // The reverse of the title tier, a step lower: the query holds a whole title
  // of two words or more, so the reader asked a question around the section's
  // name ("how do I add dark mode"). Coverage breaks ties between sections
  // that share a title such as "Best Practices".
  const named = titleInQuery(term, candidate.titles);
  if (named != null) {
    return {
      score: TITLE_IN_QUERY_SCORE + Math.min(matched, 9),
      reason: `the query names the title "${named}"`,
      matched,
      total,
    };
  }
  if (matched === 0) return full ? asFull(full) : null;

  const reason = `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`;

  // Every word matched is its own tier. Summed per word, a doc that matches
  // both words of `troubleshoot integration` in its title and description
  // (50 + bonus + coverage = 77) lost to thirty docs that each match
  // `integration` alone, by name or in a code tick (98-108). The reader asked for
  // both; a candidate that has both comes first, ordered among its peers by
  // how strong its matches are. It needs one keyword-strength hit:
  // every word mentioned in prose, or rendered by a page, is breadth, and
  // stays on the token sum below an exact hit on one word.
  //
  // The TOTAL quality of matches orders candidates within this tier, not
  // just the strongest single hit. A doc matching both words by keyword
  // (90 + 90 = 180) outranks one matching keyword + prose (90 + 50 = 140).
  // Before this, every all-word match whose strongest hit was a keyword (90)
  // scored 157, burying the better match among dozens of ties.
  if (matched === tokens.length && strongest >= STRONG_TOKEN_SCORE) {
    return {
      score:
        FULL_COVERAGE_SCORE +
        Math.min(
          Math.floor((tokenSum - matched * MIN_TOKEN_SCORE) / (matched * 5)),
          8,
        ),
      reason,
      matched,
      total,
      ...(alias ? {alias, aliasWords} : {}),
    };
  }

  // Base the score on the STRONGEST concept that matched, plus a bonus per
  // additional matched concept and a coverage term.
  //
  // Deliberately not the mean, and deliberately not divided by total query
  // length. Dividing by total length penalizes verbose / low-fidelity prompts.
  // Dividing by the number of MATCHED tokens (what this used to do) made the
  // score non-monotonic: a second, weaker hit could drag the mean down by more
  // than the coverage bonus added it back, so matching fewer terms well beat
  // matching more terms partially. Concretely, `build "file browser"` scored
  // two form wizards matching only "file" at 98, above the actual file browser
  // matching both terms at 97 — and 98 clears the PAGE_DIRECT gate, so the
  // wrong template was returned as a confident match.
  //
  // Taking the max keeps both properties: a verbose prompt is still scored on
  // the concepts it did hit, and matching a superset of another candidate's
  // terms can never score lower, since every term of the expression is
  // non-decreasing in the set of matched tokens.
  const coverage = matched / tokens.length;
  const tokenScore = Math.round(
    strongest + Math.min(matched - 1, 3) * 12 + coverage * 15,
  );
  if (full && full.score >= tokenScore) return asFull(full);
  return {
    score: tokenScore,
    reason,
    matched,
    total,
    ...(alias ? {alias, aliasWords} : {}),
  };
}