An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): search sees your integrations, and build stops calling one word a match (#5320)
Joey70b529590604
diff --git a/.changeset/build-kit-coverage-gate.md b/.changeset/build-kit-coverage-gate.mdnew file mode 100644index 0000000000..ef9b94c0d5--- /dev/null+++ b/.changeset/build-kit-coverage-gate.md@@ -0,0 +1,13 @@+---+'@astryxdesign/cli': patch+---++[fix] build: a page that matched one word of the query is no longer offered as a direct match. A page template's keywords include every component its source renders, so `build "actionable warning banner"` returned `login`, `contact-form` and `documentation-design` at 95 apiece — an exact keyword hit on "banner" alone, plus the coverage garnish, landing exactly on the direct-match threshold. Three pages that are not warnings, presented as the page to start from. Coverage now gates the pages group rather than garnishing its score.++Score alone could not carry the gate, so `scoreQuery` now reports the coverage it already computed: `matchedTerms` / `queryTerms` on every search result, with a whole-phrase hit reporting full coverage. A single strong hit and a broad weak one land on the same score, so a caller cannot tell "one of three concepts" from "three of three" without it.++Rebased onto current `main`, which landed integration search (#5259) and the scorer-level false-direct-match fix (#5614) while this was open. Both are `main`'s implementations, untouched here — this branch no longer rewrites `gatherComponents`, so the two regressions that rewrite caused are gone with it: an integration result reports its own package again, and a broken config no longer turns a Core `button` search into an empty success.++The other two pieces this branch used to carry now ship separately, as asked: the guidance-tier indexing in #5937 and the thin-kit hint in #5938.++@josephfarinadiff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjsindex 572938f12c..bb86a74c5a 100644--- a/packages/cli/api/build/build.test.mjs+++ b/packages/cli/api/build/build.test.mjs@@ -108,3 +108,43 @@ describe('build API', () => {expect(r.data.domain).toHaveLength(0);});});++describe('build kit — coverage gates the pages group', () => {+ it('never offers a page that answered less than half the query', async () => {+ const r = await build('actionable warning banner', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ for (const p of r.data.pages) {+ expect(p.matchedTerms / p.queryTerms).toBeGreaterThanOrEqual(0.5);+ }+ });++ it('does not call a one-word coincidence a direct match', async () => {+ // A page's keywords include every component its source renders, so any+ // page that happens to render a Banner keyword-matched "banner" at 90 —+ // which, plus the coverage garnish, landed exactly on PAGE_DIRECT. Three+ // pages that are not warnings were presented as a confident direct match.+ const r = await build('actionable warning banner', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.directMatch).toBe(false);+ for (const p of r.data.pages) {+ expect(['login', 'contact-form', 'documentation-design']).not.toContain(p.name);+ }+ });++ it('still reports a direct match when the page really does answer the query', async () => {+ const r = await build('contact form', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.directMatch).toBe(true);+ expect(r.data.pages[0].matchedTerms).toBe(r.data.pages[0].queryTerms);+ });++ it('leaves single-concept queries alone (nothing to cover)', async () => {+ const r = await build('dashboard', {cwd: REPO});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ for (const p of r.data.pages) expect(p.queryTerms).toBe(1);+ });+});diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjsindex e6a7418541..decbd2a966 100644--- a/packages/cli/api/build/kit/kit.mjs+++ b/packages/cli/api/build/kit/kit.mjs@@ -21,6 +21,20 @@ const PAGE_DIRECT = 95;const PAGE_FLOOR = 50;/** Below this a block/domain-component match is incidental noise. */const DOMAIN_FLOOR = 55;+/**+ * How much of a multi-word query a result must cover to be offered as a PAGE.+ *+ * Score alone cannot carry this. A page's keywords include every component its+ * source renders, so `build "actionable warning banner"` scored `login`,+ * `contact-form` and `documentation-design` at 95 apiece — an exact keyword hit+ * (90) on "banner" alone, plus the coverage garnish, lands exactly on+ * PAGE_DIRECT. Three pages that are not warnings, presented as a direct match,+ * because each happens to render a Banner somewhere.+ *+ * Coverage has to gate rather than garnish: matching one of three concepts is+ * not the same claim as matching three.+ */+const PAGE_COVERAGE = 0.5;/*** Always-surfaced primitives. Every page needs a shell + layout/typography/@@ -63,10 +77,24 @@ export async function buildKit(query, options = {}) {);const results = result.data.results;+ /**+ * Did this result answer enough of the query to stand as a page?+ * Single-concept queries have nothing to cover, so they always pass.+ * @param {{matchedTerms?: number, queryTerms?: number}} r+ */+ const covers = r => {+ const total = r.queryTerms ?? 1;+ if (total <= 1) return true;+ return (r.matchedTerms ?? 0) / total >= PAGE_COVERAGE;+ };+const pages = results.filter(r =>- r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR,+ r.domain === 'template' &&+ r.kind !== 'block' &&+ r.score >= PAGE_FLOOR &&+ covers(r),).slice(0, 3);const blocks = resultsdiff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjsindex 8bddaede7c..9cd90f04a6 100644--- a/packages/cli/api/search/search.mjs+++ b/packages/cli/api/search/search.mjs@@ -236,9 +236,21 @@ function bestForToken(tok, candidate) {* @param {string} term - Lowercased full query.* @param {string[]} tokens - Content tokens from tokenizeQuery(term).* @param {Candidate} candidate- * @returns {{score: number, reason: string} | null}+ * @returns {{score: number, reason: string, matched: number, total: number} | null}+ * `matched`/`total` are the query concepts this candidate answered, out of+ * the concepts the query had. Callers that must distinguish "matched one word+ * of three" from "matched all three" — `build`, which gates its pages group+ * on coverage — cannot recover that from the score, because a single strong+ * hit and a broad weak one land on the same number.*/export function scoreQuery(term, tokens, candidate) {+ const total = Math.max(tokens.length, 1);+ // A whole-phrase hit answered the whole query by definition.+ const asFull = (/** @type {{score: number, reason: string}} */ hit) => ({+ ...hit,+ matched: total,+ total,+ });const full = scoreCandidate(term, candidate);// 0–1 content tokens: keep whole-phrase fuzzy matching (typo tolerance for@@ -246,8 +258,8 @@ export function scoreQuery(term, tokens, candidate) {// "pricing page" → "pricing"), score that token too and take the stronger.if (tokens.length <= 1) {const single = tokens.length === 1 ? bestForToken(tokens[0], candidate) : null;- if (full && (!single || full.score >= single.score)) return full;- return single;+ if (full && (!single || full.score >= single.score)) return asFull(full);+ return single ? asFull(single) : null;}// Multi-word natural language: score each content token, counting only@@ -264,7 +276,7 @@ export function scoreQuery(term, tokens, candidate) {hitTerms.push(tok);}}- if (matched === 0) return full;+ if (matched === 0) return full ? asFull(full) : null;// Base the score on the STRONGEST concept that matched, plus a bonus per// additional matched concept and a coverage term.@@ -286,10 +298,12 @@ export function scoreQuery(term, tokens, candidate) {const coverage = matched / tokens.length;const tokenScore = Math.round(strongest + Math.min(matched - 1, 3) * 12 + coverage * 15);- if (full && full.score >= tokenScore) return full;+ if (full && full.score >= tokenScore) return asFull(full);return {score: tokenScore,reason: `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`,+ matched,+ total,};}@@ -686,13 +700,17 @@ async function gatherTemplates(cwd) {* @param {Candidate} c - candidate* @param {number} score* @param {string} reason+ * @param {number} matchedTerms - Query concepts this result answered.+ * @param {number} queryTerms - Query concepts there were to answer.*/-function toResult(c, score, reason) {+function toResult(c, score, reason, matchedTerms, queryTerms) {const base = {domain: c.domain,name: c.name,score,reason,+ matchedTerms,+ queryTerms,description: c.description || '',};switch (c.domain) {@@ -796,7 +814,7 @@ export async function search(query, options = {}) {const scored = [];for (const candidate of all) {const hit = scoreQuery(term, tokens, candidate);- if (hit) scored.push(toResult(candidate, hit.score, hit.reason));+ if (hit) scored.push(toResult(candidate, hit.score, hit.reason, hit.matched, hit.total));}// Sort by score desc, then domain (stable order), then name.diff --git a/packages/cli/api/search/search.type.mjs b/packages/cli/api/search/search.type.mjsindex 4a07f5f056..35ced726f9 100644--- a/packages/cli/api/search/search.type.mjs+++ b/packages/cli/api/search/search.type.mjs@@ -20,6 +20,8 @@* @property {number} score - Relevance score (higher is better).* @property {string} reason - Human-readable reason the candidate matched (e.g. `keyword "button"`).* @property {string} description - One-line description, when available.+ * @property {number} matchedTerms - How many of the query's concepts this result matched.+ * @property {number} queryTerms - How many concepts the query had. `matchedTerms / queryTerms` is the coverage; a whole-phrase match reports full coverage.* @property {string} command - Follow-up command to act on this result (e.g. `astryx component Button`).* @property {string} [import] - Import path — present for component and hook results.* @property {string} [title] - Doc title — present for doc results.