An open source design system that's fully customizable and agent ready
TypeScript
search: order tied results below the first by fit, not by name (#7959)
Joey1a316222075b
diff --git a/.changeset/search-tie-order.md b/.changeset/search-tie-order.mdnew file mode 100644index 0000000000..6c3c8f5d61--- /dev/null+++ b/.changeset/search-tie-order.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx search` orders results the matcher scored the same by fit instead of by name: below the first result, a part of it leads (BadgeCountBadges after Badge), then the result matching the query's rarer words. Scores and the first result are unchanged.++@josephfarinadiff --git a/packages/cli/api/search/ORDERING.md b/packages/cli/api/search/ORDERING.mdindex d2ef0700a2..7099ed4a70 100644--- a/packages/cli/api/search/ORDERING.md+++ b/packages/cli/api/search/ORDERING.md@@ -4,7 +4,7 @@## Rule-`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, in the lexical ranker's order, 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. Matches never cross bands or kinds. There is no model runtime: every number is a plain static value read at load time.+`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.## Filesdiff --git a/packages/cli/api/search/_order.mjs b/packages/cli/api/search/_order.mjsindex 99281aef06..1ed1321514 100644--- a/packages/cli/api/search/_order.mjs+++ b/packages/cli/api/search/_order.mjs@@ -9,14 +9,15 @@* 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.+ * that scored the same move 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.+ * Below the first result, a block of one domain is ordered by fit (tiesByFit): a part of the first result, then rarer matched+ * words, then the lexical order.*/import {entryOf} from './_entries.mjs';-import {words} from './_query-words.mjs';+import {fold, nameWords, words} from './_query-words.mjs';import {searchedComponentsOf} from './_result.mjs';/** @typedef {import('./_entries.mjs').EntryTable} EntryTable */@@ -104,9 +105,12 @@ export function orderMatches(table, order, lexical, query, limit) {ranked = keepLexical(ranked, it => (it.res.score ?? 0) >= FULL_COVERAGE);}ranked = integrationTies(ranked);+ // Each whole tie is ordered by fit before the limit, so every limit shows+ // the top of one answer.+ const shown = tiesByFit(ranked, table, blockOf).slice(0, limit);const response = {...lexical,- data: {...lexical.data, results: ranked.slice(0, limit).map(it => it.res)},+ data: {...lexical.data, results: shown.map(it => it.res)},};const searched = searchedComponentsOf.get(lexical);if (searched) searchedComponentsOf.set(response, searched);@@ -117,6 +121,71 @@ export function orderMatches(table, order, lexical, query, limit) {* @typedef {{res: any, i: number, band: number, learned: number}} Item*/+/** How many parts of the first result lead their ties, across an answer. */+const PARTS_FIRST = 2;++/**+ * Below the first result, matches the lexical ranker scored the same keep+ * their block but are no longer in name order inside it: a part or sibling of+ * the first result leads (TableRow after Table), then the match whose matched+ * words are rarer in the catalog, so a match on a common word alone sits+ * below one on the query's telling words. Nothing crosses a block.+ * @param {Item[]} ranked+ * @param {EntryTable} table+ * @param {(item: Item) => string} blockOf+ * @returns {Item[]}+ */+function tiesByFit(ranked, table, blockOf) {+ if (ranked.length < 3) return ranked;+ const first = nameWords(String(ranked[0].res.name ?? '')).map(fold);+ const idf = table.fields.desc.idf;+ const rarest = Math.max(0, ...idf.values());+ /** @param {Item} it */+ const related = it => {+ // A part's name words start with the first result's whole name words:+ // TableRow is a part of Table, Table is no part of Tab.+ const name = nameWords(String(it.res.name ?? '')).map(fold);+ return (+ (first.length > 0 &&+ name.length > first.length &&+ first.every((w, n) => name[n] === w)) ||+ /^member of /.test(it.res.reason ?? '')+ );+ };+ /** @param {Item} it */+ const rarity = it => {+ const m = /^matches \d+\/\d+ terms: (.*)$/.exec(it.res.reason ?? '');+ if (!m) return 0;+ let sum = 0;+ // A matched term counts by its alphanumeric parts (`three-dot`), and a+ // part the catalog never uses is as rare as a word can be.+ for (const t of m[1].split(', '))+ for (const part of words(t)) sum += idf.get(fold(part)) ?? rarest;+ return sum;+ };+ const out = [ranked[0]];+ let parts = 0;+ for (let i = 1; i < ranked.length;) {+ let j = i;+ const at = (/** @type {Item} */ it) => `${blockOf(it)}:${it.res.domain}`;+ while (j < ranked.length && at(ranked[j]) === at(ranked[i])) j++;+ const run = ranked.slice(i, j);+ if (run.length > 1) {+ const keyed = run.map((it, n) => {+ // At most PARTS_FIRST parts lead, across the answer, so a family+ // with many parts does not crowd out what else the query matched.+ const r = parts < PARTS_FIRST && related(it);+ if (r) parts++;+ return {it, n, r, f: rarity(it)};+ });+ keyed.sort((a, b) => Number(b.r) - Number(a.r) || b.f - a.f || a.n - b.n);+ out.push(...keyed.map(k => k.it));+ } else out.push(...run);+ i = j;+ }+ return out;+}+/*** The matches `pick` selects keep the places they hold, filled in lexical* order.diff --git a/packages/cli/api/search/search.tie-order.test.mjs b/packages/cli/api/search/search.tie-order.test.mjsnew file mode 100644index 0000000000..7742de67cd--- /dev/null+++ b/packages/cli/api/search/search.tie-order.test.mjs@@ -0,0 +1,39 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Below the first result, matches the lexical ranker scored the same+ * are ordered by fit, not by name: a part of the first result leads its tie,+ * then the match on the query's rarer words. Scores, reasons and the set of+ * results stay the lexical ranker's (see _order.test.mjs).+ */++import {describe, expect, it} from 'vitest';+import {search} from './search.mjs';++describe('ties below the first result', () => {+ it('a part of the first result leads its tie', async () => {+ const results = (await search('progress bar with percent')).data.results;+ expect(results[0]).toMatchObject({name: 'ProgressBar'});+ expect(results[1]?.name).toMatch(/^ProgressBar./);+ });++ it('shows the top of one answer at every limit', async () => {+ const query = 'progress bar with percent';+ const all = (await search(query)).data.results.map(r => r.name);+ const three = (await search(query, {limit: 3})).data.results.map(+ r => r.name,+ );+ expect(three).toEqual(all.slice(0, 3));+ });++ it('reads a punctuated query word by its parts', async () => {+ const results = (await search('three-dot menu with actions')).data.results;+ expect(results.slice(0, 3).map(r => r.name)).toContain('MoreMenu');+ });++ it('lets few parts lead, so a big family keeps the rest in view', async () => {+ const results = (await search('chat')).data.results.map(r => r.name);+ expect(results).toContain('ai-chat');+ expect(results).toContain('ai-chat-landing');+ });+});