Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): rank exact keyword phrase matches above token-sum scores (#5289)

Ojas Mutrejaf44af810cbc4
diff --git a/.changeset/cli-search-exact-keyword-phrase-ranking.md b/.changeset/cli-search-exact-keyword-phrase-ranking.md
new file mode 100644
index 0000000000..9c1e797c69
--- /dev/null
+++ b/.changeset/cli-search-exact-keyword-phrase-ranking.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx search` (and `astryx build`, which shares its ranking) never surfaced a component whose exact multi-word keyword phrase was searched, if enough other unrelated candidates happened to each contain one of the query's individual words. Searching `"table of contents"` returned no results for `Outline`, even though `Outline.doc.mjs` declares `'table of contents'` verbatim as a keyword, because `Table`-related templates each matched `table` and `contents` separately and their combined per-word score outranked Outline's single exact match.
+
+A query that exactly matches a candidate's declared keyword (or name) verbatim is now promoted to a top-tier score, so it always outranks a candidate that only coincidentally contains several of the query's individual words. Single-word queries and queries that don't exactly match a keyword are unaffected.
+
+@nynexman4464
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index 9cd90f04a6..810df266d8 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -262,6 +262,21 @@ export function scoreQuery(term, tokens, candidate) {
return single ? asFull(single) : null;
}
+ // 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 {score: full.score + 100, reason: full.reason};
+ }
+
// Multi-word natural language: score each content token, counting only
// strong hits, then reward coverage so candidates matching more terms win.
let strongest = 0;
diff --git a/packages/cli/api/search/search.test.mjs b/packages/cli/api/search/search.test.mjs
index cd96ad5229..d398a4bd0e 100644
--- a/packages/cli/api/search/search.test.mjs
+++ b/packages/cli/api/search/search.test.mjs
@@ -72,6 +72,27 @@ describe('search leaf — --type filter', () => {
});
});
+describe('search leaf — exact keyword phrase outranks incidental token matches (issue #5239)', () => {
+ it('surfaces Outline for its own declared keyword "table of contents", ranked first', async () => {
+ // Before the fix, "table" and "contents" each separately matched dozens
+ // of unrelated Table-related templates by coincidence, and their
+ // combined token-sum score outranked Outline's single exact match,
+ // pushing it out of the results entirely at the default limit.
+ const r = await search('table of contents', {cwd});
+ expect(r.data.results[0]?.name).toBe('Outline');
+ }, SLOW);
+
+ it('surfaces Outline for its own declared keyword "heading navigation", ranked first', async () => {
+ const r = await search('heading navigation', {cwd});
+ expect(r.data.results[0]?.name).toBe('Outline');
+ }, SLOW);
+
+ it('still returns no results for a nonsense query (the fix does not loosen matching)', async () => {
+ const r = await search('zzzzqqqx', {cwd});
+ expect(r.data.results).toEqual([]);
+ }, SLOW);
+});
+
describe('search leaf — error paths (pinned)', () => {
it('throws ERR_INVALID_ARGUMENT when the query is empty/whitespace', async () => {
await expect(search(' ', {cwd})).rejects.toMatchObject({