@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/api/search/_score.mjs

@@ -0,0 +1,283 @@
+// 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}} [opts]
+ * @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) {
+      const h = scoreCandidate(s, candidate, opts);
+      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});
+    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} : {}),
+  };
+}

package/api/search/_synonyms.d.mts

@@ -0,0 +1,21 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export namespace SYNONYMS {
+    let dashboard: string[];
+    let login: string[];
+    let signup: string[];
+    let payment: string[];
+    let pricing: string[];
+    let chat: string[];
+    let settings: string[];
+    let calendar: string[];
+    let table: string[];
+    let gallery: string[];
+    let hero: string[];
+    let form: string[];
+    let profile: string[];
+    let documentation: string[];
+    let navigation: string[];
+}
+export const SYNONYM_INDEX: Map<string, Set<string>>;

package/api/search/_synonyms.mjs

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Search's synonym map: product words an agent types, mapped to the
+ * catalog's vocabulary in both directions.
+ */
+
+/**
+ * Synonym / intent map: product-language terms an agent is likely to type,
+ * expanded to the catalog's vocabulary so oblique queries still rank. Keys and
+ * values are matched bidirectionally (typing any value also pulls in the key
+ * and its siblings). Lowercase, single words or short phrases. Exported for
+ * `build`, whose page ranker expands a query with the same vocabulary.
+ */
+export const SYNONYMS = {
+  dashboard: [
+    'overview',
+    'analytics',
+    'kpi',
+    'kpis',
+    'metrics',
+    'stats',
+    'reporting',
+    'insights',
+    'control',
+  ],
+  login: ['signin', 'auth', 'authentication', 'sso', 'credentials', 'account'],
+  signup: ['register', 'registration', 'onboarding'],
+  payment: ['checkout', 'billing', 'card', 'pay', 'purchase', 'order'],
+  pricing: ['plans', 'plan', 'tiers', 'tier', 'subscription', 'subscriptions'],
+  chat: ['messaging', 'message', 'messages', 'conversation', 'inbox', 'dm'],
+  settings: ['preferences', 'config', 'configuration', 'account'],
+  calendar: ['schedule', 'scheduling', 'events', 'event', 'month', 'agenda'],
+  table: ['list', 'rows', 'records', 'grid', 'spreadsheet', 'datatable'],
+  gallery: ['photos', 'photo', 'images', 'image', 'pictures'],
+  hero: ['banner', 'splash', 'headline', 'landing'],
+  form: ['fields', 'input', 'inputs', 'survey'],
+  profile: ['bio', 'avatar', 'user'],
+  documentation: ['docs', 'reference', 'guide', 'api'],
+  navigation: ['nav', 'menu', 'sidebar'],
+};
+
+// Flatten into a token -> Set(expansions) lookup (bidirectional).
+export const SYNONYM_INDEX = (() => {
+  /** @type {Map<string, Set<string>>} */
+  const idx = new Map();
+  /**
+   * @param {string} a
+   * @param {string} b
+   */
+  const add = (a, b) => {
+    let set = idx.get(a);
+    if (!set) {
+      set = new Set();
+      idx.set(a, set);
+    }
+    set.add(b);
+  };
+  for (const [key, vals] of Object.entries(SYNONYMS)) {
+    for (const v of vals) {
+      add(key, v);
+      add(v, key);
+      for (const v2 of vals) if (v2 !== v) add(v, v2);
+    }
+  }
+  return idx;
+})();

package/api/search/_template-searcher.d.mts

@@ -0,0 +1,4 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export const template: import("../../foundation/route/route.mjs").Searcher<import("./tree.mjs").SearchRequest, import("./_adapter.mjs").SearchCatalog, import("./search.type.mjs").SearchResponse>;

package/api/search/_template-searcher.mjs

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The template searcher: the main searcher's signals with its own
+ * weights, in _template-searcher.weights.json.
+ * @input {query, options} and the gathered catalog with its static data
+ * @output the search response, the lexical response's shape and size
+ * @position api/search; a topic child of the root dispatcher in tree.mjs
+ */
+
+import {routeKit} from '../../foundation/route/route.mjs';
+import {asWeights, rankWith} from './_main-searcher.mjs';
+
+/** @type {import('./tree.mjs').SearchKit} */
+const {defineSearcher} = routeKit;
+
+export const template = defineSearcher({
+  id: 'template',
+  summary:
+    'Ranks entries for queries that ask for a template, with weights of its own.',
+  run: (request, catalog, weights) =>
+    rankWith(request, catalog, asWeights(weights) ?? catalog.data.template),
+});

