An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): search — results that fit the whole query rank higher below the first result (#10926)
Joey3312a58cbd9c
diff --git a/.changeset/search-fit-pass.md b/.changeset/search-fit-pass.mdnew file mode 100644index 0000000000..01e6051d0c--- /dev/null+++ b/.changeset/search-fit-pass.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx search` puts the results that fit the whole query higher. The first result stays the same. At the default limit, and at any limit of 10 or more, the set of results stays the same. A smaller `--limit` shows the top of the new order, so it can show a different result. Below the first result, inside each group of equally strong matches, a result whose docs fit the query much worse than the others in its group moves after them. A result whose name spells two or more of the query's words never moves down; it can still move up. The fit uses the same word-meaning weights `astryx build` uses to pick blocks, so a new component or template is placed from its own docs. A query that is an entry's whole name keeps its answer.++@josephfarinadiff --git a/packages/cli/api/build/blocks/blocks.mjs b/packages/cli/api/build/blocks/blocks.mjsindex 33f42066af..72a6dbb6b7 100644--- a/packages/cli/api/build/blocks/blocks.mjs+++ b/packages/cli/api/build/blocks/blocks.mjs@@ -163,34 +163,10 @@ export function termsOf(text) {return out;}-/**- * The weights, decoded once per weights object.- * @type {WeakMap<BlockPickerWeights, {index: Map<string, number>, idf: Float64Array, request: Int8Array, doc: Int8Array}>}- */-const decoded = new WeakMap();--/** @param {BlockPickerWeights} weights */-function decode(weights) {- let d = decoded.get(weights);- if (!d) {- // Each byte is a signed weight stored offset by 128.- const bytes = (/** @type {string} */ s) =>- Int8Array.from(Buffer.from(s, 'base64'), b => b - 128);- d = {- index: new Map(weights.vocab.map((w, i) => [w, i])),- idf: Float64Array.from(weights.idf, x => x / 1024),- request: bytes(weights.request),- doc: bytes(weights.doc),- };- decoded.set(weights, d);- }- return d;-}-/*** A text's sparse unit vector over the vocabulary: (1 + ln count) x idf.* @param {string[]} terms- * @param {ReturnType<typeof decode>} d+ * @param {{index: Map<string, number>, idf: Float64Array}} d* @returns {Map<number, number>}*/function vectorOf(terms, d) {@@ -214,20 +190,116 @@ function vectorOf(terms, d) {}/**- * A sparse vector through a signed byte matrix.- * @param {Map<number, number>} v- * @param {Int8Array} m+ * The vocabulary index and idf, read once per weights object, and each matrix+ * row decoded when a side first uses it.+ * @type {WeakMap<BlockPickerWeights, {index: Map<string, number>, idf: Float64Array, rows: Map<string, Int8Array>}>}+ */+const vocabularies = new WeakMap();++/** @param {BlockPickerWeights} weights */+function vocabularyOf(weights) {+ let v = vocabularies.get(weights);+ if (!v) {+ v = {+ index: new Map(weights.vocab.map((w, i) => [w, i])),+ idf: Float64Array.from(weights.idf, x => x / 1024),+ rows: new Map(),+ };+ vocabularies.set(weights, v);+ }+ return v;+}++/**+ * One row of a byte matrix, decoded from the base64 text alone: four+ * characters hold three bytes, so the row's bytes sit inside the characters+ * from its first byte's group to its last byte's group.+ * @param {BlockPickerWeights} weights+ * @param {'request' | 'doc'} matrix+ * @param {number} i+ * @returns {Int8Array}+ */+function rowOf(weights, matrix, i) {+ const {rows} = vocabularyOf(weights);+ const key = `${matrix}:${i}`;+ let row = rows.get(key);+ if (!row) {+ const {dims} = weights;+ const first = Math.floor((i * dims) / 3);+ const last = Math.ceil(((i + 1) * dims) / 3);+ const bytes = Buffer.from(+ weights[matrix].slice(first * 4, last * 4),+ 'base64',+ ).subarray(i * dims - first * 3, i * dims - first * 3 + dims);+ // Each byte is a signed weight stored offset by 128.+ row = Int8Array.from(bytes, b => b - 128);+ rows.set(key, row);+ }+ return row;+}++/**+ * A text's side for `matchOf` through one matrix: its word vector, and that+ * vector times the matrix rows its words use, scaled.+ * @param {string} text+ * @param {BlockPickerWeights} weights+ * @param {'request' | 'doc'} matrix* @param {number} scale- * @param {number} dims+ * @returns {{vector: Map<number, number>, projected: Float64Array}}*/-function project(v, m, scale, dims) {- const out = new Float64Array(dims);- for (const [i, x] of v) {- const row = i * dims;- for (let k = 0; k < dims; k++) out[k] += x * m[row + k];+function sideOf(text, weights, matrix, scale) {+ const vector = vectorOf(termsOf(text), vocabularyOf(weights));+ const {dims} = weights;+ const projected = new Float64Array(dims);+ for (const [i, x] of vector) {+ const row = rowOf(weights, matrix, i);+ for (let k = 0; k < dims; k++) projected[k] += x * row[k];}- for (let k = 0; k < dims; k++) out[k] *= scale;- return out;+ for (let k = 0; k < dims; k++) projected[k] *= scale;+ return {vector, projected};+}++/**+ * A text's docs side for `matchOf`: its word vector and that vector through+ * the doc matrix. Search scores its entries' own docs with it.+ * @param {string} text+ * @param {BlockPickerWeights} weights+ * @returns {{vector: Map<number, number>, projected: Float64Array}}+ */+export function docSideOf(text, weights) {+ return sideOf(text, weights, 'doc', weights.docScale);+}++/**+ * A request's side for `matchOf`: its word vector and that vector through the+ * request matrix.+ * @param {string} request+ * @param {BlockPickerWeights} weights+ * @returns {{vector: Map<number, number>, projected: Float64Array}}+ */+export function requestSideOf(request, weights) {+ return sideOf(request, weights, 'request', weights.requestScale);+}++/**+ * The picker's match of a request to a docs text: their projections' dot+ * product plus the lexical weight times their plain overlap (the cosine of+ * their word vectors). Build's ranking also reads the overlap alone.+ * @param {{vector: Map<number, number>, projected: Float64Array}} request+ * @param {{vector: Map<number, number>, projected: Float64Array}} doc+ * @param {BlockPickerWeights} weights+ * @returns {{match: number, overlap: number}}+ */+export function matchOf(request, doc, weights) {+ let s = 0;+ for (let k = 0; k < weights.dims; k++)+ s += request.projected[k] * doc.projected[k];+ let overlap = 0;+ for (const [i, x] of request.vector) {+ const y = doc.vector.get(i);+ if (y !== undefined) overlap += x * y;+ }+ return {match: s + weights.lexical * overlap, overlap};}/**@@ -261,7 +333,6 @@ function readCatalog(catalog, components, weights) {]);const cached = catalogs.get(weights);if (cached && cached.key === key) return cached;- const d = decode(weights);const names = components.map(c => c.name).sort((a, b) => b.length - a.length);const keywords = new Map(components.map(c => [c.name, c.keywords ?? []]));/** @type {Map<string, {component: string, vector: Map<number, number>, projected: Float64Array}>} */@@ -276,12 +347,7 @@ function readCatalog(catalog, components, weights) {wordsOf(component).join(' '),(keywords.get(component) ?? []).join(' '),].join(' ');- const vector = vectorOf(termsOf(text), d);- blocks.set(b.name, {- component,- vector,- projected: project(vector, d.doc, weights.docScale, weights.dims),- });+ blocks.set(b.name, {component, ...docSideOf(text, weights)});}// A component is named by its own words, or by a keyword at most three// components share (weighted by how few share it).@@ -378,26 +444,12 @@ export function pickBlocks(request, signals, weights) {/** @type {Map<string, SearchResultEntry>} */const entries = new Map();if (own.length === 0) return {names: [], entries};- const d = decode(weights);const cat = readCatalog(signals.catalog, signals.components, weights);- const q = vectorOf(termsOf(request), d);- const eq = project(q, d.request, weights.requestScale, weights.dims);- const dot = (/** @type {Map<number, number>} */ v) => {- let s = 0;- for (const [i, x] of q) {- const y = v.get(i);- if (y !== undefined) s += x * y;- }- return s;- };+ const side = requestSideOf(request, weights);/** @type {Map<string, {match: number, overlap: number}>} */const scored = new Map();- for (const [name, b] of cat.blocks) {- let s = 0;- for (let k = 0; k < weights.dims; k++) s += eq[k] * b.projected[k];- const overlap = dot(b.vector);- scored.set(name, {match: s + weights.lexical * overlap, overlap});- }+ for (const [name, b] of cat.blocks)+ scored.set(name, matchOf(side, b, weights));const get = (/** @type {string} */ b) =>scored.get(b) ?? {match: -Infinity, overlap: 0};const ranked = [...scored.keys()].sort((a, b) => get(b).match - get(a).match);@@ -480,7 +532,7 @@ export function pickBlocks(request, signals, weights) {name,package: block.package ?? '',score: Math.max(1, Math.round(100 * Math.exp(x.score - max))),- reason: reasonFor(request, cat.blocks.get(name), d, weights),+ reason: reasonFor(request, side, cat.blocks.get(name), weights),description: block.description ?? '',displayName: block.displayName,kind: 'block',@@ -493,11 +545,11 @@ export function pickBlocks(request, signals, weights) {/*** Why a block fits: the request words that tie it to its docs most.* @param {string} request+ * @param {{vector: Map<number, number>, projected: Float64Array}} side the request's side* @param {{vector: Map<number, number>, projected: Float64Array} | undefined} block- * @param {ReturnType<typeof decode>} d* @param {BlockPickerWeights} weights*/-function reasonFor(request, block, d, weights) {+function reasonFor(request, side, block, weights) {if (!block) return 'fits by meaning';const raw =String(request)@@ -507,16 +559,14 @@ function reasonFor(request, block, d, weights) {const wordOf = new Map();for (const w of raw)if (!STOP.has(w) && !wordOf.has(stemOf(w))) wordOf.set(stemOf(w), w);- const q = vectorOf(termsOf(request), d);/** @type {[string, number][]} */const parts = [];- for (const [i, x] of q) {+ for (const [i, x] of side.vector) {const term = weights.vocab[i];if (term.includes('_')) continue;+ const row = rowOf(weights, 'request', i);let s = 0;- const row = i * weights.dims;- for (let k = 0; k < weights.dims; k++)- s += d.request[row + k] * block.projected[k];+ for (let k = 0; k < weights.dims; k++) s += row[k] * block.projected[k];s =x * s * weights.requestScale +weights.lexical * x * (block.vector.get(i) ?? 0);diff --git a/packages/cli/api/search/ORDERING.md b/packages/cli/api/search/ORDERING.mdindex 7099ed4a70..759b018589 100644--- a/packages/cli/api/search/ORDERING.md+++ b/packages/cli/api/search/ORDERING.md@@ -6,12 +6,15 @@`spec:AST-083` owns search's result order; this file describes the data that implements it. Inside one score band, a searcher's static weights decide the order. Matches with the same score move together as one block, placed by the learned position of the block's first match: moving each one on its own breaks search's existing rules for tied matches. Inside a block, the lexical ranker's order holds, except below the first result: there a block of one domain puts a part of the first result first (its name words start with the first result's; at most two parts lead across an answer), then the match whose matched words are rarer in the catalog. Matches never cross bands or kinds. There is no model runtime: every number is a plain static value read at load time.+After that order, one fit pass reads the first ten results (`_fit-order.mjs`). The first result stays. The others split into runs of one band and kind. Inside a run, each match gets a fit to the whole query from build's block-picker match (`../build/blocks/blocks.mjs` with `blocks.weights.json`) over the match's own docs: its name words, display name or title, description, and keywords. A match whose fit is under 1.7 times the run's median fit moves, in order, after the others in its run, unless its name spells two or more of the query's words. Such a match never moves down; it can still move up when others move after it. A run whose median fit is zero or less keeps its order. A query that is an entry's whole name skips the pass, as it skips the learned order. The pass always reads ten places before the limit cuts the answer. At the default limit, and at any limit of 10 or more, the set of results stays the same. A smaller limit shows the top of the new order, so it can show a different result. Build's loader (`loadBlockPicker` in `../build/_adapter.mjs`) reads and checks the block-picker weights for both commands. When the file is missing, unreadable, or not the picker's shape, the loader returns null and the pass keeps the order. The pass reads the weights only when a run holds two or more matches, and it decodes only the matrix rows that the query's words and those matches' docs use, so a search does not pay for the whole catalog.+## Files| File | What it holds || ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `tree.weights.json` | The root classifier: for each query word or word pair, one number per class (component, hook, doc, template, theme, none). The query's tokens vote, and a topic searcher takes the query only when its class wins by the floor in `tree.mjs`. || `_main-searcher.weights.json`, `_doc-searcher.weights.json`, `_template-searcher.weights.json` | One weight, mean and spread per signal for each searcher (see `SIGNALS` and `PER_DOMAIN` in `_features.mjs`). A match's place inside its band is the weighted sum of its standardized signals. |+| `../build/blocks/blocks.weights.json` | The block picker's vocabulary, idf and two projection matrices, shared with build. The fit pass reads them through build's loader; search ships no copy. || `_cards.json` | One card per Core component and hook: what it is, the words people use for it, and its main props, written from the item's own source. Cards feed one signal, word overlap with the card. |The signals are counts over the query and each entry's own text: the lexical score and rank, BM25 over the entry's name, docs text and card, how many query words the entry covers, whether the query holds the entry's name, and the classifier's guess of the domain.diff --git a/packages/cli/api/search/_adapter.mjs b/packages/cli/api/search/_adapter.mjsindex 43d2d25f1d..f5ececdea8 100644--- a/packages/cli/api/search/_adapter.mjs+++ b/packages/cli/api/search/_adapter.mjs@@ -16,6 +16,7 @@ import {} from '../../foundation/fs/read-record.mjs';import {isOutsideProject} from '../../foundation/env/project-scope.mjs';import {coreDirOrThrow} from '../error.mjs';+import {loadBlockPicker} from '../build/_adapter.mjs';import {CORELESS_DOMAINS} from './_query.mjs';import {gatherComponents} from './_gather-components.mjs';import {gatherHooks} from './_gather-hooks.mjs';@@ -167,6 +168,10 @@ export function gatherCandidatesReused(options) {* @property {SearcherWeights} main The main searcher's weights.* @property {SearcherWeights} doc The doc searcher's weights.* @property {SearcherWeights} template The template searcher's weights.+ * @property {import('../build/blocks/blocks.mjs').BlockPickerWeights | null} picker+ * Build's block-picker weights, which the fit pass (_fit-order.mjs) reads;+ * null when build's loader finds the file absent, unreadable, or the wrong+ * shape.* @typedef {Awaited<ReturnType<typeof gatherCandidates>> & {data: SearchData}} SearchCatalog*/@@ -174,8 +179,10 @@ export function gatherCandidatesReused(options) {let searchData = null;/**- * The search tree's static data, read once: the entry cards and each node's- * weights file.+ * The search tree's static data, read once: the entry cards, each node's+ * weights file, and build's block-picker weights for the fit pass. Build's+ * loader (loadBlockPicker) reads and checks the picker weights, only when the+ * pass first needs them.** These files are static, reviewed data that only order matches inside a score* band; ORDERING.md beside them says what each holds and how@@ -193,6 +200,10 @@ export function loadSearchData() {main: read('./_main-searcher.weights.json'),doc: read('./_doc-searcher.weights.json'),template: read('./_template-searcher.weights.json'),+ // Read on first use: most searches never reach the fit pass.+ get picker() {+ return loadBlockPicker();+ },};}return searchData;diff --git a/packages/cli/api/search/_fit-order.mjs b/packages/cli/api/search/_fit-order.mjsnew file mode 100644index 0000000000..8ef1f3882f--- /dev/null+++ b/packages/cli/api/search/_fit-order.mjs@@ -0,0 +1,257 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A last pass over a searcher's answer: inside each run of one score+ * band and kind, the entries from #2 to #10 that fit the whole query much+ * worse than the others in their run move, in order, after them.+ * @input the ordered response, the gathered candidates, and the query+ * @output the same response with the same results, maybe in a new order+ * @position api/search; rankWith (_main-searcher.mjs) runs it after+ * orderMatches, with the weights the adapter loads (loadSearchData) through+ * build's own loader. The fit is build's block-picker match+ * (build/blocks/blocks.mjs) with its shipped weights, so an entry the weights+ * never saw is scored from its own docs the same way. Without readable+ * weights the order stays.+ */++import {+ docSideOf,+ matchOf,+ requestSideOf,+ stemOf,+ termsOf,+ wordsOf,+} from '../build/blocks/blocks.mjs';+import {bandOf} from './_order.mjs';+import {searchedComponentsOf} from './_result.mjs';++/** An entry stays in place when its fit is at least this times the median. */+export const FIT_BAR = 1.7;++/** An entry whose name spells at least this many query words never moves. */+const NAME_WORDS = 2;++/** The first result stays; the pass orders the places after it up to here. */+export const FIT_PLACES = 10;++/** @typedef {import('../build/blocks/blocks.mjs').BlockPickerWeights} Weights */+/** @typedef {{vector: Map<number, number>, projected: Float64Array}} Side */++/**+ * Each candidate by `domain:name`; a doc also by its topic and by+ * `topic#section`. The first candidate with a key owns it.+ * @type {WeakMap<any[], Map<string, any>>}+ */+const keyed = new WeakMap();++/**+ * Each candidate's docs side, computed when a result first needs it.+ * @type {WeakMap<Weights, WeakMap<any, Side>>}+ */+const sides = new WeakMap();++/**+ * An entry's docs text: its name words, display name or first title,+ * description, and keywords.+ * @param {any} c+ */+const docText = c =>+ [+ wordsOf(c.name).join(' '),+ c._displayName ?? (Array.isArray(c.titles) ? c.titles[0] : '') ?? '',+ c.description ?? '',+ (Array.isArray(c.keywords) ? c.keywords : []).join(' '),+ ].join(' ');++/**+ * @param {any[]} candidates+ * @returns {Map<string, any>}+ */+function keysOf(candidates) {+ let byKey = keyed.get(candidates);+ if (!byKey) {+ byKey = new Map();+ for (const c of candidates) {+ const keys = [`${c.domain}:${c._resultName ?? c.name}`];+ if (c.domain === 'doc' && c._topic)+ keys.push(+ c._section ? `doc:${c._topic}#${c._section}` : `doc:${c._topic}`,+ );+ for (const k of keys) if (!byKey.has(k)) byKey.set(k, c);+ }+ keyed.set(candidates, byKey);+ }+ return byKey;+}++/**+ * @param {any} c+ * @param {Weights} weights+ * @returns {Side}+ */+function candidateSide(c, weights) {+ let byCandidate = sides.get(weights);+ if (!byCandidate) {+ byCandidate = new WeakMap();+ sides.set(weights, byCandidate);+ }+ let side = byCandidate.get(c);+ if (!side) {+ side = docSideOf(docText(c), weights);+ byCandidate.set(c, side);+ }+ return side;+}++/**+ * A result's docs side: its candidate's, else one from the result's own name,+ * display name and description.+ * @param {any} r+ * @param {any[]} candidates+ * @param {Weights} weights+ * @returns {Side}+ */+function resultSideOf(r, candidates, weights) {+ const byKey = keysOf(candidates);+ if (r.domain === 'doc' && r.section) {+ const c = byKey.get(`doc:${r.name}#${r.section}`);+ if (c) return candidateSide(c, weights);+ }+ const c = byKey.get(`${r.domain}:${r.name}`);+ return c+ ? candidateSide(c, weights)+ : docSideOf(+ `${wordsOf(r.name).join(' ')} ${r.displayName ?? ''} ${r.description ?? ''}`,+ weights,+ );+}++/**+ * A result's run: its score band and kind (doc or not), as orderMatches reads+ * them.+ * @param {any} r+ */+const runOf = r => `${bandOf(r.score ?? 0)}:${r.domain === 'doc'}`;++/**+ * The results with the first kept. Entries #2 to #10 split into runs of one+ * band and kind. Inside a run, the entries that fit the query under FIT_BAR+ * times the run's median fit move, in order, after the others, unless their+ * name spells NAME_WORDS or more of the query's words. A run whose+ * median fit is zero or less keeps its order. Nothing crosses a run, and+ * nothing is added or dropped.+ * @param {any[]} results+ * @param {any[]} candidates+ * @param {string} query+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights+ * the block picker's weights, or a function that reads them; the function+ * runs only when a run can change. Without weights the order stays+ * @returns {any[]}+ */+export function orderByFit(results, candidates, query, weights) {+ if (!weights || results.length < 3) return results;+ const end = Math.min(FIT_PLACES, results.length);+ /** @type {[number, number][]} */+ const runs = [];+ for (let i = 1; i < end;) {+ let j = i;+ while (j < end && runOf(results[j]) === runOf(results[i])) j++;+ runs.push([i, j]);+ i = j;+ }+ // Only a run of two or more can change, so the weights stay unread when+ // there is none.+ if (!runs.some(([i, j]) => j - i > 1)) return results;+ const w = typeof weights === 'function' ? weights() : weights;+ if (!w) return results;+ const request = requestSideOf(query, w);+ const queryWords = new Set(termsOf(query).filter(t => !t.includes('_')));+ /** @param {any} r */+ const named = r =>+ new Set(+ wordsOf(r.name)+ .map(stemOf)+ .filter(word => queryWords.has(word)),+ ).size >= NAME_WORDS;+ const out = results.slice();+ let changed = false;+ for (const [i, j] of runs) {+ if (j - i < 2) continue;+ const moved = demoteWeak(+ results.slice(i, j),+ request,+ candidates,+ w,+ named,+ );+ moved.forEach((r, k) => {+ if (r !== out[i + k]) changed = true;+ out[i + k] = r;+ });+ }+ return changed ? out : results;+}++/**+ * One run, with the entries under FIT_BAR times its median fit moved, in+ * order, after the others. An entry whose name spells NAME_WORDS or more of+ * the query's words stays with the others: its name is strong evidence.+ * @param {any[]} run+ * @param {Side} request+ * @param {any[]} candidates+ * @param {Weights} weights+ * @param {(r: any) => boolean} named+ * @returns {any[]}+ */+function demoteWeak(run, request, candidates, weights, named) {+ const fits = run.map(+ r => matchOf(request, resultSideOf(r, candidates, weights), weights).match,+ );+ const sorted = [...fits].sort((a, b) => a - b);+ const n = sorted.length;+ const median =+ n % 2 ? sorted[(n - 1) / 2] : (sorted[n / 2 - 1] + sorted[n / 2]) / 2;+ if (!(median > 0)) return run;+ const bar = FIT_BAR * median;+ const kept = run.map((r, k) => fits[k] >= bar || named(r));+ return [...run.filter((_, k) => kept[k]), ...run.filter((_, k) => !kept[k])];+}++/**+ * The search response with its results ordered by fit (`orderByFit`). Any+ * other response passes through.+ * @template T+ * @param {T} response+ * @param {any[]} candidates+ * @param {string} query+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights+ * @returns {T}+ */+export function withFitOrder(response, candidates, query, weights) {+ const r = /** @type {any} */ (response);+ const results = r?.data?.results;+ if (!Array.isArray(results)) return response;+ const ordered = orderByFit(results, candidates, query, weights);+ if (ordered === results) return response;+ const out = {...r, data: {...r.data, results: ordered}};+ const searched = searchedComponentsOf.get(r);+ if (searched) searchedComponentsOf.set(out, searched);+ return /** @type {T} */ (out);+}++/**+ * The search response with at most `limit` results.+ * @template T+ * @param {T} response+ * @param {number} limit+ * @returns {T}+ */+export function withLimit(response, limit) {+ const r = /** @type {any} */ (response);+ const results = r?.data?.results;+ if (!Array.isArray(results) || results.length <= limit) return response;+ const out = {...r, data: {...r.data, results: results.slice(0, limit)}};+ const searched = searchedComponentsOf.get(r);+ if (searched) searchedComponentsOf.set(out, searched);+ return /** @type {T} */ (out);+}diff --git a/packages/cli/api/search/_fit-order.test.mjs b/packages/cli/api/search/_fit-order.test.mjsnew file mode 100644index 0000000000..8b0d435f5a--- /dev/null+++ b/packages/cli/api/search/_fit-order.test.mjs@@ -0,0 +1,200 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The fit pass over search's answer, on a made-up catalog: the first+ * result stays, the set of results stays, nothing crosses a band or kind,+ * and an entry known only from its own docs moves up when it fits.+ */++import {describe, it, expect} from 'vitest';+import {requireNatively} from '../../test-utils/native-require.mjs';++const require = requireNatively(import.meta.url);+/** @type {typeof import('./_fit-order.mjs')} */+const {orderByFit, withFitOrder, withLimit} = require('./_fit-order.mjs');+/** @type {typeof import('./_adapter.mjs')} */+const {loadSearchData} = require('./_adapter.mjs');+/** @type {typeof import('./_result.mjs')} */+const {searchedComponents, searchedComponentsOf} = require('./_result.mjs');++const weights = /** @type {any} */ (loadSearchData().picker);++const QUERY = 'drop zone to upload files';++/** Made-up entries; none of them is in Astryx. */+const CATALOG = [+ {domain: 'component', name: 'Beacon', description: 'A page title row.'},+ {+ domain: 'component',+ name: 'Pebble',+ description: 'A small round marker that shows a count.',+ },+ {+ domain: 'component',+ name: 'Quill',+ description: 'A text field for a short note.',+ },+ {+ domain: 'component',+ name: 'Marrow',+ description: 'A banner that tells people about upload limits.',+ },+ {+ domain: 'component',+ name: 'Thistle',+ description: 'A list of rows with files and folders.',+ },+ {+ domain: 'component',+ name: 'LanternCrate',+ description: 'A drop zone where people drag files to upload them.',+ },+ {+ domain: 'component',+ name: 'UploadZoneHint',+ description: 'A grey line of help text.',+ },+];++/**+ * @param {string} name+ * @param {number} score+ * @param {string} [domain]+ */+const result = (name, score, domain = 'component') => ({domain, name, score});++/** @param {any[]} results */+const names = results => results.map(r => r.name);++describe('orderByFit', () => {+ it('lifts a new entry known only from its own docs when it fits', () => {+ expect(weights.known).not.toContain('LanternCrate');+ const results = [+ result('Beacon', 160),+ result('Pebble', 120),+ result('Quill', 120),+ result('Marrow', 120),+ result('Thistle', 120),+ result('LanternCrate', 120),+ ];+ const out = orderByFit(results, CATALOG, QUERY, weights);+ expect(names(out)).toEqual([+ 'Beacon',+ 'Thistle',+ 'LanternCrate',+ 'Pebble',+ 'Quill',+ 'Marrow',+ ]);+ expect(new Set(out)).toEqual(new Set(results));+ });++ it('scores an entry with no catalog item from the result itself', () => {+ const results = [+ result('Beacon', 160),+ result('Pebble', 120),+ result('Quill', 120),+ result('Marrow', 120),+ result('Thistle', 120),+ {+ ...result('Driftbox', 120),+ description: 'A drop zone where people drag files to upload them.',+ },+ ];+ const out = orderByFit(results, CATALOG, QUERY, weights);+ expect(names(out).slice(0, 3)).toEqual(['Beacon', 'Thistle', 'Driftbox']);+ });++ it('never moves an entry past one of another band or kind', () => {+ const results = [+ result('Beacon', 160),+ result('Pebble', 120),+ result('Quill', 120),+ result('Marrow', 120),+ result('Thistle', 60),+ result('LanternCrate', 60),+ result('Quill', 120, 'doc'),+ ];+ const out = orderByFit(results, CATALOG, QUERY, weights);+ expect(out.map(r => `${r.score}:${r.domain}`)).toEqual(+ results.map(r => `${r.score}:${r.domain}`),+ );+ expect(out[0]).toBe(results[0]);+ });++ it('keeps an entry whose name spells two query words', () => {+ const results = [+ result('Beacon', 160),+ result('UploadZoneHint', 120),+ result('Pebble', 120),+ result('Quill', 120),+ result('Thistle', 120),+ result('LanternCrate', 120),+ ];+ const out = orderByFit(results, CATALOG, QUERY, weights);+ expect(names(out).slice(0, 2)).toEqual(['Beacon', 'UploadZoneHint']);+ });++ it('keeps the order when the median fit is not above zero', () => {+ const results = [+ result('Beacon', 160),+ result('Pebble', 120),+ result('Quill', 120),+ result('Thistle', 120),+ ];+ expect(orderByFit(results, CATALOG, 'qzxv blorf', weights)).toBe(results);+ });++ it('keeps an answer of fewer than three results, and works without weights', () => {+ const two = [result('Beacon', 160), result('LanternCrate', 120)];+ expect(orderByFit(two, CATALOG, QUERY, weights)).toBe(two);+ const many = [+ result('Beacon', 160),+ result('Pebble', 120),+ result('LanternCrate', 120),+ ];+ expect(orderByFit(many, CATALOG, QUERY, null)).toBe(many);+ });++ it('orders only the first ten places', () => {+ const results = [+ result('Beacon', 160),+ ...Array.from({length: 9}, (_, k) => ({+ ...result(`Pebble${k}`, 120),+ description: 'A small round marker that shows a count.',+ })),+ result('LanternCrate', 120),+ ];+ const out = orderByFit(results, CATALOG, QUERY, weights);+ expect(out).toEqual(results);+ });+});++describe('withFitOrder and withLimit', () => {+ it('keep the response shape and the components it was scored against', () => {+ const response = {+ type: 'search',+ data: {+ query: QUERY,+ matchCount: 6,+ results: [+ result('Beacon', 160),+ result('Pebble', 120),+ result('Quill', 120),+ result('Marrow', 120),+ result('Thistle', 120),+ result('LanternCrate', 120),+ ],+ },+ };+ const searched = [{name: 'Beacon', keywords: []}];+ searchedComponentsOf.set(response, searched);+ const ordered = withFitOrder(response, CATALOG, QUERY, weights);+ expect(Object.keys(ordered.data)).toEqual(Object.keys(response.data));+ expect(ordered.data.matchCount).toBe(6);+ expect(searchedComponents(ordered)).toBe(searched);+ const cut = withLimit(ordered, 2);+ expect(names(cut.data.results)).toEqual(['Beacon', 'Thistle']);+ expect(searchedComponents(cut)).toBe(searched);+ });+});diff --git a/packages/cli/api/search/_fit-order.weights.test.mjs b/packages/cli/api/search/_fit-order.weights.test.mjsnew file mode 100644index 0000000000..55cd8d4614--- /dev/null+++ b/packages/cli/api/search/_fit-order.weights.test.mjs@@ -0,0 +1,118 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The fit pass without readable block-picker weights: when build's+ * loader finds the weights file missing or broken, search keeps the order it+ * has without the pass and does not throw. Each case runs in its own process,+ * because the loader reads the file once per process. A search whose pass+ * cannot move anything never reads the file.+ */++import {execFileSync} from 'node:child_process';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import {requireNatively} from '../../test-utils/native-require.mjs';++const require = requireNatively(import.meta.url);+/** @type {typeof import('./search.mjs')} */+const {search} = require('./search.mjs');+/** @type {typeof import('./_adapter.mjs')} */+const {loadSearchData} = require('./_adapter.mjs');++/** A query whose answer the fit pass changes. */+const QUERY = 'table with row selection';++const SEARCH = fileURLToPath(new URL('./search.mjs', import.meta.url));+const BUILD_ADAPTER = fileURLToPath(+ new URL('../build/_adapter.mjs', import.meta.url),+);++/** @param {any} response */+const names = response => response.data.results.map(r => r.name);++/**+ * The answer's names, and whether build's loader found weights, in a process+ * where every read of the weights file does `onRead` instead.+ * @param {string} onRead a statement that throws or returns the file's text+ * @param {string} [query]+ * @returns {{names: string[], picker: boolean, reads: number}}+ */+function searchWithWeightsFile(onRead, query = QUERY) {+ const patch = [+ "import fs from 'node:fs';",+ 'const read = fs.readFileSync;',+ 'globalThis.weightReads = 0;',+ 'fs.readFileSync = function (file, ...rest) {',+ " if (String(file).endsWith('blocks.weights.json')) {",+ ' globalThis.weightReads++;',+ ` ${onRead}`,+ ' }',+ ' return read.call(this, file, ...rest);',+ '};',+ ].join('\n');+ const script = [+ `const {search} = await import(${JSON.stringify(SEARCH)});`,+ `const {loadBlockPicker} = await import(${JSON.stringify(BUILD_ADAPTER)});`,+ `const response = await search(${JSON.stringify(query)});`,+ 'const reads = globalThis.weightReads;',+ 'process.stdout.write(JSON.stringify({',+ ' names: response.data.results.map(r => r.name),',+ ' picker: loadBlockPicker() !== null,',+ ' reads,',+ '}));',+ ].join('\n');+ const out = execFileSync(+ process.execPath,+ [+ '--import',+ `data:text/javascript,${encodeURIComponent(patch)}`,+ '--input-type=module',+ '--eval',+ script,+ ],+ {encoding: 'utf8'},+ );+ return JSON.parse(out);+}++/**+ * The answer with the fit pass given no weights, in this process.+ * @returns {Promise<string[]>}+ */+async function answerWithoutWeights() {+ const data = loadSearchData();+ const picker = Object.getOwnPropertyDescriptor(data, 'picker');+ Object.defineProperty(data, 'picker', {value: null, configurable: true});+ try {+ return names(await search(QUERY));+ } finally {+ if (picker) Object.defineProperty(data, 'picker', picker);+ }+}++describe('the fit pass without readable weights', () => {+ it('keeps the order when the weights file is missing', async () => {+ const without = await answerWithoutWeights();+ expect(names(await search(QUERY))).not.toEqual(without);+ const missing = searchWithWeightsFile(+ "throw Object.assign(new Error('missing'), {code: 'ENOENT'});",+ );+ expect(missing).toEqual({names: without, picker: false, reads: 1});+ }, 60_000);++ it('keeps the order when the weights file is not the picker’s shape', async () => {+ const without = await answerWithoutWeights();+ const broken = searchWithWeightsFile('return \'{"vocab": 3}\';');+ expect(broken).toEqual({names: without, picker: false, reads: 1});+ const unparsable = searchWithWeightsFile("return 'not json';");+ expect(unparsable).toEqual({names: without, picker: false, reads: 1});+ }, 60_000);++ it('never reads the weights when the pass cannot move anything', () => {+ const named = searchWithWeightsFile(+ 'return read.call(this, file, ...rest);',+ 'Button',+ );+ expect(named.reads).toBe(0);+ }, 60_000);+});diff --git a/packages/cli/api/search/_main-searcher.mjs b/packages/cli/api/search/_main-searcher.mjsindex af6fa7b2d6..b7ea8af248 100644--- a/packages/cli/api/search/_main-searcher.mjs+++ b/packages/cli/api/search/_main-searcher.mjs@@ -15,6 +15,7 @@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';@@ -94,13 +95,22 @@ export function rankWith(request, catalog, weights) {);const route = routeProbs(catalog.data.router, query);const rows = signals(table, query, lexical.data.results, route);- return orderMatches(- table,- rank(table, rows, weights),- lexical,+ 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,- options.limit ?? 20,+ () => catalog.data.picker,);+ return withLimit(ordered, limit);}/** @type {import('./tree.mjs').SearchKit} */diff --git a/packages/cli/test/__golden__/no-icon-set/search-close.json b/packages/cli/test/__golden__/no-icon-set/search-close.jsonindex 89858dc0df..a44870642f 100644--- a/packages/cli/test/__golden__/no-icon-set/search-close.json+++ b/packages/cli/test/__golden__/no-icon-set/search-close.json@@ -16,6 +16,17 @@"command": "astryx component AlertDialog","mentions": []},+ {+ "domain": "component",+ "name": "DrawerHeader",+ "package": "@astryxdesign/core",+ "score": "<text>",+ "reason": "<text>",+ "description": "<text>",+ "import": "@astryxdesign/core/Drawer",+ "command": "astryx component DrawerHeader",+ "mentions": []+ },{"domain": "component","name": "BottomSheet",@@ -64,17 +75,6 @@"command": "astryx component Drawer","mentions": []},- {- "domain": "component",- "name": "DrawerHeader",- "package": "@astryxdesign/core",- "score": "<text>",- "reason": "<text>",- "description": "<text>",- "import": "@astryxdesign/core/Drawer",- "command": "astryx component DrawerHeader",- "mentions": []- },{"domain": "component","name": "DropdownMenuSubMenu",diff --git a/packages/cli/test/__golden__/no-icon-set/search-close.txt b/packages/cli/test/__golden__/no-icon-set/search-close.txtindex 8d1b1c3465..ef455ceb12 100644--- a/packages/cli/test/__golden__/no-icon-set/search-close.txt+++ b/packages/cli/test/__golden__/no-icon-set/search-close.txt@@ -4,6 +4,11 @@ domain: componentpackage: @astryxdesign/coreimport: @astryxdesign/core/AlertDialogcommand: pnpm exec astryx component AlertDialog+name: DrawerHeader+domain: component+package: @astryxdesign/core+import: @astryxdesign/core/Drawer+command: pnpm exec astryx component DrawerHeadername: BottomSheetdomain: componentpackage: @astryxdesign/core@@ -24,11 +29,6 @@ domain: componentpackage: @astryxdesign/coreimport: @astryxdesign/core/Drawercommand: pnpm exec astryx component Drawer-name: DrawerHeader-domain: component-package: @astryxdesign/core-import: @astryxdesign/core/Drawer-command: pnpm exec astryx component DrawerHeadername: DropdownMenuSubMenudomain: componentpackage: @astryxdesign/corediff --git a/packages/cli/test/__golden__/no-icon-set/search-delete.json b/packages/cli/test/__golden__/no-icon-set/search-delete.jsonindex ca35134d43..ea1b315765 100644--- a/packages/cli/test/__golden__/no-icon-set/search-delete.json+++ b/packages/cli/test/__golden__/no-icon-set/search-delete.json@@ -39,6 +39,19 @@"command": "astryx component Dialog","mentions": []},+ {+ "domain": "doc",+ "name": "global/uninstall",+ "package": "@astryxdesign/cli",+ "score": "<text>",+ "reason": "<text>",+ "description": "<text>",+ "section": "<text>",+ "title": "<text>",+ "command": "astryx docs global/uninstall reset",+ "parent": "astryx docs global/uninstall --index",+ "mentions": []+ },{"domain": "doc","name": "cli/api/functions/theme-template",@@ -89,19 +102,6 @@"parent": "astryx docs global/uninstall --index","mentions": []},- {- "domain": "doc",- "name": "global/uninstall",- "package": "@astryxdesign/cli",- "score": "<text>",- "reason": "<text>",- "description": "<text>",- "section": "<text>",- "title": "<text>",- "command": "astryx docs global/uninstall reset",- "parent": "astryx docs global/uninstall --index",- "mentions": []- },{"domain": "doc","name": "migration/migration-setup",diff --git a/packages/cli/test/__golden__/no-icon-set/search-delete.txt b/packages/cli/test/__golden__/no-icon-set/search-delete.txtindex 33ad6800d6..24cc44a4cc 100644--- a/packages/cli/test/__golden__/no-icon-set/search-delete.txt+++ b/packages/cli/test/__golden__/no-icon-set/search-delete.txt@@ -14,6 +14,12 @@ domain: componentpackage: @astryxdesign/coreimport: @astryxdesign/core/Dialogcommand: pnpm exec astryx component Dialog+name: global/uninstall+section: reset+domain: doc+package: @astryxdesign/cli+command: pnpm exec astryx docs global/uninstall reset+parent: pnpm exec astryx docs global/uninstall --indexname: cli/api/functions/theme-templatedomain: docpackage: @astryxdesign/cli@@ -36,12 +42,6 @@ domain: docpackage: @astryxdesign/clicommand: pnpm exec astryx docs global/uninstall agent-guideparent: pnpm exec astryx docs global/uninstall --index-name: global/uninstall-section: reset-domain: doc-package: @astryxdesign/cli-command: pnpm exec astryx docs global/uninstall reset-parent: pnpm exec astryx docs global/uninstall --indexname: migration/migration-setupsection: foundation-smoke-testdomain: doc