@astryxdesign/cli 0.7.2 → 0.7.3-canary.02f5fe4

package/api/search/_main-searcher.mjs

@@ -0,0 +1,115 @@
+// 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 size
+ * @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 {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);
+  return orderMatches(
+    table,
+    rank(table, rows, weights),
+    lexical,
+    query,
+    options.limit ?? 20,
+  );
+}
+
+/** @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),
+});

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

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the main searcher (_main-searcher.mjs) through search():
+ * it ranks by plain signals, answers the same every time, never grows the
+ * response past the lexical ranker's, and touches no network. Run against the
+ * real @astryxdesign/core.
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import * as path from 'node:path';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import {fileURLToPath} from 'node:url';
+import {search, searchCore} from './search.mjs';
+
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+const QUERIES = [
+  'date chooser',
+  'show a confirmation before deleting',
+  'toast notice for a saved draft',
+  'grid of rows you can sort by column',
+  'how do I install a theme',
+  'page of settings with a side menu',
+  'Bookmarkz',
+  'qzxv',
+];
+/** @param {unknown} r */
+const top = r =>
+  /** @type {any} */ (r).data.results.map(x => `${x.domain}:${x.name}`);
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('main searcher', () => {
+  it('finds a component from what it does', async () => {
+    expect(
+      top(await search('show a confirmation before deleting', {cwd: REPO}))[0],
+    ).toBe('component:AlertDialog');
+    expect(top(await search('date chooser', {cwd: REPO}))[0]).toBe(
+      'component:DateInput',
+    );
+  });
+
+  it('answers a whole-name query exactly as the lexical ranker does', async () => {
+    for (const q of ['Button', 'Dialog', 'useTheme', 'tokens']) {
+      expect(top(await search(q, {cwd: REPO}))).toEqual(
+        top(await searchCore(q, {cwd: REPO})),
+      );
+    }
+  });
+
+  it('answers a name typed with spaces for its dashes as the lexical ranker does', async () => {
+    for (const q of ['author a theme', 'tokens data']) {
+      expect(top(await search(q, {cwd: REPO}))).toEqual(
+        top(await searchCore(q, {cwd: REPO})),
+      );
+    }
+  });
+
+  it('answers the same every time', async () => {
+    for (const q of QUERIES.slice(0, 3)) {
+      expect(top(await search(q, {cwd: REPO}))).toEqual(
+        top(await search(q, {cwd: REPO})),
+      );
+    }
+  });
+
+  it(
+    'never returns more results or more bytes than the lexical ranker',
+    {timeout: 120_000},
+    async () => {
+      let mine = 0;
+      let core = 0;
+      for (const q of QUERIES) {
+        const [a, b] = [
+          await search(q, {cwd: REPO}),
+          await searchCore(q, {cwd: REPO}),
+        ];
+        expect(a.data.results.length).toBeLessThanOrEqual(
+          b.data.results.length,
+        );
+        mine += JSON.stringify(a).length;
+        core += JSON.stringify(b).length;
+      }
+      expect(mine).toBeLessThanOrEqual(core);
+    },
+  );
+
+  it('touches no network', async () => {
+    const fail = () => {
+      throw new Error('search reached the network');
+    };
+    vi.spyOn(http, 'request').mockImplementation(fail);
+    vi.spyOn(https, 'request').mockImplementation(fail);
+    vi.spyOn(net, 'connect').mockImplementation(fail);
+    vi.spyOn(net.Socket.prototype, 'connect').mockImplementation(fail);
+    vi.spyOn(globalThis, 'fetch').mockImplementation(fail);
+    expect(
+      top(await search('toast notice for a saved draft', {cwd: REPO}))[0],
+    ).toBe('component:Toast');
+  });
+});

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