package/api/search/_template-searcher.test.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the template searcher (_template-searcher.mjs): with its own weights
+ * it ranks a template first for a query that asks for one. Run against the real
+ * @astryxdesign/core.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {gatherCandidates, loadSearchData} from './_adapter.mjs';
+import {template} from './_template-searcher.mjs';
+
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+
+describe('template searcher', () => {
+  it('ranks a template near the top for a template query', async () => {
+    const catalog = {
+      ...(await gatherCandidates({cwd: REPO})),
+      data: loadSearchData(),
+    };
+    const answer = /** @type {any} */ (
+      await template.run(
+        {query: 'page of settings with a side menu', options: {cwd: REPO}},
+        catalog,
+        null,
+      )
+    );
+    expect(
+      answer.data.results
+        .slice(0, 3)
+        .some((/** @type {any} */ r) => r.domain === 'template'),
+    ).toBe(true);
+    expect(answer.data.results.length).toBeLessThanOrEqual(20);
+  });
+});

package/api/search/_template-searcher.weights.json

@@ -0,0 +1 @@
+{"w":[0.26388,-0.013032,0.516431,0.121331,0.254512,-0.261785,-0.688666,0.112076,-0.376705,0.111327,0.097715,0.065046,0.095694,-0.016049,-0.236365,0.094383,0.0,-0.003606,0.003684,0.067567,0.024298,-0.030137,0.324971,-0.059765,-0.008739,0.015668,0.011897,0.016649,-0.066041,0.056844,-0.055073,0.054001,0.137491,0.0,0.002283,-0.360264,0.210105,0.137841,0.14848,0.051643,0.401352,0.0,0.0,0.0,0.17537,-0.278616,0.138193,0.041566,0.02038,0.043262,0.134831,0.272071,-0.024414,-0.000472,0.013668,0.0,0.034693,0.004465,0.0],"mu":[0.164885,0.00511,0.225783,0.017021,0.147234,0.050213,0.178723,0.617872,0.005957,0.260431,0.758487,0.118373,0.062975,0.000497,0.08043,0.415077,0.054719,0.001375,4e-06,0.016249,0.004739,0.048162,0.095679,5.7e-05,0.00111,0.000198,0.001298,0.002502,1e-06,0.022962,0.00435,0.075387,0.157731,0.0,0.132838,0.026582,0.222958,0.37547,0.00064,0.098856,0.019517,0.0,0.0,0.0,0.014202,0.002142,0.017938,0.028668,2.6e-05,0.030184,0.001323,0.02033,0.363165,7.4e-05,0.000775,0.0,0.000152,0.000448,0.0],"sd":[0.30267,0.037002,0.399695,0.129352,0.35434,0.218385,0.383122,0.485909,0.076955,1.016246,1.780214,0.698764,0.119979,0.022138,0.262291,0.251643,1e-06,0.037042,0.002117,0.107524,0.058464,0.180391,0.248041,0.00567,0.021262,0.005551,0.018508,0.023617,0.00015,0.335998,0.139746,0.538946,0.804633,1e-06,0.783314,0.348833,1.042717,1.321848,0.07162,0.646141,0.275325,1e-06,1e-06,1e-06,0.066632,0.023566,0.076235,0.079854,0.002538,0.085732,0.008484,0.056206,0.296331,0.001967,0.027817,1e-06,0.012337,0.021154,1e-06]}

package/api/search/_titles.d.mts

@@ -0,0 +1,33 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The first title or heading that holds every word of the query, in order and
+ * side by side, or null.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function headingWithPhrase(term: string, titles: string[] | undefined): string | null;
+/**
+ * The first title or heading of two words or more that the query holds whole,
+ * in order and side by side, or null. A question such as "how do I add dark
+ * mode" names the "Dark mode" section outright, around words no title has.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function titleInQuery(term: string, titles: string[] | undefined): string | null;
+/**
+ * The score of a whole-query phrase inside a doc's title or heading: a keyword
+ * substring hit (70) promoted by the same 100 as the exact tier. Below an
+ * exact name or keyword (190-200), above the token-sum path (~151 at most).
+ */
+export const TITLE_PHRASE_SCORE: 170;
+/**
+ * The score of a whole title inside a longer query, before its coverage bonus:
+ * one step below {@link TITLE_PHRASE_SCORE}. The bonus (one per query term the
+ * candidate matches, at most 9) orders the sections that share a common title,
+ * so "best practices for spacing" puts Spacing's Best Practices first.
+ */
+export const TITLE_IN_QUERY_SCORE: 160;

