Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/search/ORDERING.md b/packages/cli/api/search/ORDERING.md
index 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.
## Files
diff --git a/packages/cli/api/search/_order.mjs b/packages/cli/api/search/_order.mjs
index 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.mjs
new file mode 100644
index 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');
+ });
+});