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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/packages/cli/api/search/_candidate-score.mjs b/packages/cli/api/search/_candidate-score.mjsindex 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.mjsindex 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` "usediff --git a/packages/cli/api/search/_words.term.test.mjs b/packages/cli/api/search/_words.term.test.mjsnew file mode 100644index 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);+ });+});