Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/search/search.domain-priority.test.mjs b/packages/cli/api/search/search.domain-priority.test.mjs
index 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.mjs
index 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)