Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): keep search coverage internal (#5994)

Cindy Zhangea1b9b58c368
diff --git a/.changeset/search-exact-phrase-coverage.md b/.changeset/search-exact-phrase-coverage.md
new file mode 100644
index 0000000000..651a91fd31
--- /dev/null
+++ b/.changeset/search-exact-phrase-coverage.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Keep query-coverage metadata internal to build ranking while preserving it for promoted exact-phrase matches.
+
+@cixzhang
diff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjs
index debaac6973..74af20f91e 100644
--- a/packages/cli/api/build/build.test.mjs
+++ b/packages/cli/api/build/build.test.mjs
@@ -110,15 +110,6 @@ describe('build API', () => {
});
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 —
@@ -138,14 +129,18 @@ describe('build kit — coverage gates the pages group', () => {
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);
+ expect(r.data.pages.length).toBeGreaterThan(0);
+ for (const page of r.data.pages) {
+ expect(page).not.toHaveProperty('matchedTerms');
+ expect(page).not.toHaveProperty('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);
+ expect(r.data.pages.length).toBeGreaterThan(0);
});
});
diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjs
index 85f0c37fef..ee23d6da11 100644
--- a/packages/cli/api/build/kit/kit.mjs
+++ b/packages/cli/api/build/kit/kit.mjs
@@ -14,6 +14,7 @@
*/
import {search} from '../../search/search.mjs';
+import {getResultCoverage} from '../../search/coverage.mjs';
/** A page at/above this score is a confident direct match. */
const PAGE_DIRECT = 95;
@@ -88,13 +89,15 @@ export async function buildKit(query, options = {}) {
/**
* 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
+ * Single-concept queries have nothing to cover, so they always pass. Coverage
+ * stays in a module-private WeakMap and never enters public search/build JSON.
+ * @param {object} r
*/
const covers = r => {
- const total = r.queryTerms ?? 1;
+ const coverage = getResultCoverage(r);
+ const total = coverage?.total ?? 1;
if (total <= 1) return true;
- return (r.matchedTerms ?? 0) / total >= PAGE_COVERAGE;
+ return (coverage?.matched ?? 0) / total >= PAGE_COVERAGE;
};
const pages = results
@@ -137,7 +140,8 @@ export async function buildKit(query, options = {}) {
const hint =
pages.length + blocks.length + domain.length < THIN_KIT
? {
- reason: 'Few matches. This is keyword search, not semantic — try other wordings.',
+ reason:
+ 'Few matches. This is keyword search, not semantic — try other wordings.',
commands: ['component --list', 'template --list'],
}
: undefined;
diff --git a/packages/cli/api/search/coverage.mjs b/packages/cli/api/search/coverage.mjs
new file mode 100644
index 0000000000..40cc5f74cf
--- /dev/null
+++ b/packages/cli/api/search/coverage.mjs
@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Internal query-coverage bridge between search ranking and build kits.
+ * @input Scored result objects plus matched/total concept counts.
+ * @output Module-private metadata access that never changes public result JSON.
+ * @position Internal search/build plumbing; not exported from the package API.
+ */
+
+/** @type {WeakMap<object, {matched: number, total: number}>} */
+const coverageByResult = new WeakMap();
+
+/**
+ * @template {object} T
+ * @param {T} result
+ * @param {number} matched
+ * @param {number} total
+ * @returns {T}
+ */
+export function setResultCoverage(result, matched, total) {
+ coverageByResult.set(result, {matched, total});
+ return result;
+}
+
+/**
+ * @param {object} result
+ * @returns {{matched: number, total: number} | undefined}
+ */
+export function getResultCoverage(result) {
+ return coverageByResult.get(result);
+}
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index 3abdbfd8ce..8e7a8ec236 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -65,6 +65,7 @@ import {discoverTemplates, extractComponents} from '../template/template.mjs';
import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
import {AstryxError} from '../error.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {setResultCoverage} from './coverage.mjs';
/**
* A search candidate gathered from one content domain. Extra underscore-
@@ -724,39 +725,43 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
name: c.name,
score,
reason,
- matchedTerms,
- queryTerms,
description: c.description || '',
};
+ let result;
switch (c.domain) {
case 'component':
- return {
+ result = {
...base,
import: c._import,
command: `astryx component ${c.name}`,
};
+ break;
case 'hook':
- return {
+ result = {
...base,
import: c._import,
command: `astryx hook ${c.name}`,
};
+ break;
case 'doc':
- return {
+ result = {
...base,
title: c._title,
command: `astryx docs ${c.name}`,
};
+ break;
case 'template':
- return {
+ result = {
...base,
displayName: c._displayName,
kind: c._kind,
command: `astryx template ${c.name}`,
};
+ break;
default:
- return base;
+ result = base;
}
+ return setResultCoverage(result, matchedTerms, queryTerms);
}
/**
diff --git a/packages/cli/api/search/search.test.mjs b/packages/cli/api/search/search.test.mjs
index 9cd3a90736..4cc01f1491 100644
--- a/packages/cli/api/search/search.test.mjs
+++ b/packages/cli/api/search/search.test.mjs
@@ -44,6 +44,15 @@ describe('search leaf — envelope + ranking', () => {
expect(r.data.results.length).toBeGreaterThan(0);
}, SLOW);
+ it('keeps tokenizer coverage out of the public result shape', async () => {
+ const r = await search('table of contents', {cwd});
+ expect(r.data.results.length).toBeGreaterThan(0);
+ for (const result of r.data.results) {
+ expect(result).not.toHaveProperty('matchedTerms');
+ expect(result).not.toHaveProperty('queryTerms');
+ }
+ }, SLOW);
+
it('returns an empty result set (not an error) for a no-match query', async () => {
const r = await search('zzznomatch99', {cwd});
expect(r.type).toBe('search');
@@ -88,6 +97,17 @@ describe('search leaf — exact keyword phrase outranks incidental token matches
expect(r.data.results[0]?.name).toBe('Outline');
}, SLOW);
+ it('preserves query coverage metadata on the promoted exact phrase', () => {
+ const query = 'table of contents';
+ const tokens = tokenizeQuery(query);
+ expect(
+ scoreQuery(query, tokens, {
+ name: 'Outline',
+ keywords: [query],
+ }),
+ ).toMatchObject({matched: tokens.length, total: tokens.length});
+ });
+
it('still returns no results for a nonsense query (the fix does not loosen matching)', async () => {
const r = await search('zzzzqqqx', {cwd});
expect(r.data.results).toEqual([]);
diff --git a/packages/cli/api/search/search.type.mjs b/packages/cli/api/search/search.type.mjs
index 35ced726f9..4a07f5f056 100644
--- a/packages/cli/api/search/search.type.mjs
+++ b/packages/cli/api/search/search.type.mjs
@@ -20,8 +20,6 @@
* @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.