An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): search ranks a theme's description as prose, not as keywords (#7042)
Cindy Zhang310472999db4
diff --git a/.changeset/search-theme-description-prose.md b/.changeset/search-theme-description-prose.mdnew file mode 100644index 0000000000..f480dc47b5--- /dev/null+++ b/.changeset/search-theme-description-prose.md@@ -0,0 +1,8 @@+---+'@astryxdesign/cli': patch+---++[fix] Search ranks a theme's description as prose, not as keywords+@cixzhang++A word a theme shares with your query only through its description, such as `minimal`, `focus` or `content`, now ranks the theme like any other description instead of like a declared keyword, so it no longer lands above the components, hooks and docs that declare that word. A theme still comes first for its own slug or display name: `astryx search neutral` finds the Neutral theme first.diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjsindex f9c95347cc..50b7d88cc8 100644--- a/packages/cli/api/search/search.mjs+++ b/packages/cli/api/search/search.mjs@@ -113,6 +113,8 @@ import {setResultCoverage} from './coverage.mjs';* @typedef {object} Candidate* @property {'component'|'hook'|'doc'|'template'|'theme'} domain* @property {string} name+ * @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[]} [weakKeywords]* @property {string} [description]@@ -717,6 +719,7 @@ export function scoreQuery(term, tokens, candidate) {* @param {string} term - Lowercased search term.* @param {object} candidate* @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).+ * @param {string[]} [candidate.aliases] - Other names, scored like the name (a theme's display name).* @param {string} [candidate.domain] - A component, hook, or template name* also matches typed as words: `command palette` is CommandPalette.* @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).@@ -731,6 +734,7 @@ export function scoreCandidate(term,{name,+ aliases = [],domain,keywords = [],weakKeywords = [],@@ -753,40 +757,44 @@ export function scoreCandidate(}};- const nameLower = name.toLowerCase();- // A placed guide's name is its route, and the route's last segment is its- // name too, as a flat topic's is: `codemods` is cli/integrations/codemods.- const leafLower = nameLower.slice(nameLower.lastIndexOf('/') + 1);-// ── Name signals ────────────────────────────────────────────────- // A plural of the name is the name: `integration` is the `integrations`- // guides, `tab` the `tabs` doc.- // A component, hook, or template name typed as words is its name:- // `command palette` is CommandPalette. A doc's name is a route or key,- // matched as written.- const spelled =- domain !== 'doc' &&- !/[\s_-]/.test(nameLower) &&- nameLower === term.replace(/\s+/g, '');- if (nameLower === term || leafLower === term || spelled) {- consider(100, 'exact name');- } else if (pluralOf(nameLower, term) || pluralOf(term, nameLower)) {- // One point under the exact spelling, so the doc named `tokens` still- // outranks the Token component for `tokens`.- consider(99, 'plural of the name');- } else {- if (sameWord(term, nameLower)) consider(95, `name "${name}"`);- // The term is a word of the name, or starts one: "input" in TextInput.- else if (startsAWordOf(term, name)) {- consider(60, `name contains "${term}"`);- }- if (fuzzy) {- const dist = levenshteinDistance(term, nameLower);- if (isTypo(term, nameLower, dist)) {- consider(- dist === 1 ? 80 : dist === 2 ? 40 : 20,- `similar name (distance ${dist})`,- );+ // An alias is a name too: a theme answers to its display name as well as+ // its slug.+ for (const candidateName of [name, ...aliases.filter(Boolean)]) {+ const nameLower = candidateName.toLowerCase();+ // A placed guide's name is its route, and the route's last segment is its+ // name too, as a flat topic's is: `codemods` is cli/integrations/codemods.+ const leafLower = nameLower.slice(nameLower.lastIndexOf('/') + 1);++ // A plural of the name is the name: `integration` is the `integrations`+ // guides, `tab` the `tabs` doc.+ // A component, hook, or template name typed as words is its name:+ // `command palette` is CommandPalette. A doc's name is a route or key,+ // matched as written.+ const spelled =+ domain !== 'doc' &&+ !/[\s_-]/.test(nameLower) &&+ nameLower === term.replace(/\s+/g, '');+ if (nameLower === term || leafLower === term || spelled) {+ consider(100, 'exact name');+ } else if (pluralOf(nameLower, term) || pluralOf(term, nameLower)) {+ // One point under the exact spelling, so the doc named `tokens` still+ // outranks the Token component for `tokens`.+ consider(99, 'plural of the name');+ } else {+ if (sameWord(term, nameLower)) consider(95, `name "${candidateName}"`);+ // The term is a word of the name, or starts one: "input" in TextInput.+ else if (startsAWordOf(term, candidateName)) {+ consider(60, `name contains "${term}"`);+ }+ if (fuzzy) {+ const dist = levenshteinDistance(term, nameLower);+ if (isTypo(term, nameLower, dist)) {+ consider(+ dist === 1 ? 80 : dist === 2 ? 40 : 20,+ `similar name (distance ${dist})`,+ );+ }}}}@@ -1487,6 +1495,12 @@ async function gatherTemplates(cwd) {* Build theme candidates from bundled and integration-provided themes. Without* this, an integration's themes are invisible to `search` even though* `theme list` and `discover` already resolve them.+ *+ * A theme's slug and display name are its names, and its description is prose+ * (`spec:AST-050/FR14`). A theme declares no keywords, so a word it shares with+ * the query only through its description is a description mention: read as a+ * keyword, every word of the description would outrank the components and docs+ * that declare that word.* @param {string} cwd* @returns {Promise<Candidate[]>}*/@@ -1500,10 +1514,7 @@ async function gatherThemes(cwd) {return themes.map(t => ({domain: 'theme',name: t.slug,- keywords: [- t.displayName,- ...(t.description ? t.description.split(/[^A-Za-z0-9]+/).filter(w => w.length > 3) : []),- ],+ aliases: t.displayName ? [t.displayName] : [],description: t.description || '',_displayName: t.displayName,_package: t.package,diff --git a/packages/cli/api/search/search.test.mjs b/packages/cli/api/search/search.test.mjsindex ca297daaf5..3ccd25ee23 100644--- a/packages/cli/api/search/search.test.mjs+++ b/packages/cli/api/search/search.test.mjs@@ -25,6 +25,8 @@ import * as os from 'node:os';import * as path from 'node:path';import {fileURLToPath} from 'node:url';import {docs} from '../docs/docs.mjs';+import {listAvailableThemes} from '../theme/_adapter.mjs';+import {doc as themeAddCommandDoc} from '../../clients/cli/commands/theme-add.doc.mjs';import {headingWithPhrase,titleInQuery,@@ -76,7 +78,10 @@ describe('search leaf — envelope + ranking', () => {describe('search leaf — per-domain result fields', () => {it('carries import for components and hooks, title for docs, displayName and kind for templates, displayName for themes', async () => {- const r = await search('theme', {cwd, limit: 60});+ // `theme` reaches every domain, but a theme matches it only through its+ // description, a prose mention below every name and keyword hit, so read+ // the whole result list.+ const r = await search('theme', {cwd, limit: 400});expect(new Set(r.data.results.map(res => res.domain))).toEqual(new Set(SEARCH_DOMAINS),);@@ -499,6 +504,114 @@ describe('search leaf — limit validation (API matches the CLI contract)', () =}, SLOW);});+describe('search leaf — a theme is found by its names; its description is prose (AST-050 FR14)', () => {+ /** A result that answers the query by a name or a declared keyword, not a typo or a mention. */+ const matchesByNameOrKeyword = (/** @type {{reason: string}} */ result) =>+ /^(exact name|plural of the name|name "|name contains ")/.test(result.reason) ||+ /^keyword "[^"]*"$/.test(result.reason);++ /**+ * The `theme add` command AST-050 FR12 and FR13 name for the stage that+ * `theme add` itself declares: no `--import` yet, a deprecated copy default+ * beside `--import`, or the cleanup, which keeps `--import` and drops the+ * copy's `--overwrite`.+ * @param {string} slug+ */+ function themeAddCommandForStage(slug) {+ const flags = themeAddCommandDoc.options.flatMap(option => option.flag.split(/[\s,]+/));+ if (!flags.includes('--import')) return `astryx theme add ${slug}`;+ if (flags.includes('--overwrite')) return `astryx theme add --import ${slug}`;+ return `astryx theme add ${slug}`;+ }++ it(+ 'ranks a theme found only through its description below every name and keyword match',+ async () => {+ for (const [query, slugs] of [+ ['focus', ['neutral']],+ ['content', ['matcha', 'neutral']],+ ]) {+ const {results} = (await search(query, {cwd, limit: 400})).data;+ const strong = results.filter(+ result => result.domain !== 'theme' && matchesByNameOrKeyword(result),+ );+ expect(strong.length).toBeGreaterThan(0);+ const lastStrong = Math.max(...strong.map(result => results.indexOf(result)));+ for (const slug of slugs) {+ const at = results.findIndex(result => result.domain === 'theme' && result.name === slug);+ expect(at).toBeGreaterThan(-1);+ expect(results[at].reason).toMatch(/^description mentions /);+ expect(at).toBeGreaterThan(lastStrong);+ }+ }+ },+ SLOW,+ );++ it(+ 'scores a word in a theme description the same as a word in a component description',+ async () => {+ const {results} = (await search('minimal', {cwd, limit: 400})).data;+ const neutral = results.find(result => result.domain === 'theme' && result.name === 'neutral');+ const topNav = results.find(result => result.domain === 'component' && result.name === 'TopNav');+ expect(neutral?.reason).toMatch(/^description mentions /);+ expect(topNav?.reason).toMatch(/^description mentions /);+ expect(neutral?.score).toBe(topNav?.score);+ },+ SLOW,+ );++ it(+ 'keeps a theme that matches every word only in its description below results with a keyword hit',+ async () => {+ // Overlay and Dialog declare `focus` and mention `content`; neutral only+ // mentions both, in "so the content stays the focus".+ const {results} = (await search('content focus', {cwd, limit: 400})).data;+ const neutral = results.findIndex(result => result.domain === 'theme' && result.name === 'neutral');+ expect(neutral).toBeGreaterThan(-1);+ for (const name of ['Overlay', 'Dialog']) {+ const at = results.findIndex(result => result.domain === 'component' && result.name === name);+ expect(at).toBeGreaterThan(-1);+ expect(at).toBeLessThan(neutral);+ }+ },+ SLOW,+ );++ it(+ 'still finds a theme first by its slug or its display name',+ async () => {+ for (const query of ['neutral', 'Matcha', 'Y2K']) {+ const [first] = (await search(query, {cwd})).data.results;+ expect(first).toMatchObject({domain: 'theme', name: query.toLowerCase(), reason: 'exact name'});+ }+ },+ SLOW,+ );++ it('scores a display name with the same name signals as the slug', () => {+ const theme = {name: 'ocean', aliases: ['Ocean Blue'], description: 'Deep blues for calm reading.'};+ expect(scoreCandidate('ocean blue', theme)).toEqual(scoreCandidate('ocean', theme));+ expect(scoreCandidate('ocean blue', {...theme, aliases: []})?.score ?? 0).toBeLessThan(+ scoreCandidate('ocean', theme).score,+ );+ });++ it(+ 'names the theme add command for the stage theme add declares',+ async () => {+ const themes = await listAvailableThemes(cwd);+ expect(themes.length).toBeGreaterThan(0);+ for (const {slug} of themes) {+ const {results} = (await search(slug, {cwd, type: 'theme'})).data;+ const result = results.find(entry => entry.name === slug);+ expect(result?.command).toBe(themeAddCommandForStage(slug));+ }+ },+ SLOW,+ );+});+describe('search leaf — integration components', () => {/*** A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`diff --git a/packages/cli/clients/cli/commands/search.test.mjs b/packages/cli/clients/cli/commands/search.test.mjsindex d6a08d1a6d..f288dd4955 100644--- a/packages/cli/clients/cli/commands/search.test.mjs+++ b/packages/cli/clients/cli/commands/search.test.mjs@@ -288,22 +288,31 @@ describe('search CLI — exit codes + JSON contract', () => {});it('prints every result field under its JSON key (score and reason with --verbose)', async () => {- // One query that reaches every domain, so every per-domain field shows.- const args = ['search', 'theme', '--limit', '60'];- const env = JSON.parse((await runCli(['--json', ...args], REPO_ROOT)).stdout);- expect(new Set(env.data.results.map(r => r.domain))).toEqual(new Set(SEARCH_DOMAINS));- const plain = (await runCli(args, REPO_ROOT)).stdout.split('\n');- const verbose = (await runCli([...args, '--verbose'], REPO_ROOT)).stdout.split('\n');- for (const result of env.data.results) {- for (const [key, value] of Object.entries(result)) {- if (value == null || value === '') continue;- const label = `${result.domain} ${result.name}: ${key}`;- expect(printsField(verbose, key, value), label).toBe(true);- if (key !== 'score' && key !== 'reason') {- expect(printsField(plain, key, value), label).toBe(true);+ // Between them these reach every domain, so every per-domain field shows.+ // A theme matches `theme` only through its description, a prose mention+ // ranked below every name and keyword hit, so the theme domain comes from+ // a theme's own name.+ const domains = new Set();+ for (const args of [+ ['search', 'theme', '--limit', '60'],+ ['search', 'neutral', '--type', 'theme'],+ ]) {+ const env = JSON.parse((await runCli(['--json', ...args], REPO_ROOT)).stdout);+ const plain = (await runCli(args, REPO_ROOT)).stdout.split('\n');+ const verbose = (await runCli([...args, '--verbose'], REPO_ROOT)).stdout.split('\n');+ for (const result of env.data.results) {+ domains.add(result.domain);+ for (const [key, value] of Object.entries(result)) {+ if (value == null || value === '') continue;+ const label = `${result.domain} ${result.name}: ${key}`;+ expect(printsField(verbose, key, value), label).toBe(true);+ if (key !== 'score' && key !== 'reason') {+ expect(printsField(plain, key, value), label).toBe(true);+ }}}}+ expect(domains).toEqual(new Set(SEARCH_DOMAINS));}, 90_000);it('--verbose exits 0 and prints import/match detail', async () => {diff --git a/packages/cli/test/__golden__/search.json b/packages/cli/test/__golden__/search.jsonindex 568d44bfbe..5786d4935d 100644--- a/packages/cli/test/__golden__/search.json+++ b/packages/cli/test/__golden__/search.json@@ -14,16 +14,6 @@"import": "@acme/kit","command": "astryx component AcmeCard"},- {- "domain": "theme",- "name": "ocean",- "score": 90,- "reason": "keyword \"zorblax\"",- "description": "A zorblax blue.",- "displayName": "Ocean",- "command": "astryx theme add ocean",- "package": "@acme/kit"- },{"domain": "doc","name": "acme-guide",@@ -44,6 +34,16 @@"displayName": "Zorblax hero","kind": "block","command": "astryx template hero --type block"+ },+ {+ "domain": "theme",+ "name": "ocean",+ "score": 50,+ "reason": "description mentions \"zorblax\"",+ "description": "A zorblax blue.",+ "displayName": "Ocean",+ "command": "astryx theme add ocean",+ "package": "@acme/kit"}]}