Skip to content

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.md
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.json
index 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"
}
]
}