Skip to content

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

TypeScript

perf(cli): search works out a term's forms once per entry (#10036)

Christopher Chedeau0236bb8fcf85
diff --git a/.changeset/cli-search-term-words.md b/.changeset/cli-search-term-words.md
new file mode 100644
index 0000000000..1d6007e5a0
--- /dev/null
+++ b/.changeset/cli-search-term-words.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[perf] `astryx search` and `astryx build` work out a query word's forms once per entry they score, not once per word compared. Answers are unchanged.
+
+@vjeux
diff --git a/packages/cli/api/search/_candidate-score.mjs b/packages/cli/api/search/_candidate-score.mjs
index 6acd748000..f7f39f2172 100644
--- a/packages/cli/api/search/_candidate-score.mjs
+++ b/packages/cli/api/search/_candidate-score.mjs
@@ -37,9 +37,10 @@
import {
stem,
- wordForms,
sameWord,
- startsAWordOf,
+ sameTermWord,
+ startsATermWordOf,
+ termWords,
wordsOf,
joined,
typoDistance,
@@ -78,14 +79,14 @@ function spellsOut(term, name, description) {
/**
* Whether a one-word term is a name's last word and every word before it is a
* single letter: Stack in VStack and HStack.
- * @param {string} term
+ * @param {import('./_words.mjs').TermWords} t
* @param {string} name
*/
-function headOfLetters(term, name) {
+function headOfLetters(t, name) {
const parts = wordsOf(name);
return (
parts.length >= 2 &&
- sameWord(term, parts[parts.length - 1]) &&
+ sameTermWord(t, parts[parts.length - 1]) &&
parts.slice(0, -1).every(p => p.length === 1)
);
}
@@ -96,14 +97,14 @@ const FAMILY_MEMBERS = 3;
/**
* A derived name's score for a term: 60 for the same word, 40 for a word the
* term starts, else 0.
- * @param {string} term - Lowercased search term.
+ * @param {import('./_words.mjs').TermWords} t - The lowercased search term.
* @param {string} kw - The derived name as authored.
* @returns {number}
*/
-function weakKeywordScore(term, kw) {
+function weakKeywordScore(t, kw) {
const kwLower = String(kw).toLowerCase();
- if (kwLower === term || sameWord(term, kwLower)) return 60;
- return startsAWordOf(term, kw) ? 40 : 0;
+ if (kwLower === t.term || sameTermWord(t, kwLower)) return 60;
+ return startsATermWordOf(t, kw) ? 40 : 0;
}
/**
@@ -146,6 +147,8 @@ export function scoreCandidate(
_family,
_familyIndex,
} = candidate;
+ // The term's forms, worked out once for every word below.
+ const t = termWords(term);
let best = 0;
let reason = '';
/** @type {'partial' | 'keyword' | false} */
@@ -208,18 +211,18 @@ export function scoreCandidate(
// outranks the Token component for `tokens`.
consider(99, 'plural of the name');
} else {
- if (sameWord(term, nameLower)) consider(95, `name "${candidateName}"`);
+ if (sameTermWord(t, nameLower)) consider(95, `name "${candidateName}"`);
// The term is a word of the name, or starts one: "input" in TextInput.
else if (
!part &&
domain !== 'doc' &&
domain !== 'theme' &&
- headOfLetters(term, candidateName)
+ headOfLetters(t, candidateName)
) {
// The whole query is the name's head word after single letters (Stack
// in VStack, HStack): a variant named by its head, as a keyword is.
consider(90, `name "${candidateName}" ends in "${term}"`);
- } else if (startsAWordOf(term, candidateName)) {
+ } else if (startsATermWordOf(t, candidateName)) {
consider(60, `name contains "${term}"`);
}
if (fuzzy) {
@@ -273,11 +276,11 @@ export function scoreCandidate(
consider(90, `keyword "${kw}"`, 'keyword');
continue;
}
- if (sameWord(term, kwLower)) {
+ if (sameTermWord(t, kwLower)) {
consider(88, `keyword "${kw}"`);
continue;
}
- if (startsAWordOf(term, kw)) consider(70, `keyword "${kw}"`);
+ if (startsATermWordOf(t, kw)) consider(70, `keyword "${kw}"`);
if (fuzzy) {
const dist = typoDistance(term, kwLower);
if (dist != null && dist <= 2) {
@@ -294,9 +297,9 @@ export function scoreCandidate(
// A bound skips the read when no name the page can yield matches the term,
// and then no weak keyword can match it either.
const bound = candidate.weakKeywordBound;
- if (!bound || bound.some(kw => weakKeywordScore(term, kw) > 0)) {
+ if (!bound || bound.some(kw => weakKeywordScore(t, kw) > 0)) {
for (const kw of candidate.weakKeywords ?? []) {
- const score = weakKeywordScore(term, kw);
+ const score = weakKeywordScore(t, kw);
if (score > 0) consider(score, `renders ${kw}`);
}
}
@@ -307,7 +310,7 @@ export function scoreCandidate(
if (term.length >= 3) {
// Any form of the term, with any common suffix: `spacing` finds
// "space" and "spaces", `tables` finds "table".
- const roots = [...new Set([stem(term), ...wordForms(term)])]
+ const roots = [...new Set([stem(term), ...t.forms])]
.filter(f => f.length >= 3)
.map(f => f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
const re = new RegExp(`\\b(?:${roots.join('|')})(s|es|ing|ed|ies)?\\b`);
diff --git a/packages/cli/api/search/_words.mjs b/packages/cli/api/search/_words.mjs
index 0d6c163431..c9c33222c6 100644
--- a/packages/cli/api/search/_words.mjs
+++ b/packages/cli/api/search/_words.mjs
@@ -26,27 +26,47 @@ export function stem(w) {
}
/**
- * The forms of a word that count as the same word: itself, its stem, and its
- * singular when it ends in a plural suffix — so "tables" is "table",
- * "statuses" is "status", and "filtering" is "filter".
+ * Visits the forms of a word that count as the same word, in order, until a
+ * visit returns true. The forms are the word, its stem, and its singular when
+ * it ends in a plural suffix. So "tables" is "table", "statuses" is "status",
+ * and "filtering" is "filter".
* @param {string} w - Lowercase word.
- * @returns {Set<string>}
+ * @param {(form: string) => boolean} visit
+ * @returns {boolean} whether a visit returned true
*/
-export function wordForms(w) {
- const forms = new Set([w, stem(w)]);
- if (w.length > 3 && w.endsWith('s')) forms.add(w.slice(0, -1));
- if (w.length > 4 && w.endsWith('es')) forms.add(w.slice(0, -2));
- if (w.length > 4 && w.endsWith('ies')) forms.add(w.slice(0, -3) + 'y');
+function someForm(w, visit) {
+ if (visit(w) || visit(stem(w))) return true;
+ if (w.length > 3 && w.endsWith('s') && visit(w.slice(0, -1))) return true;
+ if (w.length > 4 && w.endsWith('es') && visit(w.slice(0, -2))) return true;
+ if (w.length > 4 && w.endsWith('ies') && visit(w.slice(0, -3) + 'y')) {
+ return true;
+ }
// A gerund keeps its verb: "spacing" lost a final e ("space"), and
// "dragging" doubled a consonant ("drag"). A past participle does not: it
// usually describes a state ("archived notes"), not the action a catalog
// word names.
if (w.length >= 6 && w.endsWith('ing')) {
const base = w.slice(0, -3);
- forms.add(base);
- forms.add(`${base}e`);
- if (/([b-df-hj-np-tv-z])\1$/.test(base)) forms.add(base.slice(0, -1));
+ if (visit(base) || visit(`${base}e`)) return true;
+ if (/([b-df-hj-np-tv-z])\1$/.test(base) && visit(base.slice(0, -1))) {
+ return true;
+ }
}
+ return false;
+}
+
+/**
+ * The forms of a word that count as the same word (see someForm).
+ * @param {string} w - Lowercase word.
+ * @returns {Set<string>}
+ */
+export function wordForms(w) {
+ /** @type {Set<string>} */
+ const forms = new Set();
+ someForm(w, form => {
+ forms.add(form);
+ return false;
+ });
return forms;
}
@@ -74,8 +94,38 @@ function singulars(w) {
export function sameWord(a, b) {
if (a === b) return true;
const forms = wordForms(a);
- for (const f of wordForms(b)) if (forms.has(f)) return true;
- return false;
+ return someForm(b, form => forms.has(form));
+}
+
+/**
+ * A search term's forms and the word starts it matches, worked out once for
+ * every word the term is compared with.
+ * @typedef {{term: string, forms: Set<string>, starts: string[]}} TermWords
+ */
+
+/**
+ * @param {string} term - Lowercase term.
+ * @returns {TermWords}
+ */
+export function termWords(term) {
+ return {
+ term,
+ forms: wordForms(term),
+ // The term or its singular may start the word: "tokens" starts
+ // "tokenizer" through "token". A singular needs five letters, so "stats"
+ // does not start "status".
+ starts: [term, ...singulars(term).filter(f => f.length >= 5)],
+ };
+}
+
+/**
+ * Whether a lowercase word is the term's word, as sameWord answers.
+ * @param {TermWords} t
+ * @param {string} w
+ * @returns {boolean}
+ */
+export function sameTermWord(t, w) {
+ return w === t.term || someForm(w, form => t.forms.has(form));
}
/**
@@ -103,17 +153,33 @@ export function wordsOf(text) {
* @returns {boolean}
*/
export function startsAWordOf(term, text) {
- if (term.length < 4) return false;
- if (term.length / String(text).length < 0.5) return false;
- // The term or its singular may start the word: "tokens" starts
- // "tokenizer" through "token". A singular needs five letters, so "stats"
- // does not start "status".
- const starts = [term, ...singulars(term).filter(f => f.length >= 5)];
+ if (!coversHalf(term, text)) return false;
+ return startsATermWordOf(termWords(term), text);
+}
+
+/**
+ * startsAWordOf for a term whose words are already worked out.
+ * @param {TermWords} t
+ * @param {string} text - The name or keyword as authored.
+ * @returns {boolean}
+ */
+export function startsATermWordOf(t, text) {
+ if (!coversHalf(t.term, text)) return false;
return wordsOf(text).some(
- w => starts.some(f => w.startsWith(f)) || sameWord(term, w),
+ w => t.starts.some(f => w.startsWith(f)) || sameTermWord(t, w),
);
}
+/**
+ * Whether a term is long enough to match inside `text`: four letters, and at
+ * least half of the text.
+ * @param {string} term
+ * @param {string} text
+ */
+function coversHalf(term, text) {
+ return term.length >= 4 && term.length / String(text).length >= 0.5;
+}
+
/**
* A query with its camelCase and PascalCase identifiers spelled as words, so
* `SidebarToggle` reads "sidebar toggle" and `useTablePaginationState` "use
diff --git a/packages/cli/api/search/_words.term.test.mjs b/packages/cli/api/search/_words.term.test.mjs
new file mode 100644
index 0000000000..d81cb981c0
--- /dev/null
+++ b/packages/cli/api/search/_words.term.test.mjs
@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A term's words (termWords in _words.mjs) answer as sameWord and
+ * startsAWordOf did, and scoring one candidate builds the term's forms once,
+ * not once for every word it compares.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {scoreCandidate} from './_candidate-score.mjs';
+import {
+ sameTermWord,
+ sameWord,
+ startsATermWordOf,
+ startsAWordOf,
+ stem,
+ termWords,
+ wordForms,
+ wordsOf,
+} from './_words.mjs';
+
+/**
+ * The forms of a word as they were worked out before termWords, kept here as
+ * the reference answer.
+ * @param {string} w
+ */
+function referenceForms(w) {
+ const forms = new Set([w, stem(w)]);
+ if (w.length > 3 && w.endsWith('s')) forms.add(w.slice(0, -1));
+ if (w.length > 4 && w.endsWith('es')) forms.add(w.slice(0, -2));
+ if (w.length > 4 && w.endsWith('ies')) forms.add(w.slice(0, -3) + 'y');
+ if (w.length >= 6 && w.endsWith('ing')) {
+ const base = w.slice(0, -3);
+ forms.add(base);
+ forms.add(`${base}e`);
+ if (/([b-df-hj-np-tv-z])\1$/.test(base)) forms.add(base.slice(0, -1));
+ }
+ return forms;
+}
+
+/** @param {string} a @param {string} b */
+function referenceSameWord(a, b) {
+ if (a === b) return true;
+ const forms = referenceForms(a);
+ for (const f of referenceForms(b)) if (forms.has(f)) return true;
+ return false;
+}
+
+/** @param {string} term @param {string} text */
+function referenceStarts(term, text) {
+ if (term.length < 4) return false;
+ if (term.length / String(text).length < 0.5) return false;
+ const singulars = [];
+ if (term.length > 3 && term.endsWith('s')) singulars.push(term.slice(0, -1));
+ if (term.length > 4 && term.endsWith('es')) singulars.push(term.slice(0, -2));
+ if (term.length > 4 && term.endsWith('ies')) {
+ singulars.push(term.slice(0, -3) + 'y');
+ }
+ const starts = [term, ...singulars.filter(f => f.length >= 5)];
+ return wordsOf(text).some(
+ w => starts.some(f => w.startsWith(f)) || referenceSameWord(term, w),
+ );
+}
+
+const WORDS = [
+ 'table',
+ 'tables',
+ 'status',
+ 'statuses',
+ 'entry',
+ 'entries',
+ 'filter',
+ 'filtering',
+ 'filtered',
+ 'space',
+ 'spacing',
+ 'drag',
+ 'dragging',
+ 'run',
+ 'running',
+ 'box',
+ 'boxes',
+ 'token',
+ 'tokens',
+ 'tokenizer',
+ 'stats',
+ 'chart',
+ 'charts',
+ 'charting',
+ 'dashboard',
+ 'dashboards',
+ 'menu',
+ 'menus',
+ 'select',
+ 'selection',
+ 'series',
+ 'is',
+ 'as',
+ 'ties',
+ 'skies',
+ 'thing',
+ 'things',
+ 'sing',
+];
+const TEXTS = [
+ 'TextInput',
+ 'Dashboard - Analytics',
+ 'tokenizer',
+ 'StatusBadge',
+ 'DataTable',
+ 'filters',
+ 'Charting Guide',
+ 'boxes',
+ 'spacing scale',
+ 'drag and drop',
+];
+
+describe('termWords', () => {
+ it('works out the forms sameWord and startsAWordOf use, for every pair', () => {
+ for (const w of WORDS) {
+ expect([...wordForms(w)], w).toEqual([...referenceForms(w)]);
+ }
+ for (const a of WORDS) {
+ const t = termWords(a);
+ for (const b of WORDS) {
+ const answer = referenceSameWord(a, b);
+ expect(sameWord(a, b), `${a} ${b}`).toBe(answer);
+ expect(sameTermWord(t, b), `${a} ${b}`).toBe(answer);
+ }
+ for (const text of [...TEXTS, ...WORDS]) {
+ const answer = referenceStarts(a, text);
+ expect(startsAWordOf(a, text), `${a} in ${text}`).toBe(answer);
+ expect(startsATermWordOf(t, text), `${a} in ${text}`).toBe(answer);
+ }
+ }
+ });
+
+ it("builds the term's forms once when scoring a candidate with many keywords", () => {
+ const candidate = {
+ name: 'ChartLegend',
+ domain: 'component',
+ keywords: WORDS.map(w => `${w} legend`),
+ description: 'A legend for a chart.',
+ };
+ let built = 0;
+ const RealSet = globalThis.Set;
+ globalThis.Set = class extends RealSet {
+ /** @param {Iterable<unknown>} [values] */
+ constructor(values) {
+ super(values);
+ built += 1;
+ }
+ };
+ try {
+ scoreCandidate('dashboards', candidate);
+ } finally {
+ globalThis.Set = RealSet;
+ }
+ // One set for the term's forms, one for the prose pattern's roots.
+ expect(built).toBe(2);
+ });
+});