package/api/search/_titles.mjs

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The title tier of a multi-word query: the whole query as a phrase in
+ * a doc's title or heading, or a whole title inside the query.
+ */
+
+import {phraseWords, samePhraseWord} from './_query.mjs';
+
+/**
+ * The score of a whole-query phrase inside a doc's title or heading: a keyword
+ * substring hit (70) promoted by the same 100 as the exact tier. Below an
+ * exact name or keyword (190-200), above the token-sum path (~151 at most).
+ */
+export const TITLE_PHRASE_SCORE = 170;
+
+/**
+ * The score of a whole title inside a longer query, before its coverage bonus:
+ * one step below {@link TITLE_PHRASE_SCORE}. The bonus (one per query term the
+ * candidate matches, at most 9) orders the sections that share a common title,
+ * so "best practices for spacing" puts Spacing's Best Practices first.
+ */
+export const TITLE_IN_QUERY_SCORE = 160;
+
+/**
+ * The first title or heading that holds every word of the query, in order and
+ * side by side, or null.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function headingWithPhrase(term, titles) {
+  const query = phraseWords(term);
+  if (query.length < 2 || !titles) return null;
+  for (const title of titles) {
+    const words = phraseWords(String(title ?? ''));
+    for (let i = 0; i + query.length <= words.length; i++) {
+      if (query.every((word, j) => samePhraseWord(words[i + j], word)))
+        return title;
+    }
+  }
+  return null;
+}
+
+/**
+ * The first title or heading of two words or more that the query holds whole,
+ * in order and side by side, or null. A question such as "how do I add dark
+ * mode" names the "Dark mode" section outright, around words no title has.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function titleInQuery(term, titles) {
+  const query = phraseWords(term);
+  if (!titles) return null;
+  for (const title of titles) {
+    const words = phraseWords(String(title ?? ''));
+    if (words.length < 2 || words.length > query.length) continue;
+    for (let i = 0; i + words.length <= query.length; i++) {
+      if (words.every((word, j) => samePhraseWord(query[i + j], word)))
+        return title;
+    }
+  }
+  return null;
+}

package/api/search/_words.d.mts

@@ -0,0 +1,64 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file Word matching for search: stems and word forms, word starts,
+ * identifier spelling, joined names, and typo tolerance.
+ */
+/**
+ * Light stemmer: strips common English suffixes so "charts"/"charting" and
+ * "chart" share a root. Deliberately crude (no Porter) — good enough to bridge
+ * plural/gerund gaps without a dependency.
+ * @param {string} w
+ * @returns {string}
+ */
+export function stem(w: string): string;
+/**
+ * The forms of a word that count as the same word: itself, its stem, and its
+ * singular when it ends in a plural suffix — so "tables" is "table",
+ * "statuses" is "status", and "filtering" is "filter".
+ * @param {string} w - Lowercase word.
+ * @returns {Set<string>}
+ */
+export function wordForms(w: string): Set<string>;
+/**
+ * Whether two lowercase words are the same word, up to plural and stem form.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameWord(a: string, b: string): boolean;
+/**
+ * The lowercase words of a name or keyword: split at non-alphanumerics and at
+ * camelCase boundaries, so "TextInput" is ["text", "input"] and
+ * "Dashboard - Analytics" is ["dashboard", "analytics"].
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function wordsOf(text: string): string[];
+/**
+ * Whether a term is found inside a name or keyword: it is one of its words, or
+ * the start of one (a truncation), and covers at least half of the whole
+ * string. Four letters minimum, so a short term never matches by accident.
+ * @param {string} term - Lowercase term.
+ * @param {string} text - The name or keyword as authored.
+ * @returns {boolean}
+ */
+export function startsAWordOf(term: string, text: string): boolean;
+/**
+ * A query with its camelCase and PascalCase identifiers spelled as words, so
+ * `SidebarToggle` reads "sidebar toggle" and `useTablePaginationState` "use
+ * table pagination state". Plain words, and identifiers joined with `_` or `-`, are
+ * unchanged: a joined token that matches nothing stays unmatched.
+ * @param {string} query - The query as typed, before lowercasing.
+ * @returns {string} Lowercased.
+ */
+export function spellIdentifiers(query: string): string;
+/**
+ * A name or keyword with its separators removed, lowercased: `Side Nav`,
+ * `side-nav`, and `SideNav` all join to `sidenav`.
+ * @param {string} text
+ * @returns {string}
+ */
+export function joined(text: string): string;
+export function isTypo(a: string, b: string, dist: number): boolean;