Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

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.ts
index 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: boolea
score: total,
};
matchedOf.set(hit, matchedIdfShare(q, [name, body], idf, dfltIdf));
+ matchedStrongOf.set(hit, matchedIdfShare(q, [name], idf, dfltIdf)); // concepts have no path field
conceptHits.push(hit);
}
}
@@ -538,6 +550,7 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea
const 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: boolea
hits: 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.length
diff --git a/src/graph/workspace.ts b/src/graph/workspace.ts
index 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.ts
index 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 l
rmSync(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 });