Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
fix(workspace): gate weak children on match strength, not lenient coverage ratio
Shrish Dwivediea4baf4bd996
diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex ed69dece..5eacba8c 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -66,6 +66,14 @@ export interface AskResult {* best result, i.e. the pack is probably noise for this prompt. Absent in* structural mode — a resolved "who calls X" is itself the relevance signal. */coverage?: number;+ /** Like {@link coverage}, but the top hit's idf-weighted matched share over+ * its NAME + PATH fields ONLY (body excluded) — a match-STRENGTH signal:+ * "did the query hit a high-value field, or only incidental body tokens?".+ * A body-only collision (a variable that happens to share a query word) has+ * `coverageStrong === 0` while `coverage` can still look respectable. Used by+ * workspace federation to gate a weak child out of the cross-repo ranking.+ * Absent in structural mode; same lexical-only contract as `coverage`. */+ coverageStrong?: number;/** Multi-scope lexical results only: which scopes federated into the fused* ranking, plus scopes that matched too weakly to federate (with their best* doc id). Drives formatAsk's `matched in:` / `also matched:` footer.@@ -437,6 +445,9 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea: conceptBags.length + symbolDocs.length;const dfltIdf = Math.log(1 + nDocs);const matchedOf = new Map<AskHit, number>();+ // Parallel to matchedOf, but over NAME+PATH only (body dropped) — the+ // match-strength signal exported as `coverageStrong`.+ const matchedStrongOf = new Map<AskHit, number>();// ── Concepts (prose nodes; not in the wiring graph) ──const conceptHits: AskHit[] = [];@@ -454,6 +465,7 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleascore: total,};matchedOf.set(hit, matchedIdfShare(q, [name, body], idf, dfltIdf));+ matchedStrongOf.set(hit, matchedIdfShare(q, [name], idf, dfltIdf)); // concepts have no path fieldconceptHits.push(hit);}}@@ -538,6 +550,7 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleaconst d = docsById.get(rd.id);const si = idfOf.get(rd.scope);matchedOf.set(hit, d && si ? matchedIdfShare(q, [d.name, d.path, d.body], si.idf, si.dflt) : 0);+ matchedStrongOf.set(hit, d && si ? matchedIdfShare(q, [d.name, d.path], si.idf, si.dflt) : 0);symbolHits.push(hit);}// Label + footer only when federation actually happened (or a scope was@@ -601,6 +614,7 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea};const d = docsById.get(id);matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);+ matchedStrongOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path], idf, dfltIdf) : 0);symbolHits.push(hit);}}@@ -618,6 +632,7 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleahits: scored.slice(0, limit),scopes: scopeMeta,coverage: scored.length && q.size > 0 ? matchedOf.get(scored[0]) ?? 0 : undefined,+ coverageStrong: scored.length && q.size > 0 ? matchedStrongOf.get(scored[0]) ?? 0 : undefined,// Zero hits on a genuinely multi-scope graph names the scopes that exist,// so a query that missed everywhere still tells the caller where to look.note: scored.lengthdiff --git a/src/graph/workspace.ts b/src/graph/workspace.tsindex 8980e01d..55e3843a 100644--- a/src/graph/workspace.ts+++ b/src/graph/workspace.ts@@ -34,7 +34,7 @@ import { edgeWalk, resolveSymbol, type Direction } from "./traverse.js";import { wiringPath } from "./write.js";import type { GraphV1 } from "./types.js";import { ask, type AskHit, type AskResult } from "../ask/ask.js";-import { fuseScopes, PARTICIPATION_RATIO, type ScopedDoc } from "../ask/fuse.js";+import { fuseScopes, type ScopedDoc } from "../ask/fuse.js";import { grepGraph, type GrepGroup, type GrepResult } from "../search/grep.js";import { formatGrepResult, zeroHitNote } from "../search/grep-cli.js";import { savingsFooter, type Savings } from "../context/savings.js";@@ -177,11 +177,28 @@ export interface FederateAskOptions {interface ChildRun {child: string;hits: AskHit[];- /** The child's top-hit idf-weighted matched share — a RAW, cross-child-- * comparable magnitude (NOT per-child normalized), used for the gate. */+ /** The child's top-hit idf-weighted matched share over name+path+body — a+ * RAW, cross-child-comparable magnitude (NOT per-child normalized). */coverage: number;+ /** Same, but over name+path ONLY (body dropped) — the match-STRENGTH signal.+ * A body-only incidental collision has `coverageStrong === 0`. */+ coverageStrong: number;}+/** A child federates if a query term hit a NAME/PATH field at all (any strength+ * ≥ this) — the primary gate. Well below every genuine fixture (≥0.45) yet+ * strictly above a body-only collision's 0, so a real partial-relevance hit on+ * a common/low-idf term is never overcorrected out. */+const STRONG_FLOOR = 0.1;+/** …OR the overall (name+path+body) coverage is broad enough to be real even+ * body-only. A single incidental body-token collision measures ~0.29 and RISES+ * with corpus size (0.30+ at 200 nodes) but never approaches this, while a+ * genuinely broad match clears it. This is why the gate is on absolute,+ * scale-invariant floors, NOT the prior 0.25×best ratio (which — calibrated for+ * raw-lexical-SCORE space — was far too lenient in coverage/matched-fraction+ * space and leaked junk, worsening as the corpus grew). */+const HIGH_FLOOR = 0.5;+/*** Federated `ask` across a workspace: run each child's own per-scope ask* pipeline, then fuse ALL the children's scope lists with the same@@ -236,21 +253,22 @@ export function federateAsk(continue; // corrupt child, or a sub-scope --in matching nothing here}if (r.hits.length === 0) continue;- runs.push({ child, hits: r.hits, coverage: r.coverage ?? 0 });+ runs.push({ child, hits: r.hits, coverage: r.coverage ?? 0, coverageStrong: r.coverageStrong ?? 0 });}- // Cross-child participation gate on RAW coverage: per-child scores are each- // normalized (top ~1.0 everywhere), which makes fuseScopes's own gate vacuous- // across repos. coverage (the top hit's idf-weighted matched share) is NOT- // per-child normalized and IS comparable across corpora, so a child below- // 0.25x the best is reported in alsoMatched, not fused — this keeps a junk- // body-token collision in one repo out of another repo's genuine ranking.- const bestCoverage = runs.reduce((m, r) => Math.max(m, r.coverage), 0);- const gate = PARTICIPATION_RATIO * bestCoverage;+ // Cross-child participation gate on match STRENGTH, not a lenient ratio.+ // Per-child hit scores are each per-child-normalized (top ~1.0 everywhere),+ // so feeding them to fuseScopes makes its gate vacuous across repos — a junk+ // body-token collision would federate beside another repo's genuine hits.+ // Gate: a child federates iff its top hit matched a query term in a NAME/PATH+ // field (coverageStrong ≥ STRONG_FLOOR — not just an incidental body token)+ // OR its overall coverage is broad enough to be real (≥ HIGH_FLOOR). A+ // body-only collision has coverageStrong 0 and coverage ~0.3 → gated to+ // alsoMatched. Both floors are absolute + scale-invariant (see their docs).const gatedOut: { scope: string; bestId: string }[] = [];const survivors: ChildRun[] = [];for (const run of runs) {- if (run.coverage >= gate) survivors.push(run);+ if (run.coverageStrong >= STRONG_FLOOR || run.coverage >= HIGH_FLOOR) survivors.push(run);else gatedOut.push({ scope: run.child, bestId: prefixPointer(run.child, run.hits[0].pointer) });}diff --git a/test/workspace.test.ts b/test/workspace.test.tsindex cff762bd..34b1247a 100644--- a/test/workspace.test.ts+++ b/test/workspace.test.ts@@ -46,6 +46,14 @@ const REPOS = {repoB: { "b.ts": "export function betaHandler() { return 2; }\n" },};+/** N unrelated functions, to pad a child's corpus to a realistic size so+ * coverage/idf reflect scale (junk coverage rises with corpus size). */+function pad(n: number): string {+ let s = "";+ for (let i = 0; i < n; i++) s += `export function pad${i}Widget() { const v${i} = ${i}; return v${i}; }\n`;+ return s;+}+test("isWorkspaceBuildRoot: ≥2 git children, no own .git → workspace", () => {const p = workspaceFx(REPOS);assert.equal(isWorkspaceBuildRoot(p), true);@@ -231,6 +239,52 @@ test("federated ask: --in <child> narrows to that child; --in <unknown> errors lrmSync(p, { recursive: true, force: true });});+for (const padN of [0, 200]) {+ test(`strength gate: body-only junk (\`position\`) gated out at ${padN ? "~200" : "~30"}-node scale`, async () => {+ const strongPad = padN ? { "pad.ts": pad(padN) } : {};+ const p = workspaceFx({+ repoStrong: { "m.ts": "export function scrollbarOverlay() { return computeThumb(); }\nfunction computeThumb() { return 1; }\n", ...strongPad },+ repoJunk: { "m.ts": "export function drawFrame() { const position = 0; return position; }\nfunction helper() { return 1; }\n", ...strongPad },+ });+ await buildWorkspace(p);+ const r = federateAsk(p, undefined, "scrollbar overlay position", { limit: 8 });+ const titles = r.hits.map((h) => h.title);+ assert.ok(titles.some((t) => t.startsWith("scrollbarOverlay")), "name-match child federates");+ assert.ok(!titles.some((t) => t.startsWith("drawFrame")), `body-only junk must NOT federate:\n${titles.join("\n")}`);+ assert.ok(r.hits.every((h) => h.scope!.startsWith("repoStrong")), "only the strong child federates");+ assert.deepEqual(r.scopes?.alsoMatched.map((m) => m.scope), ["repoJunk"], "junk reported in alsoMatched");+ rmSync(p, { recursive: true, force: true });+ });+}++test("strength gate: 3-child payment/gateway/refund — strong + mid federate, incidental-var junk gated out", async () => {+ const p = workspaceFx({+ repoStrong: { "m.ts": "export function paymentGatewayRefund() { return 1; }\n", "pad.ts": pad(25) },+ repoMid: { "m.ts": "export function refundPayment() { return 1; }\n", "pad.ts": pad(25) }, // partial name match+ repoJunk: { "m.ts": "export function renderList() { const gateway = 0; return gateway; }\n", "pad.ts": pad(25) },+ });+ await buildWorkspace(p);+ const r = federateAsk(p, undefined, "payment gateway refund", { limit: 8 });+ const scopes = new Set(r.hits.map((h) => h.scope!.split("/")[0]));+ assert.ok(scopes.has("repoStrong") && scopes.has("repoMid"), "genuine name matches federate");+ assert.ok(!scopes.has("repoJunk"), "incidental-var junk excluded from the ranking");+ assert.ok(r.scopes?.alsoMatched.some((m) => m.scope === "repoJunk"), "junk reported in alsoMatched");+ rmSync(p, { recursive: true, force: true });+});++test("strength gate: a legit COMMON-term (low-idf) name match is NOT overcorrected out", async () => {+ let cfg = "export function loadConfig() { return 1; }\n";+ for (let i = 0; i < 15; i++) cfg += `export function config${i}Reader() { return ${i}; }\n`; // "config" common → low idf+ const p = workspaceFx({+ repoConfig: { "m.ts": cfg, "pad.ts": pad(25) },+ repoOther: { "m.ts": "export function unrelatedThing() { return 0; }\n", "pad.ts": pad(25) },+ });+ await buildWorkspace(p);+ const r = federateAsk(p, undefined, "config loader", { limit: 8 });+ assert.ok(r.hits.some((h) => h.scope!.startsWith("repoConfig")), "real partial-relevance (low-idf name hit) must still federate");+ rmSync(p, { recursive: true, force: true });+});+test("readWorkspace: rejects foreign/invalid json as not-a-workspace", () => {const p = mkdtempSync(join(tmpdir(), "ws-"));mkdirSync(contextDirFor(p), { recursive: true });