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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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 matchesexpect(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.mjsindex 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.