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
feat(workspace): Fuse file candidates before span projection (#251)
Buseong Kimf6c411226fa0
diff --git a/src/graph/workspace.ts b/src/graph/workspace.tsindex 3a811327..d371586f 100644--- a/src/graph/workspace.ts+++ b/src/graph/workspace.ts@@ -37,8 +37,16 @@ import {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 { fileFirstRoundRobin } from "../ask/file-selection.js";+import {+ ask,+ type AskHit,+ type AskRankingMetadata,+ type AskResult,+} from "../ask/ask.js";+import {+ fileFirstRoundRobin,+ roundRobinQueues,+} from "../ask/file-selection.js";import { fuseScopes, STRONG_FLOOR, HIGH_FLOOR, type ScopedDoc } from "../ask/fuse.js";import { grepGraph, type GrepGroup, type GrepResult } from "../search/grep.js";import { formatGrepResult, zeroHitNote } from "../search/grep-cli.js";@@ -183,6 +191,8 @@ export interface FederateAskOptions {/** Narrow to one child (`repoA`) or a sub-scope within it (`repoA/backend`).* A prefix matching NO child throws, listing the repos. */in?: string;+ /** @internal File-level child RRF plus an exact workspace baseline top lock. */+ fileTopLock?: boolean;}interface ChildRun {@@ -194,6 +204,11 @@ interface ChildRun {/** Same, but over name+path ONLY (body dropped) — the match-STRENGTH signal.* A body-only incidental collision has `coverageStrong === 0`. */coverageStrong: number;+ /** Exact baseline top-hit coverage used only to compute the workspace top lock. */+ baselineCoverage: number;+ baselineCoverageStrong: number;+ /** Present only for the internal file-aware path. */+ ranking?: AskRankingMetadata;}// STRONG_FLOOR / HIGH_FLOOR (a child federates if its top hit matched a@@ -230,6 +245,7 @@ export function federateAsk(): AskResult {const wg = loadWorkspaceGraphs(root, override);const limit = opts.limit ?? 8;+ const fileTopLock = opts.fileTopLock ?? true;// `--in` scopes to a single child (and, past the first segment, a sub-scope// within it). A prefix naming no known child at all is a caller mistake.@@ -263,12 +279,24 @@ export function federateAsk(// The parent owns the final cross-repo ranking. Selecting inside each// child would be undone by fusion and could truncate a hybrid list.fileFirst: false,+ fileComplement: fileTopLock,+ includeRankingMetadata: fileTopLock,});} catch {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, coverageStrong: r.coverageStrong ?? 0 });+ const topGroup = r.ranking?.groups[0];+ runs.push({+ child,+ hits: r.hits,+ coverage: topGroup?.coverage ?? r.coverage ?? 0,+ coverageStrong: topGroup?.coverageStrong ?? r.coverageStrong ?? 0,+ baselineCoverage: r.ranking?.baselineCoverage ?? r.coverage ?? 0,+ baselineCoverageStrong:+ r.ranking?.baselineCoverageStrong ?? r.coverageStrong ?? 0,+ ranking: r.ranking,+ });}// Cross-child participation gate on match STRENGTH, not a lenient ratio.@@ -289,9 +317,197 @@ export function federateAsk(// every run (there is at most one) survives, matching a standalone child ask.const gatedOut: { scope: string; bestId: string }[] = [];const survivors: ChildRun[] = [];+ const baselineSurvivors: ChildRun[] = [];for (const run of runs) {- if (onlyChild || 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) });+ const baselineEligible =+ onlyChild ||+ run.baselineCoverageStrong >= STRONG_FLOOR ||+ run.baselineCoverage >= HIGH_FLOOR;+ const fileEligible =+ onlyChild ||+ run.coverageStrong >= STRONG_FLOOR ||+ run.coverage >= HIGH_FLOOR;+ if (baselineEligible) baselineSurvivors.push(run);+ // Distributed file evidence may admit a child, but the exact baseline+ // top lock must never resurrect a child that the final stream calls gated+ // out. The production survivor set is therefore the union of both gates;+ // baselineSurvivors remains the strict baseline subset used only to choose the+ // locked pointer.+ if (baselineEligible || fileEligible) survivors.push(run);+ else {+ const best = run.ranking?.groups[0]?.hits[0] ?? run.hits[0];+ gatedOut.push({ scope: run.child, bestId: prefixPointer(run.child, best.pointer) });+ }+ }++ if (fileTopLock) {+ type WorkspaceGroup = {+ key: string;+ child: string;+ hits: AskHit[];+ baselineHits: AskHit[];+ };+ const qualifyHit = (+ child: string,+ hit: AskHit,+ score = hit.score,+ scope = hit.scope ? `${child}/${hit.scope}` : child,+ ): AskHit => ({+ ...hit,+ score,+ scope,+ pointer: prefixPointer(child, hit.pointer),+ });+ const sameHit = (a: AskHit, b: AskHit): boolean =>+ a.kind === b.kind && a.pointer === b.pointer && a.title === b.title;++ // Baseline workspace stream: reproduce the all-span RRF exactly so the+ // final lock owns the same concrete pointer and fused score as the baseline.+ const baselineDocs: ScopedDoc[] = [];+ const baselineBack = new Map<+ string,+ { child: string; group: string; hit: AskHit }+ >();+ for (const run of baselineSurvivors) {+ const entries = run.ranking?.baseline ?? run.hits.map((hit, index) => ({+ group: `singleton:${index}`,+ hit,+ }));+ entries.forEach((entry, index) => {+ // Keep the legacy id shape so equal-score baseline ties remain exact.+ const id = `${run.child} ${index}`;+ const scope = entry.hit.scope+ ? `${run.child}/${entry.hit.scope}`+ : run.child;+ baselineDocs.push({ id, scope, score: entry.hit.score });+ baselineBack.set(id, {+ child: run.child,+ group: `${run.child}\0${entry.group}`,+ hit: entry.hit,+ });+ });+ }+ const baselineFused = fuseScopes(baselineDocs);+ const baselineTopRanked = baselineFused.ranked[0];+ const baselineTopBack = baselineTopRanked+ ? baselineBack.get(baselineTopRanked.id)+ : undefined;+ const baselineTop = baselineTopRanked && baselineTopBack+ ? qualifyHit(+ baselineTopBack.child,+ baselineTopBack.hit,+ baselineTopRanked.score,+ baselineTopRanked.scope,+ )+ : undefined;++ // File-aware workspace stream: exactly one leader per child/file (concepts stay+ // singleton groups) participates in RRF. Span queues remain in a side map+ // and cannot consume reciprocal-rank positions.+ const fileDocs: ScopedDoc[] = [];+ const fileBack = new Map<string, WorkspaceGroup>();+ for (const run of survivors) {+ const groups = run.ranking?.groups ?? run.hits.map((hit, index) => ({+ key: `singleton:${index}`,+ hits: [hit],+ baselineHits: [hit],+ coverage: 0,+ coverageStrong: 0,+ }));+ groups.forEach((group, index) => {+ const leader = group.hits[0];+ if (!leader) return;+ const id = `${run.child} file ${String(index).padStart(8, "0")}`;+ const scope = leader.scope ? `${run.child}/${leader.scope}` : run.child;+ const key = `${run.child}\0${group.key}`;+ fileDocs.push({ id, scope, score: leader.score });+ fileBack.set(id, {+ key,+ child: run.child,+ hits: group.hits,+ baselineHits: group.baselineHits ?? [leader],+ });+ });+ }+ const fileFused = fuseScopes(fileDocs);+ const rankedGroups: WorkspaceGroup[] = fileFused.ranked.flatMap((ranked) => {+ const group = fileBack.get(ranked.id);+ if (!group) return [];+ return [{+ ...group,+ // These spans are projections of one cross-child file document. Keep+ // their public score on that same RRF scale; child-local tail scores are+ // not comparable after workspace fusion and downstream re-sorting would+ // otherwise silently undo the file ordering.+ hits: group.hits.map((hit) =>+ qualifyHit(+ group.child,+ hit,+ ranked.score,+ hit.scope ? `${group.child}/${hit.scope}` : group.child,+ ),+ ),+ baselineHits: group.baselineHits.map((hit) => qualifyHit(group.child, hit)),+ }];+ });++ let projectedGroups = rankedGroups;+ if (baselineTop && baselineTopBack) {+ const key = baselineTopBack.group;+ const existing = rankedGroups.find((group) => group.key === key);+ const baselineQueue = existing?.baselineHits ?? [baselineTop];+ const projectedScore = existing?.hits[0]?.score ?? baselineTop.score;+ const locked: WorkspaceGroup = existing+ ? {+ ...existing,+ hits: [+ baselineTop,+ ...baselineQueue+ .filter((hit) => !sameHit(hit, baselineTop))+ .map((hit) => ({ ...hit, score: projectedScore })),+ ],+ }+ : {+ key,+ child: baselineTopBack.child,+ hits: [baselineTop],+ baselineHits: [baselineTop],+ };+ projectedGroups = [+ locked,+ ...rankedGroups.filter((group) => group.key !== key),+ ];+ }++ const hits = roundRobinQueues(+ projectedGroups.map((group) => group.hits),+ limit,+ );+ const unmatched = [...fileFused.alsoMatched, ...gatedOut];+ const note = coverageNote(wg);+ const result: AskResult = {+ query,+ mode: hits.length ? "lexical" : "empty",+ hits,+ };+ if (hits.length) {+ const lockedScope = baselineTop?.scope;+ const federated = [+ ...new Set([+ ...(lockedScope ? [lockedScope] : []),+ ...fileFused.federated,+ ]),+ ];+ const federatedSet = new Set(federated);+ result.scopes = {+ federated,+ alsoMatched: unmatched.filter((match) => !federatedSet.has(match.scope)),+ };+ } else {+ result.note = `no matching nodes across ${wg.loaded.length} workspace repo(s) — try different words, or \`graft build\` at a child`;+ }+ if (note) result.note = result.note ? `${result.note}\n${note}` : note;+ return result;}// Fuse the survivors' scope lists (within-child fusion is left untouched —diff --git a/test/workspace.test.ts b/test/workspace.test.tsindex 3f71db21..89430bb5 100644--- a/test/workspace.test.ts+++ b/test/workspace.test.ts@@ -127,7 +127,11 @@ test("workspace ask applies file-first selection after cross-repo fusion", async});try {await buildWorkspace(p);- const r = federateAsk(p, undefined, "quartz", { limit: 8, graphRank: false });+ const r = federateAsk(p, undefined, "quartz", {+ limit: 8,+ graphRank: false,+ fileTopLock: false,+ });const files = r.hits.map((hit) => hit.pointer.replace(/:L\d+-L\d+$/, ""));const firstPass = [...new Set(files)];@@ -144,6 +148,154 @@ test("workspace ask applies file-first selection after cross-repo fusion", async}});+test("default file-aware fusion locks the exact workspace top before projecting span queues", async () => {+ const p = workspaceFx({+ repoA: {+ "a.ts":+ `export function quartzAlphaA() { return "quartz"; }\n` ++ `export function quartzBetaA() { return "quartz"; }\n` ++ `export function quartzGammaA() { return "quartz"; }\n`,+ "b.ts": `export function quartzOmegaB() { return "quartz"; }\n`,+ },+ repoB: {+ "a.ts":+ `export function quartzAlphaC() { return "quartz"; }\n` ++ `export function quartzBetaC() { return "quartz"; }\n`,+ "d.ts": `export function quartzOmegaD() { return "quartz"; }\n`,+ },+ });+ try {+ await buildWorkspace(p);+ const baseline = federateAsk(p, undefined, "quartz", {+ limit: 8,+ graphRank: false,+ fileTopLock: false,+ });+ const a5 = federateAsk(p, undefined, "quartz", {+ limit: 8,+ graphRank: false,+ source: true,+ });+ const explicitA5 = federateAsk(p, undefined, "quartz", {+ limit: 8,+ graphRank: false,+ source: true,+ fileTopLock: true,+ });++ assert.deepEqual(+ a5,+ explicitA5,+ "the workspace default route is exactly the explicit file-aware configuration",+ );++ assert.deepEqual(+ {+ kind: a5.hits[0].kind,+ title: a5.hits[0].title,+ pointer: a5.hits[0].pointer,+ score: a5.hits[0].score,+ scope: a5.hits[0].scope,+ },+ {+ kind: baseline.hits[0].kind,+ title: baseline.hits[0].title,+ pointer: baseline.hits[0].pointer,+ score: baseline.hits[0].score,+ scope: baseline.hits[0].scope,+ },+ "the parent lock reproduces the exact pre-file-RRF workspace top",+ );++ const files = a5.hits.map((hit) => hit.pointer.replace(/:L\d+-L\d+$/, ""));+ const firstDuplicate = files.findIndex(+ (file, index) => files.indexOf(file) !== index,+ );+ assert.equal(firstDuplicate, 4, "all four child/file documents emit before a tail span");+ assert.equal(new Set(files.slice(0, firstDuplicate)).size, 4);+ assert.ok(files.includes("repoA/a.ts"));+ assert.ok(files.includes("repoB/a.ts"), "same relative paths in different children remain distinct");+ assert.ok(files.slice(firstDuplicate).includes("repoA/a.ts"));+ assert.ok(files.slice(firstDuplicate).includes("repoB/a.ts"));+ const repoBTailScores = a5.hits+ .filter((hit) => hit.pointer.replace(/:L\d+-L\d+$/, "") === "repoB/a.ts")+ .map((hit) => hit.score);+ assert.ok(repoBTailScores.length > 1, "fixture reaches a non-locked queue tail");+ assert.equal(+ new Set(repoBTailScores).size,+ 1,+ "every projected span in a non-locked file keeps the same cross-child RRF score",+ );+ const federated = new Set(a5.scopes?.federated ?? []);+ assert.ok(+ a5.scopes?.alsoMatched.every((match) => !federated.has(match.scope)),+ "a locked or otherwise federated scope is never also reported as gated out",+ );+ assert.ok(+ a5.hits.filter((hit) => hit.kind === "symbol").every((hit) => hit.code?.includes("function")),+ "source mode inlines both file leaders and queue tails",+ );+ } finally {+ rmSync(p, { recursive: true, force: true });+ }+});++test("file-union admission preserves the workspace baseline top-lock survivor set", async () => {+ const p = workspaceFx({+ repoStrong: {+ "strong.ts": `export function alphaBetaGamma() { return "alpha beta gamma"; }\n`,+ },+ repoDistributed: {+ "distributed.ts":+ `export function neutralOne() { return "alpha"; }\n` ++ `export function neutralTwo() { return "beta"; }\n` ++ `export function neutralThree() { return "gamma"; }\n`,+ },+ });+ try {+ await buildWorkspace(p);+ const baseline = federateAsk(p, undefined, "alpha beta gamma", {+ limit: 8,+ graphRank: false,+ fileTopLock: false,+ });+ assert.ok(baseline.hits.every((hit) => hit.scope?.startsWith("repoStrong")));+ assert.ok(baseline.scopes?.alsoMatched.some((match) => match.scope === "repoDistributed"));++ const a5 = federateAsk(p, undefined, "alpha beta gamma", {+ limit: 8,+ graphRank: false,+ });+ assert.deepEqual(+ {+ title: a5.hits[0].title,+ pointer: a5.hits[0].pointer,+ score: a5.hits[0].score,+ scope: a5.hits[0].scope,+ },+ {+ title: baseline.hits[0].title,+ pointer: baseline.hits[0].pointer,+ score: baseline.hits[0].score,+ scope: baseline.hits[0].scope,+ },+ "the lock is computed from the original baseline participation gate",+ );+ assert.ok(+ a5.hits.some((hit) => hit.scope?.startsWith("repoDistributed")),+ "file union may admit a newly coherent child into ranks below the lock",+ );+ assert.ok(!a5.scopes?.alsoMatched.some((match) => match.scope === "repoDistributed"));+ const excluded = new Set(a5.scopes?.alsoMatched.map((match) => match.scope) ?? []);+ assert.ok(+ a5.hits.every((hit) => !excluded.has(hit.scope?.split("/")[0] ?? "")),+ "the baseline top lock never resurrects a child reported as gated out",+ );+ } finally {+ rmSync(p, { recursive: true, force: true });+ }+});+test("ask inside a single child = standalone (no federation scopes)", async () => {const p = workspaceFx(REPOS);await buildWorkspace(p);@@ -250,6 +402,17 @@ test("federated ask: a junk-body-token child is gated out of the ranking, into aassert.ok(!titles.some((t) => t.startsWith("renderPanel")), `junk hit must NOT federate:\n${titles.join("\n")}`);assert.ok(r.hits.every((h) => h.scope!.startsWith("repoA")), "only repoA federates");assert.deepEqual(r.scopes?.alsoMatched.map((m) => m.scope), ["repoB"], "junk child reported in alsoMatched");+ const a5 = federateAsk(p, undefined, "invoice total tax breakdown", {+ limit: 8,+ fileTopLock: true,+ });+ assert.ok(a5.hits.some((hit) => hit.title.startsWith("invoiceTotalTaxBreakdown")));+ assert.ok(!a5.hits.some((hit) => hit.title.startsWith("renderPanel")));+ assert.deepEqual(+ a5.scopes?.alsoMatched.map((match) => match.scope),+ ["repoB"],+ "file-aware ranking gates on fresh top-file coverage instead of stale metadata",+ );rmSync(p, { recursive: true, force: true });});