@@ -0,0 +1 @@
+{"w":[0.1414,-0.004648,0.300865,0.056056,0.392736,0.10546,-0.147371,-0.284355,0.209928,0.04428,0.047343,0.064332,0.189238,-0.023495,-0.108461,0.121128,0.0,0.004331,0.0008,0.088292,0.072215,0.1392,0.24194,0.008913,-0.000386,0.006744,-0.003374,-0.001714,-0.001373,0.046662,0.011763,0.051916,0.155163,0.00274,-0.018366,-0.017329,0.166314,0.186888,0.021662,0.066943,0.046315,0.0,0.0,0.0,0.222553,0.09503,0.121672,0.164462,-0.00524,0.050195,0.059338,0.325721,0.112113,0.05238,0.010799,0.002423,0.003703,0.000179,0.00274],"mu":[0.130015,0.004813,0.187932,0.01647,0.147234,0.050213,0.178723,0.617872,0.005957,0.150607,0.600003,0.113058,0.050851,0.000815,0.06067,0.179093,0.074597,0.001104,1.1e-05,0.016463,0.00663,0.038722,0.068087,0.000114,0.001394,0.000461,0.001084,0.001865,8e-06,0.021395,0.005404,0.028145,0.095511,0.000152,0.125196,0.036065,0.147049,0.290649,0.001044,0.087703,0.025355,0.0,0.0,0.0,0.014431,0.003255,0.013062,0.020055,4.8e-05,0.078997,0.004913,0.028451,0.066588,0.000143,0.000763,3e-05,0.000194,0.000102,1.5e-05],"sd":[0.268781,0.036771,0.372756,0.127248,0.35434,0.218385,0.383122,0.485909,0.076955,0.803588,1.602279,0.680163,0.11702,0.02842,0.22979,0.22327,1e-06,0.033186,0.003276,0.107253,0.069348,0.158982,0.208221,0.008485,0.025221,0.012654,0.015171,0.018277,0.002347,0.32287,0.162291,0.335994,0.644886,0.039907,0.762585,0.446869,0.840132,1.16098,0.094205,0.600728,0.32812,1e-06,1e-06,1e-06,0.071304,0.032858,0.067147,0.071859,0.003777,0.214543,0.045987,0.102079,0.082198,0.00474,0.027608,0.005436,0.013914,0.010108,0.003818]}

package/api/search/_module-doc.d.mts

@@ -0,0 +1,32 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @typedef {import('./_gather-components.mjs').Candidate} Candidate */
+/**
+ * A component or hook doc, compiled, or null when it cannot be read.
+ * @param {string} docPath
+ * @param {string} [exportName]
+ * @param {'components' | 'hooks'} [root]
+ * @returns {Promise<any>}
+ */
+export function loadModuleDoc(docPath: string, exportName?: string, root?: "components" | "hooks"): Promise<any>;
+/**
+ * Build component candidates from core's own tree: name + keywords +
+ * usage/description from the component's .doc.mjs.
+ * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
+ */
+/**
+ * Usage guidance from a component doc: its feature list and its best-practice
+ * advice, flattened to plain strings.
+ *
+ * This is where a reader's vocabulary usually lives. `Banner` calls itself "a
+ * persistent message" and only its guidance names "form errors, system
+ * updates, maintenance notices" — so a search for the words people actually
+ * type finds nothing without it.
+ *
+ * @param {any} doc
+ * @returns {string[]}
+ */
+export function guidanceFrom(doc: any): string[];
+export type Candidate = import("./_gather-components.mjs").Candidate;

