An open source design system that's fully customizable and agent ready
TypeScript
fix(search): keep a guide first for a phrase it declares as a keyword (#7271)
Joey3acf184856a6
diff --git a/.changeset/search-doc-keyword-names.md b/.changeset/search-doc-keyword-names.mdnew file mode 100644index 0000000000..2ee878441f--- /dev/null+++ b/.changeset/search-doc-keyword-names.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx search` keeps a guide first when the query is a phrase the guide declares as a keyword. A guide that declares `code review` now comes before the Code component for that search, instead of below every component that matches one word. A component whose name is the whole query still comes first, and one-word queries are unchanged.++@josephfarinadiff --git a/packages/cli/api/search/search.domain-priority.test.mjs b/packages/cli/api/search/search.domain-priority.test.mjsindex f0df3d168e..04f3a14845 100644--- a/packages/cli/api/search/search.domain-priority.test.mjs+++ b/packages/cli/api/search/search.domain-priority.test.mjs@@ -75,14 +75,75 @@ async function placedGuides(route, seen = new Set()) {}describe('search domain priority — the rule', () => {- it('gives a doc no priority for a keyword or heading match', () => {+ it('gives a doc no priority for a heading match or a one-word keyword', () => {const topic = {domain: 'doc',name: 'typography/font-setup',- keywords: ['font size'],+ keywords: ['size'],titles: ['Font Setup', 'Font Sizes'],};expect(priority('font size', topic)).toBe(0);+ expect(priority('size', topic)).toBe(0);+ });++ it('gives a doc priority when the query is one of its declared keywords', () => {+ const guide = {+ domain: 'doc',+ name: 'guides/quality',+ titles: ['Is my code good?'],+ keywords: ['code review', 'review my code'],+ _declared: ['code review', 'review my code'],+ };+ expect(priority('code review', guide)).toBe(1);+ expect(priority('Code Reviews', guide)).toBe(1);+ expect(priority('review my code', guide)).toBe(1);+ // A section's keywords are its headings and code terms.+ const section = {+ ...guide,+ name: 'before-you-ship',+ _topic: 'guides/quality',+ _section: 'before-you-ship',+ };+ expect(priority('code review', section)).toBe(0);+ });++ it("gives a doc no priority for a code term or table cell it didn't declare", () => {+ // A typed doc's keywords hold the first column of its tables and the code+ // terms its text mentions; `missing_field` reads as two words.+ const reference = {+ domain: 'doc',+ name: 'cli/api/functions/validate-integration',+ titles: ['validateIntegration'],+ keywords: ['validate-integration', 'missing_field', 'file required'],+ _declared: [],+ _topic: 'cli/api/functions/validate-integration',+ };+ expect(priority('missing field', reference)).toBe(0);+ expect(priority('file required', reference)).toBe(0);+ expect(+ priority('missing field', {...reference, _declared: ['missing field']}),+ ).toBe(1);+ });++ it('keeps a component the query names exactly above a doc that declares it', async () => {+ const tokens = tokenizeQuery('empty state');+ const component = {domain: 'component', name: 'EmptyState'};+ const doc = {+ domain: 'doc',+ name: 'illustrations',+ keywords: ['empty state'],+ _declared: ['empty state'],+ };+ const c = scoreQuery('empty state', tokens, component);+ const d = scoreQuery('empty state', tokens, doc);+ expect(+ domainPriority('empty state', tokens, /** @type {any} */ (component), c),+ ).toBe(1);+ expect(+ domainPriority('empty state', tokens, /** @type {any} */ (doc), d),+ ).toBe(1);+ // Both have priority, so the stronger match wins: the exact name.+ expect(c?.score).toBeGreaterThan(d?.score ?? 0);});it('gives a doc priority when the query names it', () => {@@ -190,32 +251,46 @@ describe('search domain priority — the rule', () => {describe('search domain priority — real docs and components', () => {it(- 'finds the Text component before the typography guides for `font size`',+ 'finds a guide that declares the whole phrase above a component that matches one word',async () => {- for (const q of ['font size', 'font weight']) {- const results = (await search(q, {cwd})).data.results;- expect(results[0], q).toMatchObject({- domain: 'component',- name: 'Text',- });- const guide = results.findIndex(- r => r.domain === 'doc' && /^typography(?:\/|$)/.test(r.name),- );- // The guide still matches, below the component.- expect(guide, q).toBeGreaterThan(0);+ const results = (await search('font size', {cwd})).data.results;+ expect(results[0]).toMatchObject({domain: 'doc'});+ expect(results[0].name).toMatch(/^typography(?:\/|$)/);+ // The component the phrase points to stays near the top.+ expect(+ results+ .slice(0, 3)+ .some(r => r.domain === 'component' && r.name === 'Text'),+ ).toBe(true);+ },+ SLOW,+ );++ it(+ 'keeps a component above a reference doc whose table or code terms hold the phrase',+ async () => {+ for (const q of ['missing field', 'file required']) {+ const [top] = (await search(q, {cwd})).data.results;+ expect(top, q).toMatchObject({domain: 'component', name: 'Field'});}},SLOW,);it(- 'reports the text-match score unchanged',+ 'keeps a component above docs that match only by a heading, with scores unchanged',async () => {const results = (await search('font size', {cwd})).data.results;- const guide = results.find(- r => r.domain === 'doc' && /^typography(?:\/|$)/.test(r.name),+ const text = results.findIndex(+ r => r.domain === 'component' && r.name === 'Text',);- expect(guide?.score).toBeGreaterThan(results[0].score);+ expect(text).toBeGreaterThanOrEqual(0);+ // A doc below Text outscores it on text alone: priority moved it, not the score.+ expect(+ results+ .slice(text + 1)+ .some(r => r.domain === 'doc' && r.score > results[text].score),+ ).toBe(true);},SLOW,);diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjsindex 0056685610..fad501161d 100644--- a/packages/cli/api/search/search.mjs+++ b/packages/cli/api/search/search.mjs@@ -57,9 +57,10 @@* Between domains, ranking adds one rule ahead of the score: domain priority* (see {@link domainPriority}). A component, hook, template, or theme whose* name or keyword a query word hits ranks ahead of every doc the reader did not- * ask for by name or title, so `font size` finds `Text` before a typography- * topic that declares the phrase. A doc the query names, or whose title the- * query holds, keeps its place.+ * ask for by name, title, or a declared phrase, so `font size` finds `Text`+ * before a token page whose heading holds the phrase. A doc the query names,+ * whose title the query holds, or that declares the whole query as a keyword+ * keeps its place.** Description and guidance are separate tiers on purpose. A component's own* one-line description saying "notification" is a claim about what it IS; the@@ -138,6 +139,9 @@ import {setResultCoverage} from './coverage.mjs';* @property {string[]} [aliases] - Other names the candidate answers to, scored* with the same name signals: a theme's display name.* @property {string[]} [keywords]+ * @property {string[]} [_declared] - A doc's own declared keywords: what its+ * author lists in `keywords`, without the code terms and table cells its+ * other keywords add.* @property {string[]} [weakKeywords]* @property {string} [description]* @property {string[]} [prose]@@ -513,19 +517,20 @@ const STRONG_TOKEN_SCORE = 70;* 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 keyword, by a heading holding the query, or by+ * 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, and each declares its own keywords and headings, so a common- * phrase such as `font size` hits a guide's keyword or heading exactly- * (170-190) 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+ * 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.*@@ -551,6 +556,20 @@ export function domainPriority(term, tokens, candidate, hit) {if (named.some(n => samePhrase(term, n))) {return 2;}+ // A query of two or more words that is one of the doc's own declared+ // keywords, read as words whatever the plural, is the author naming the+ // doc for that phrase: `code review` on a guide that declares it. Only+ // what the author declared counts: the code terms and table cells a+ // doc's other keywords add (`missing_field`) name what it mentions, not+ // what it is for. One word is left out too, and a section declares+ // nothing.+ if (+ phraseWords(term).length >= 2 &&+ candidate._section == null &&+ (candidate._declared ?? []).some(k => samePhrase(term, String(k)))+ ) {+ return 1;+ }if (words.some(w =>@@ -1508,6 +1527,10 @@ async function gatherDocs(cwd) {...defined,...codeTerms({content}),],+ _declared: [+ ...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),+ ...(Array.isArray(node.keywords) ? node.keywords : []),+ ],description: node.summary || '',prose: sectionProse({title: node.title, content}),titles: [node.title],@@ -1644,6 +1667,7 @@ function topicCandidates(...(doc?.title || title ? [doc?.title || title] : []),...(Array.isArray(doc?.keywords) ? doc.keywords : []),],+ _declared: Array.isArray(doc?.keywords) ? doc.keywords : [],description: doc?.description || summary,prose: split? sections.map(section => section.title).filter(Boolean)