Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjs
index 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.mjs
index 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 = results
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index 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.mjs
index 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.