package/api/search/_module-doc.mjs

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Reading a component or hook doc for search: the compiled doc and its
+ * usage guidance. Imported only by the adapter's gatherers.
+ */
+
+import {readDocView} from '../../foundation/doc-compiler/read.mjs';
+
+/** @typedef {import('./_gather-components.mjs').Candidate} Candidate */
+
+/**
+ * A component or hook doc, compiled, or null when it cannot be read.
+ * @param {string} docPath
+ * @param {string} [exportName]
+ * @param {'components' | 'hooks'} [root]
+ * @returns {Promise<any>}
+ */
+export async function loadModuleDoc(
+  docPath,
+  exportName = 'docs',
+  root = 'components',
+) {
+  try {
+    // Support both the stamped default export and the legacy named export.
+    return (
+      (await readDocView(docPath, {
+        root,
+        loader: 'native',
+        exports: ['default', exportName],
+      })) ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build component candidates from core's own tree: name + keywords +
+ * usage/description from the component's .doc.mjs.
+ * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
+ */
+
+/**
+ * Usage guidance from a component doc: its feature list and its best-practice
+ * advice, flattened to plain strings.
+ *
+ * This is where a reader's vocabulary usually lives. `Banner` calls itself "a
+ * persistent message" and only its guidance names "form errors, system
+ * updates, maintenance notices" — so a search for the words people actually
+ * type finds nothing without it.
+ *
+ * @param {any} doc
+ * @returns {string[]}
+ */
+export function guidanceFrom(doc) {
+  if (!doc) return [];
+  const features = Array.isArray(doc.features) ? doc.features : [];
+  const practices = Array.isArray(doc.usage?.bestPractices)
+    ? doc.usage.bestPractices
+    : [];
+  return [...features, ...practices]
+    .map(entry =>
+      typeof entry === 'string'
+        ? entry
+        : [
+            entry?.title,
+            entry?.text,
+            entry?.description,
+            entry?.do,
+            entry?.dont,
+          ]
+            .filter(Boolean)
+            .join(' '),
+    )
+    .filter(Boolean);
+}

package/api/search/_order.d.mts

@@ -0,0 +1,32 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The search response: the lexical matches, each band in the learned order.
+ * Nothing is added or dropped, so the count and the scores stay the lexical
+ * ranker's; only the order inside a band, and so which matches fill the
+ * limit, changes.
+ * @param {EntryTable} table
+ * @param {number[]} order entry positions, best first, by the searcher's weights
+ * @param {import('./search.type.mjs').SearchResponse} lexical every lexical match
+ * @param {string} query
+ * @param {number} limit
+ * @returns {import('./search.type.mjs').SearchResponse}
+ */
+export function orderMatches(table: EntryTable, order: number[], lexical: import("./search.type.mjs").SearchResponse, query: string, limit: number): import("./search.type.mjs").SearchResponse;
+/**
+ * An integration's matches that the lexical ranker scored the same keep its
+ * order among themselves: they have no cards, so the learned order would only
+ * guess between them.
+ * @param {Item[]} items
+ * @returns {Item[]}
+ */
+export function integrationTies(items: Item[]): Item[];
+export function bandOf(score: number): number;
+export type Item = {
+    res: any;
+    i: number;
+    band: number;
+    learned: number;
+};
+export type EntryTable = import("./_entries.mjs").EntryTable;

package/api/search/_order.mjs

@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file How a searcher orders the lexical ranker's matches. Search answers
+ * only with what the lexical ranker matched, each with its own score and
+ * reason. A match never moves past one of another score band (BANDS below)
+ * or another kind, doc or not; between runs the lexical order holds. A band
+ * can be wide: 55–99 holds keyword matches beside one-word description hits,
+ * and a synonym name match can score under 55, so inside a band a weaker match
+ * can lead a stronger one when the weights favor it. Inside such a
+ * run the learned order places the matches, with these exceptions: matches
+ * that scored the same keep their lexical order, as one block; an entry the
+ * query names leads; in a query of one or two words, the matches on every
+ * word keep their lexical order; and an integration's matches that scored the
+ * same keep theirs.
+ */
+
+import {entryOf} from './_entries.mjs';
+import {words} from './_query-words.mjs';
+import {searchedComponentsOf} from './_result.mjs';
+
+/** @typedef {import('./_entries.mjs').EntryTable} EntryTable */
+
+/**
+ * Where each lexical band starts, highest first: the whole query as a name,
+ * as a keyword, as a phrase in a title, a title in the query, every word
+ * matched, a strong partial match, a name or keyword match, and below that,
+ * prose alone.
+ */
+const BANDS = [195, 188, 170, 160, 151, 100, 55];
+/** The lowest score of the every-word top tier. */
+const FULL_COVERAGE = 151;
+
+/** @param {number} score */
+export const bandOf = score => {
+  const i = BANDS.findIndex(floor => score >= floor);
+  return i === -1 ? BANDS.length : i;
+};
+
+/**
+ * The search response: the lexical matches, each band in the learned order.
+ * Nothing is added or dropped, so the count and the scores stay the lexical
+ * ranker's; only the order inside a band, and so which matches fill the
+ * limit, changes.
+ * @param {EntryTable} table
+ * @param {number[]} order entry positions, best first, by the searcher's weights
+ * @param {import('./search.type.mjs').SearchResponse} lexical every lexical match
+ * @param {string} query
+ * @param {number} limit
+ * @returns {import('./search.type.mjs').SearchResponse}
+ */
+export function orderMatches(table, order, lexical, query, limit) {
+  const all = lexical.data.results;
+  /** @type {Map<number, number>} */
+  const place = new Map(order.map((k, i) => [k, i]));
+  // Runs of consecutive lexical matches in one band and of one kind (doc or
+  // not) are the only places the learned order acts: a match never crosses
+  // into another band, or past a doc or a non-doc the lexical ranker placed.
+  let run = -1;
+  /** @type {string} */
+  let last = '';
+  const items = all.map((res, i) => {
+    // Each match's own band: the lexical merge can place a weaker match
+    // ahead of a stronger doc, and the two must never share a run.
+    const key = `${bandOf(res.score ?? 0)}:${res.domain === 'doc'}`;
+    if (key !== last) {
+      run++;
+      last = key;
+    }
+    const k = entryOf(table, res);
+    return {
+      res,
+      i,
+      band: run,
+      learned: k === undefined ? Infinity : (place.get(k) ?? Infinity),
+    };
+  });
+  const named = (/** @type {Item} */ it) =>
+    (it.res.score ?? 0) >= 95 &&
+    /^(exact name|plural of the name|name )/.test(it.res.reason ?? '');
+  // Matches the lexical ranker scored the same move as one block, in its
+  // order; the learned position of the block's first match places the block
+  // in its run (not its best member's, which would let one strong member lift
+  // a whole block of weak ones), and an entry the query names leads its run.
+  // Moving each match on its own breaks search's existing rules for tied
+  // matches (`file required` leads with Field, `ci` with the integration
+  // check) and grows answers, so ties move together; where the block lands is
+  // measured as spec:AST-083 FR6 requires.
+  /** @type {Map<string, number>} */
+  const block = new Map();
+  const blockOf = (/** @type {Item} */ it) => `${it.band}:${it.res.score}`;
+  for (const it of items) {
+    const at = named(it) ? -1 : it.learned;
+    const k = blockOf(it);
+    if (!block.has(k) || at === -1) block.set(k, at);
+  }
+  let ranked = [...items].sort(
+    (x, y) =>
+      x.band - y.band ||
+      (block.get(blockOf(x)) ?? 0) - (block.get(blockOf(y)) ?? 0) ||
+      x.i - y.i,
+  );
+  if (words(query).length <= 2) {
+    ranked = keepLexical(ranked, it => (it.res.score ?? 0) >= FULL_COVERAGE);
+  }
+  ranked = integrationTies(ranked);
+  const response = {
+    ...lexical,
+    data: {...lexical.data, results: ranked.slice(0, limit).map(it => it.res)},
+  };
+  const searched = searchedComponentsOf.get(lexical);
+  if (searched) searchedComponentsOf.set(response, searched);
+  return /** @type {import('./search.type.mjs').SearchResponse} */ (response);
+}
+
+/**
+ * @typedef {{res: any, i: number, band: number, learned: number}} Item
+ */
+
+/**
+ * The matches `pick` selects keep the places they hold, filled in lexical
+ * order.
+ * @param {Item[]} items
+ * @param {(item: Item) => boolean} pick
+ * @returns {Item[]}
+ */
+function keepLexical(items, pick) {
+  /** @type {number[]} */
+  const at = [];
+  items.forEach((it, j) => pick(it) && at.push(j));
+  if (at.length < 2) return items;
+  const sorted = at.map(j => items[j]).sort((a, b) => a.i - b.i);
+  const out = [...items];
+  at.forEach((j, n) => (out[j] = sorted[n]));
+  return out;
+}
+
+/**
+ * An integration's matches that the lexical ranker scored the same keep its
+ * order among themselves: they have no cards, so the learned order would only
+ * guess between them.
+ * @param {Item[]} items
+ * @returns {Item[]}
+ */
+export function integrationTies(items) {
+  /** @type {Map<number, number[]>} */
+  const groups = new Map();
+  items.forEach((it, j) => {
+    const pkg = it.res.package ?? '';
+    if (!pkg || pkg.startsWith('@astryxdesign/')) return;
+    const key = it.res.score ?? 0;
+    if (!groups.has(key)) groups.set(key, []);
+    /** @type {number[]} */ (groups.get(key)).push(j);
+  });
+  const out = [...items];
+  for (const at of groups.values()) {
+    if (at.length < 2) continue;
+    const sorted = at.map(j => items[j]).sort((a, b) => a.i - b.i);
+    at.forEach((j, n) => (out[j] = sorted[n]));
+  }
+  return out;
+}

package/api/search/_order.test.mjs

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Invariants of search's ordering, checked against the lexical ranker on
+ * the real catalog: search answers only with lexical matches, keeps each one's
+ * score and reason, and never moves a match past one of another band or kind.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {search, searchCore} from './search.mjs';
+import {bandOf} from './_order.mjs';
+
+const cwd = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+
+/** @param {any} r */
+const keyOf = r => `${r.domain}:${r.name}:${r.command}`;
+/** @param {any} r */
+const runOf = r => `${bandOf(r.score ?? 0)}:${r.domain === 'doc'}`;
+
+const QUERIES = [
+  'account settings',
+  'table of contents',
+  'content',
+  'dark mode',
+  'illustration',
+  'date picker in a card',
+  'how do I add a theme',
+  'button',
+  'side panel that resizes',
+];
+
+describe('search ordering invariants', () => {
+  for (const q of QUERIES) {
+    it(`keeps the lexical matches, bands and kinds for "${q}"`, async () => {
+      const ours = await search(q, {cwd, limit: 50});
+      const lexical = await searchCore(q, {
+        cwd,
+        limit: Number.MAX_SAFE_INTEGER,
+      });
+      expect(ours.data.matchCount).toBe(lexical.data.matchCount);
+      expect(ours.data.results.length).toBeLessThanOrEqual(
+        Math.min(50, lexical.data.matchCount),
+      );
+      /** @type {Map<string, number>} */
+      const at = new Map(lexical.data.results.map((r, i) => [keyOf(r), i]));
+      const byKey = new Map(lexical.data.results.map(r => [keyOf(r), r]));
+      for (const r of ours.data.results) {
+        const own = byKey.get(keyOf(r));
+        expect(own, `${keyOf(r)} is a lexical match`).toBeDefined();
+        expect(r.score).toBe(own?.score);
+        expect(r.reason).toBe(own?.reason);
+      }
+      // Two results of different runs (band or kind) keep the lexical order.
+      const rs = ours.data.results;
+      for (let i = 0; i < rs.length; i++) {
+        for (let j = i + 1; j < rs.length; j++) {
+          if (runOf(rs[i]) === runOf(rs[j])) continue;
+          expect(
+            /** @type {number} */ (at.get(keyOf(rs[i]))) <
+              /** @type {number} */ (at.get(keyOf(rs[j]))),
+            `${keyOf(rs[i])} above ${keyOf(rs[j])}`,
+          ).toBe(true);
+        }
+      }
+    }, 60_000);
+  }
+});

package/api/search/_priority.d.mts

@@ -0,0 +1,50 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+/**
+ * A match's domain priority: 0 (none), 1, or 2 (a doc the whole query names).
+ * A component, hook, template, or theme with priority ranks ahead of any doc
+ * without it, whatever the two scores are. Docs among themselves rank by
+ * priority, then score; everything else ranks among itself by score.
+ *
+ * A component, hook, template, or theme has priority (1) when one of the
+ * query's words, or the whole query, hits its name or an authored keyword at
+ * {@link STRONG_TOKEN_SCORE} or above, or when it matches every word.
+ *
+ * A doc has priority when the reader asked for that doc:
+ * - 2: the whole query is the topic's name, its last route segment, or its
+ *   own title, as words and whatever the plural (`font setup` is
+ *   typography/font-setup, `side panel` is "Side panels");
+ * - 1: a word of the query is the topic's name (`illustration` in a longer
+ *   question is the illustrations guide);
+ * - 1: a query of two or more words is one of the topic's own declared
+ *   keywords, whatever the plural (`code review` on a guide that declares it);
+ * - 1: the query holds one of the doc's titles whole (`resizable side panels`
+ *   names "Side panels"; `light dark mode button` names "Light/Dark Mode");
+ * - 1: the doc matches every word of the query and one of them is a word of
+ *   its title (`switch to a dark theme` and "Use a theme").
+ * A section answers to its topic's name.
+ *
+ * A doc that matched only by a heading holding the query, by one word, or by
+ * words spread through its text has no priority. Docs are split into many
+ * small topics, each with its own headings, so a common phrase such as
+ * `font size` hits a heading exactly (170) while the component the reader is
+ * after matches one word by keyword (`Text`, 98). Ranked on text alone, every
+ * split adds another doc above the component. Broad reference pages match every word of many queries
+ * in their text the same way. The score stays the text-match strength the
+ * result reports, so callers that gate on it (`build`) see the same numbers.
+ *
+ * @param {string} term - Lowercased search term.
+ * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
+ * @param {Candidate} candidate
+ * @param {{score: number, matched: number, total: number}} hit - The
+ *   candidate's scoreQuery result.
+ * @returns {0 | 1 | 2}
+ */
+export function domainPriority(term: string, tokens: string[], candidate: Candidate, hit: {
+    score: number;
+    matched: number;
+    total: number;
+}, queryWords?: string[]): 0 | 1 | 2;
+export type Candidate = import("./_lexical.mjs").Candidate;