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
perf(context): synthesize concept batches in parallel, and cut them on path hashes (#521)
Alex Matthewsff56c78ec2f1
diff --git a/src/cli.ts b/src/cli.tsindex 7c093eeb..5c82ed36 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -445,6 +445,11 @@ grouped(program.command("build"), GROUP.setup).option("--deep", "run the LLM pass: concept nodes (graft/*.md) + per-symbol summary/crux").option("-e, --extensions <exts...>", 'code extensions to include (e.g. ".ts" ".py"); an extension with no parser is ignored with a warning that lists the supported set').option("-j, --concurrency <n>", "files summarized in parallel during --deep (default 5)")+ .option(+ "--synth-concurrency <n>",+ "concept synthesis batches in flight at once during --deep (default 4). Separate from -j: " ++ "each synthesis call carries a whole batch of summaries, not one file",+ ).option("--no-reuse", "re-parse every file instead of replaying unchanged ones from the extraction cache").option("--lsp", "add compiler-grade call edges via a language server if one is installed (opt-in, slower; e.g. rust-analyzer, clangd)").option("--allow-partial", "with --deep: exit 0 even when some files' summaries failed (default: a degraded meaning tier exits 1)")@@ -493,6 +498,7 @@ grouped(program.command("build"), GROUP.setup)reuse?: boolean;lsp?: boolean;allowPartial?: boolean;+ synthConcurrency?: string;includeDir?: string[];onlyDir?: string[];followSubmodules?: boolean;@@ -517,6 +523,11 @@ grouped(program.command("build"), GROUP.setup)console.error(`✗ --concurrency must be a number, got "${opts.concurrency}"`);process.exit(1);}+ const synthConcurrency = opts.synthConcurrency ? Math.max(1, Number(opts.synthConcurrency)) : undefined;+ if (opts.synthConcurrency && !Number.isFinite(synthConcurrency)) {+ console.error(`✗ --synth-concurrency must be a number, got "${opts.synthConcurrency}"`);+ process.exit(1);+ }warnUnsupportedExtensions(opts.extensions);// Persisted BEFORE the build itself runs, so this invocation's walks (and// every later no-flag build / hooks refresh) see it identically — the@@ -600,6 +611,7 @@ grouped(program.command("build"), GROUP.setup)deep: !!deep,extensions: opts.extensions,concurrency,+ synthConcurrency,childConfig: cliConfig(),override: buildGlobalDir,includeDirs: opts.includeDir,@@ -617,6 +629,7 @@ grouped(program.command("build"), GROUP.setup)const c = await engine.init(dir, {extensions: opts.extensions,onlyDirs,+ synthConcurrency,onProgress: ({ phase, index, total, file }) =>process.stderr.write(`\r${phase === "summarize" ? "reading" : "writing"} concepts ${index + 1}/${total}: ${file.slice(0, 40).padEnd(40)}`,diff --git a/src/context/batches.ts b/src/context/batches.tsnew file mode 100644index 00000000..c4dd1075--- /dev/null+++ b/src/context/batches.ts@@ -0,0 +1,145 @@+/**+ * How the concept pass cuts its synthesis batches, and what each one is cached under.+ *+ * Every batch is one LLM call, and its result is cached under a key derived from the+ * files the call saw. So a boundary that moves is a re-synthesis — a metered call the+ * user pays for again — which makes the cut rule, not the call itself, the thing that+ * decides what a `--deep` build costs after an edit.+ *+ * The cut is a function of the file PATHS: a batch ends at the first file whose own+ * path hash matches a mask, never at a size. Cut by running size, one summary growing+ * by a sentence moves every later boundary, every later batch lands on a different set+ * of files, and so every later key changes and the next build re-synthesizes most of+ * the graph. Sizes are consulted in exactly two places, neither of which is a+ * boundary: the stride (how many files to expect per batch) and a batch that+ * overshoots the budget anyway, which is cut inside itself.+ */+import { contentHash } from "../util/id.js";+import type { FileSummary } from "../ai/synthesize.js";++/** Char budget of summary text per synthesis call (keeps each call in-context). */+export const BATCH_CHAR_BUDGET = 48_000;++/**+ * Smallest share of the stride a batch may be cut at: a mask hit sooner than this is+ * ignored, so a lucky pair of adjacent paths cannot turn a repo into one call per two+ * files. An eighth keeps a stray hit to one small batch in a long tail of them,+ * without moving a well-behaved boundary at all.+ */+const BATCH_MIN_SHARE = 1 / 8;++/** One synthesis call: the batch of summaries it sees, and the key it is cached under. */+export interface SynthesisBatch {+ files: FileSummary[];+ /** Stable key for this batch: its files and their content hashes. */+ key: string;+}++/**+ * The batches phase 2 calls, in the order the merge consumes them. `summaries` is+ * expected path-sorted, which is what makes the plan reproducible.+ *+ * Exported together with their cache keys because those keys are the phase's whole+ * cost model: a boundary that moves is a re-synthesis. How these keys survive an edit+ * is what the batching tests pin down.+ */+export function planSynthesis(summaries: FileSummary[], hashByPath: ReadonlyMap<string, string>): SynthesisBatch[] {+ return batchSummaries(summaries).map((files) => ({ files, key: batchKey(files, hashByPath) }));+}++/**+ * Cut the per-file summaries into batches, each under `budget` unless it is a single+ * file too big for one.+ *+ * A batch ENDS at the first file whose own path hash matches a mask, past a small+ * floor (see {@link BATCH_MIN_SHARE}) — so the end of a batch is decided by the files+ * inside it and by nothing else, and an edit to one file cannot move a boundary it is+ * not part of.+ */+export function batchSummaries(files: FileSummary[], budget: number = BATCH_CHAR_BUDGET): FileSummary[][] {+ if (files.length === 0) return [];+ const stride = filesPerBatch(files, budget);+ const minFiles = Math.max(1, Math.round(stride * BATCH_MIN_SHARE));+ const batches: FileSummary[][] = [];+ let cur: FileSummary[] = [];+ let size = 0;+ for (const f of files) {+ cur.push(f);+ size += summaryChars(f);+ if (cur.length >= minFiles && isBoundary(f.path, stride)) {+ batches.push(...withinBudget(cur, size, budget));+ cur = [];+ size = 0;+ }+ }+ if (cur.length > 0) batches.push(...withinBudget(cur, size, budget));+ return batches;+}++/** Chars a file costs its batch: its label, its summary, and the blank line the+ * synthesizer's prompt puts between entries. */+function summaryChars(f: FileSummary): number {+ return f.path.length + f.summary.length + 8;+}++/**+ * Files to aim for per batch: as many as fit in roughly one budget's worth of summary+ * text, rounded DOWN to a power of two.+ *+ * The mean is the one statistic that can size a batch across repos whose summaries+ * differ in length by an order of magnitude. The power of two is what makes it safe+ * to derive from a number that moves: editing one summary of n shifts the mean by+ * ~1/n, and the ladder is wide enough that a shift that small cannot re-stride —+ * while re-striding is the one change that does move every boundary, so it should+ * take a real change in the repo to happen.+ */+function filesPerBatch(files: FileSummary[], budget: number): number {+ const total = files.reduce((n, f) => n + summaryChars(f), 0);+ const mean = Math.max(1, Math.round(total / files.length));+ return 2 ** Math.floor(Math.log2(Math.max(1, Math.floor(budget / mean))));+}++/** Does a batch end here? One path in `stride` does, by its own hash. */+function isBoundary(path: string, stride: number): boolean {+ if (stride <= 1) return true;+ return parseInt(contentHash(path).slice(-8), 16) % stride === 0;+}++/** A batch that outgrew the budget on its own is cut by size, greedily. Overshooting+ * takes a longer gap between two mask hits than the stride asks for, so it is the+ * tail rather than the rule — and it is cut inside that one batch, which is why a+ * split is a local edit and not a re-plan. A single file over the budget is left+ * whole: the synthesizer truncates its input either way, and half a file is not a+ * batch. */+function withinBudget(batch: FileSummary[], size: number, budget: number): FileSummary[][] {+ return size <= budget || batch.length < 2 ? [batch] : batchBySize(batch, budget);+}++/** Greedily pack file summaries into batches under a char budget (≥1 file each). */+function batchBySize(files: FileSummary[], budget: number): FileSummary[][] {+ const batches: FileSummary[][] = [];+ let cur: FileSummary[] = [];+ let size = 0;+ for (const f of files) {+ const len = summaryChars(f);+ if (cur.length > 0 && size + len > budget) {+ batches.push(cur);+ cur = [];+ size = 0;+ }+ cur.push(f);+ size += len;+ }+ if (cur.length > 0) batches.push(cur);+ return batches;+}++/** Stable key for a batch: its files and their content hashes. */+function batchKey(batch: FileSummary[], hashByPath: ReadonlyMap<string, string>): string {+ return contentHash(+ batch+ .map((f) => `${f.path}:${hashByPath.get(f.path) ?? ""}`)+ .sort()+ .join("\n"),+ );+}diff --git a/src/context/build.ts b/src/context/build.tsindex 957289c5..779bb856 100644--- a/src/context/build.ts+++ b/src/context/build.ts@@ -6,7 +6,9 @@* 2. Summarize each file to prose (one LLM call per file, cached by content hash).* 3. Synthesize a CURATED node set from the labeled summaries (the synthesizer* decides granularity: subsystems, notable files, and concepts). This is- * one LLM call per batch of summaries; batches are cached by content.+ * one LLM call per batch of summaries; the batches are independent, so they+ * run concurrently, and each is cached by content. Where the batches are cut,+ * and why that decides what the next build costs, is `./batches.ts`.* 4. Resolve node names → slugs and links → edges; attribute each node to its* source files so staleness stays exact.* 5. Write one markdown file per node (preserving human notes) + a manifest.@@ -23,6 +25,7 @@ import { readFollowNestedRepos, readFollowSubmodules, readIncludeDirs } from "..import type { Summarizer } from "../ai/summarize.js";import { LlmFailureGate } from "../ai/failure.js";import type { FileSummary, SynthNode, Synthesizer } from "../ai/synthesize.js";+import { planSynthesis, type SynthesisBatch } from "./batches.js";import {CACHE_DIR,MANIFEST_VERSION,@@ -47,8 +50,13 @@ export const CODE_EXTENSIONS = [".cs", ".swift", ".sql", ".sh", ".proto",];-/** Char budget of summary text per synthesis call (keeps each call in-context). */-const BATCH_CHAR_BUDGET = 48_000;+/**+ * Synthesis calls in flight at once. Small on purpose, and separate from phase 1's+ * `-j`: there each call is one small file summary, here each is a whole batch of+ * summaries — a long, expensive request, of which a big repo has a handful rather+ * than hundreds.+ */+const DEFAULT_SYNTH_CONCURRENCY = 4;export interface BuildProgress {phase: "summarize" | "synthesize" | "write";@@ -72,6 +80,9 @@ export interface BuildOptions {synthesizer: Synthesizer;/** Files summarized in parallel during phase 1. Default 8. Raised via `graft build -j`. */concurrency?: number;+ /** Synthesis batches synthesized in parallel during phase 2. Default+ * {@link DEFAULT_SYNTH_CONCURRENCY}. Raised via `graft build --synth-concurrency`. */+ synthConcurrency?: number;onProgress?: (info: BuildProgress) => void;}@@ -85,10 +96,12 @@ export interface BuildResult {links: number;errors: string[];/** Files whose summary call failed, and files never attempted once the pass gave- * up — reported as data so the CLI can exit non-zero without reading messages (#127). */+ * up — reported as data so the CLI can exit non-zero without reading messages (#127).+ * A unit is a file in phase 1 and a whole batch of them in phase 2, and the+ * counts cover both: the failure gate is shared. */failedFiles: number;skippedFiles: number;- /** Why the summarize phase stopped early, when it did. */+ /** Why the LLM passes stopped early, when they did. */fatal?: string;}@@ -143,6 +156,14 @@ interface NodeDraft {links: Map<string, NodeLink>; // "to|relation" → link}+/** What one synthesis batch ended up contributing, for the per-batch log line. */+interface BatchOutcome {+ nodes: SynthNode[];+ /** Served from the cache, so no call was made for it. */+ cached: boolean;+ state: "ok" | "failed" | "skipped";+}+export async function buildContext(dir: string, opts: BuildOptions): Promise<BuildResult> {const root = resolve(dir);const outDir = contextDirFor(root, opts.contextDir);@@ -241,35 +262,86 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui.filter((w): w is FileWork & { summary: string } => Boolean(w.summary)).map((w) => ({ path: w.rel, summary: w.summary })).sort((a, b) => a.path.localeCompare(b.path));- const batches = batchBySize(summarized, BATCH_CHAR_BUDGET);+ const batches = planSynthesis(summarized, hashByPath);result.batches = batches.length;- const synthNodes: SynthNode[] = [];- for (let b = 0; b < batches.length; b++) {- opts.onProgress?.({ phase: "synthesize", index: b, total: batches.length, file: `batch ${b + 1}` });- const key = batchKey(batches[b], hashByPath);- let nodes = cache.synth[key];+ /**+ * One batch's synthesis, cached and failure-gated exactly as phase 1 is: a cache+ * hit is served even once the gate has closed (it costs nothing), only the call+ * is skipped.+ */+ async function synthesizeBatch(batch: SynthesisBatch, b: number): Promise<BatchOutcome> {+ let nodes = cache.synth[batch.key];// An empty array is a miss, not a hit: caching [] made a silent empty// synthesis permanent, the same trap #177 closed for the meaning pass (#129).- const cached = Array.isArray(nodes) && nodes.length > 0;- if (!cached) {- nodes = await opts.synthesizer.synthesize(batches[b]);- if (nodes.length > 0) cache.synth[key] = nodes;- else delete cache.synth[key];+ if (Array.isArray(nodes) && nodes.length > 0) return { nodes, cached: true, state: "ok" };+ if (gate.stopped) {+ gate.skip();+ return { nodes: [], cached: false, state: "skipped" };}- const links = nodes.reduce((n, node) => n + node.links.length, 0);- console.error(- ` synthesis batch ${b + 1}/${batches.length}: ${nodes.length} nodes, ${links} links${cached ? " (cached)" : ""}`,- );- synthNodes.push(...nodes);+ try {+ nodes = await opts.synthesizer.synthesize(batch.files);+ } catch (err) {+ // Recorded, not thrown. A provider that has stopped serving fails every+ // batch the same way, so the gate turns the first of those into a loud+ // fatal and the rest into skipped calls, and the CLI already reports a+ // concept pass with errors as a degraded meaning tier. Rethrowing instead+ // would write no graph at all and leave the synthesis cache unsaved, so the+ // next run would re-synthesize every batch that did work.+ const message = errMsg(err);+ result.errors.push(`synthesis batch ${b + 1}/${batches.length}: ${message}`);+ gate.record(message);+ return { nodes: [], cached: false, state: "failed" };+ }+ if (nodes.length > 0) cache.synth[batch.key] = nodes;+ else delete cache.synth[batch.key];+ gate.succeeded();+ return { nodes, cached: false, state: "ok" };}++ // A batch is an independent unit of work — its call sees only its own summaries,+ // and nothing is merged until every call is in (phase 3) — so the batches run+ // concurrently, the way phase 1's per-file calls already do. The slow part is+ // the round-trip, and a big repo otherwise serializes every one of them.+ //+ // Results are collected in BATCH order, whatever order the calls finish in.+ // That is what makes this safe: the merge below is order-sensitive (first name+ // registered wins, longest summary wins), so consuming batches as they completed+ // would make the graph a function of network timing, and two builds of the same+ // repo could disagree.+ let synthesized = 0;+ const outcomes = await mapWithConcurrency(batches, Math.max(1, opts.synthConcurrency ?? DEFAULT_SYNTH_CONCURRENCY), async (batch, b): Promise<BatchOutcome> => {+ const outcome = await synthesizeBatch(batch, b);+ // Reported on completion, like the crux pass (`graph/enrich.ts`): with several+ // calls in flight the next batch is not the one that is running, so `index`+ // counts finished batches and `file` names the one that just landed. The CLI+ // prints them as one overwritten line, which only reads as progress if the+ // counter never goes backwards.+ opts.onProgress?.({ phase: "synthesize", index: synthesized++, total: batches.length, file: `batch ${b + 1}` });+ return outcome;+ });++ // One log line per batch, in batch order: printed as the calls land it would+ // report which call was fastest, which is noise on a run whose output does not+ // depend on how the calls interleaved.+ const synthNodes: SynthNode[] = [];+ for (const [b, out] of outcomes.entries()) {+ const links = out.nodes.reduce((n, node) => n + node.links.length, 0);+ const note = out.cached ? " (cached)" : out.state === "failed" ? " (failed)" : out.state === "skipped" ? " (skipped)" : "";+ console.error(` synthesis batch ${b + 1}/${batches.length}: ${out.nodes.length} nodes, ${links} links${note}`);+ synthNodes.push(...out.nodes);+ }+ // The gate is shared with phase 1, so these counts now cover both LLM passes.+ result.failedFiles = gate.failed;+ result.skippedFiles = gate.skipped;+ result.fatal = gate.fatal;+// Drop cache entries for batches we no longer produce, so it can't grow forever.// Skip empty arrays so a failed batch is retried on the next --deep, not frozen.cache.synth = Object.fromEntries(- batches.flatMap((batch) => {- const k = batchKey(batch, hashByPath);- const v = cache.synth[k];- return v && v.length > 0 ? [[k, v] as [string, SynthNode[]]] : [];+ batches.flatMap(({ key }) => {+ const v = cache.synth[key];+ return v && v.length > 0 ? [[key, v] as [string, SynthNode[]]] : [];}),);saveCache(outDir, cache);@@ -373,35 +445,6 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Buireturn result;}-/** Greedily pack file summaries into batches under a char budget (≥1 file each). */-function batchBySize(files: FileSummary[], budget: number): FileSummary[][] {- const batches: FileSummary[][] = [];- let cur: FileSummary[] = [];- let size = 0;- for (const f of files) {- const len = f.path.length + f.summary.length + 8;- if (cur.length > 0 && size + len > budget) {- batches.push(cur);- cur = [];- size = 0;- }- cur.push(f);- size += len;- }- if (cur.length > 0) batches.push(cur);- return batches;-}--/** Stable key for a batch: its files and their content hashes. */-function batchKey(batch: FileSummary[], hashByPath: Map<string, string>): string {- return contentHash(- batch- .map((f) => `${f.path}:${hashByPath.get(f.path) ?? ""}`)- .sort()- .join("\n"),- );-}-function registerName(table: Map<string, string>, name: string, slug: string): void {const key = name.trim().toLowerCase();if (key && !table.has(key)) table.set(key, slug);diff --git a/src/engine.ts b/src/engine.tsindex 01216cf8..74270a12 100644--- a/src/engine.ts+++ b/src/engine.ts@@ -31,6 +31,8 @@ export interface InitOptions {extensions?: string[];/** Repo-relative directory prefixes to limit the concept pass (`--only-dir`). */onlyDirs?: string[];+ /** Max concept synthesis batches in flight at once. Default 4. */+ synthConcurrency?: number;/** Progress callback for long builds. */onProgress?: (info: BuildProgress) => void;}@@ -66,6 +68,7 @@ export class Graft {contextDir: this.cfg.contextDir,extensions: opts.extensions,onlyDirs: opts.onlyDirs,+ synthConcurrency: opts.synthConcurrency,model: this.modelLabel(),summarizer: this.summarizer(),synthesizer: this.synthesizer(),diff --git a/src/graph/workspace-cli.ts b/src/graph/workspace-cli.tsindex 09755639..f428fe6c 100644--- a/src/graph/workspace-cli.ts+++ b/src/graph/workspace-cli.ts@@ -29,6 +29,8 @@ export interface WorkspaceBuildOptions {deep: boolean;extensions?: string[];concurrency?: number;+ /** Max concept synthesis batches in flight per child (default 4). */+ synthConcurrency?: number;/** Provider/model/key config for child builds — WITHOUT any contextDir* override, so each child writes to its own `<child>/graft/`. */childConfig: EngineConfig;@@ -70,7 +72,7 @@ export async function runWorkspaceBuild(root: string, opts: WorkspaceBuildOptionpatchBuildConfig(childDir, childConfigPatch);}const engine = new Graft({ ...opts.childConfig, contextDir: undefined });- if (opts.deep) await engine.init(childDir, { extensions: opts.extensions });+ if (opts.deep) await engine.init(childDir, { extensions: opts.extensions, synthConcurrency: opts.synthConcurrency });const g = await engine.graph(childDir, { llm: opts.deep, concurrency: opts.concurrency });console.log(`✓ ${childName}/: ${g.nodes} nodes, ${g.edges} edges, ${g.cards} cards [${g.languages.join(", ")}]`);for (const e of g.errors) console.error(`✗ ${childName}/: ${e}`);diff --git a/test/context-batch-stability.test.ts b/test/context-batch-stability.test.tsnew file mode 100644index 00000000..87239f9f--- /dev/null+++ b/test/context-batch-stability.test.ts@@ -0,0 +1,215 @@+/**+ * Where the concept pass cuts its synthesis batches, and what that costs+ * (`src/context/batches.ts`).+ *+ * Every batch is cached under a key derived from the files it holds, so a boundary+ * that moves is a re-synthesis — a metered LLM call the user pays for again. Cut by+ * running size (which is what this replaces) one summary growing by a few hundred+ * characters moved every later boundary, so the next build after any edit+ * re-synthesized most of the graph. These tests pin the property that replaced it:+ * the plan is a function of the file PATHS, so only the batches around a change can+ * move.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { buildContext } from "../src/context/build.js";+import { BATCH_CHAR_BUDGET, planSynthesis, type SynthesisBatch } from "../src/context/batches.js";+import { contentHash } from "../src/util/id.js";+import { tmpRepo, PassthroughSummarizer } from "./helpers.js";+import type { FileSummary, Synthesizer } from "../src/index.js";++const FILES = 200;+/** Summary length per file. ~2k is what a real per-file summary runs to, and it+ * puts the stride at 16 files, so a 200-file repo is a dozen-odd batches. */+const SUMMARY_CHARS = 2000;+/** How much one edited file's summary changes by. Deliberately MORE than one file's+ * summary: under a size-driven cut, a change smaller than that cannot move a+ * boundary at all, and a test that cannot tell the two rules apart is not a guard+ * against the regression. */+const EDIT_CHARS = SUMMARY_CHARS + 2500;++function fileBody(i: number, chars = SUMMARY_CHARS): string {+ return `export const v${i} = ${i};\n// ${"x".repeat(chars)}\n`;+}++/** A repo of numbered files, so the path-sorted order is the numeric order. */+function makeRepo(tag: string, count = FILES): string {+ const dir = tmpRepo(tag);+ mkdirSync(join(dir, "src"), { recursive: true });+ for (let i = 0; i < count; i++) {+ writeFileSync(join(dir, "src", `mod-${String(i).padStart(3, "0")}.ts`), fileBody(i));+ }+ return dir;+}++/** The plan for a repo as it stands: cache key → the paths in that batch. */+function planOf(dir: string): Map<string, string[]> {+ const summaries: FileSummary[] = [];+ const hashByPath = new Map<string, string>();+ for (const name of readdirSync(join(dir, "src")).sort((a, b) => a.localeCompare(b))) {+ const rel = `src/${name}`;+ const code = readFileSync(join(dir, rel), "utf8");+ summaries.push({ path: rel, summary: code });+ hashByPath.set(rel, contentHash(code));+ }+ return new Map(planSynthesis(summaries, hashByPath).map((b: SynthesisBatch) => [b.key, b.files.map((f) => f.path)]));+}++/**+ * The invariant: re-planning is LOCAL. A batch's files only change if a boundary+ * appeared or disappeared next to the change, so the batches whose keys move are+ * the one the change lands in and the two either side of it — and nothing further+ * out. A size-driven cut breaks this for every batch after the change; a rule that+ * re-strides on a changed mean breaks it for all of them.+ *+ * `touched` may or may not exist in `before` (a removal, an insertion), so the+ * batches it can disturb are found by bracketing its place in the path order.+ */+function assertLocalReplan(before: Map<string, string[]>, after: Map<string, string[]>, touched: string): void {+ const order = [...before.keys()];+ const lastBefore = [...order].reverse().find((k) => before.get(k)![before.get(k)!.length - 1] < touched);+ const at = lastBefore === undefined ? 0 : order.indexOf(lastBefore);+ const near = order.slice(Math.max(0, at - 1), at + 2);+ const neighbourhood = new Set(near.flatMap((k) => before.get(k)!));++ const invalidated = order.filter((k) => !after.has(k));+ const fresh = [...after.keys()].filter((k) => !before.has(k));+ for (const k of invalidated) {+ assert.ok(near.includes(k), `${invalidated.length} batches were invalidated, outside the ones holding ${touched}`);+ }+ for (const k of fresh) {+ for (const path of after.get(k)!) {+ assert.ok(+ neighbourhood.has(path) || path === touched,+ `${path} landed in a new batch well away from ${touched}`,+ );+ }+ }+ assert.ok(+ invalidated.length + fresh.length <= 3,+ `one change at ${touched} moved ${invalidated.length + fresh.length} of ${order.length} batches; ` ++ `a size-driven cut moves the rest`,+ );+}++const chars = (batch: SynthesisBatch): number =>+ batch.files.reduce((n, f) => n + f.path.length + f.summary.length + 8, 0);++test("a one-file edit re-plans only the batch that holds it", () => {+ const dir = makeRepo("batch-edit");+ try {+ const before = planOf(dir);+ assert.ok(before.size >= 8, `need several batches for this to say anything, got ${before.size}`);++ // One rewritten file, whose summary is a good deal longer than it was.+ const touched = "src/mod-100.ts";+ writeFileSync(join(dir, touched), fileBody(100, EDIT_CHARS));++ const after = planOf(dir);+ assertLocalReplan(before, after, touched);+ assert.equal(+ [...before.keys()].filter((k) => !after.has(k)).length,+ 1,+ "a summary that changed must not disturb the batch after it, or the next one either",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("adding a file re-plans only the batches around it", () => {+ const dir = makeRepo("batch-add");+ try {+ const before = planOf(dir);+ // Sorts between mod-100 and mod-101, so a size-driven cut would push every+ // boundary after it along — which is the cost this removes.+ const added = "src/mod-100z.ts";+ writeFileSync(join(dir, added), fileBody(0));++ assertLocalReplan(before, planOf(dir), added);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("removing a file re-plans only the batches around it", () => {+ const dir = makeRepo("batch-remove");+ try {+ const before = planOf(dir);+ const gone = "src/mod-042.ts";+ rmSync(join(dir, gone));++ assertLocalReplan(before, planOf(dir), gone);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("every batch stays under the char budget unless it is one oversized file", () => {+ const dir = makeRepo("batch-budget");+ try {+ const summaries: FileSummary[] = [];+ const hashByPath = new Map<string, string>();+ for (const name of readdirSync(join(dir, "src")).sort((a, b) => a.localeCompare(b))) {+ const rel = `src/${name}`;+ summaries.push({ path: rel, summary: readFileSync(join(dir, rel), "utf8") });+ hashByPath.set(rel, "h");+ }+ for (const batch of planSynthesis(summaries, hashByPath)) {+ assert.ok(+ batch.files.length === 1 || chars(batch) <= BATCH_CHAR_BUDGET,+ `a ${batch.files.length}-file batch of ${chars(batch)} chars is over the ${BATCH_CHAR_BUDGET} budget`,+ );+ }+ // One file bigger than the whole budget is its own batch rather than a+ // truncated neighbour's problem.+ const huge: FileSummary[] = [...summaries, { path: "src/huge.ts", summary: "x".repeat(BATCH_CHAR_BUDGET * 2) }];+ const plan = planSynthesis(huge, new Map([["src/huge.ts", "h"]]));+ const hugeBatch = plan.find((b) => b.files.some((f) => f.path === "src/huge.ts"));+ assert.ok(hugeBatch, "the oversized file must still be synthesized");+ assert.ok(+ hugeBatch.files.every((f) => f.path === "src/huge.ts" || chars(hugeBatch) <= BATCH_CHAR_BUDGET),+ "an oversized file must not drag neighbours over the budget",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("a re-build after a one-file edit re-synthesizes one batch, not the graph", async () => {+ const dir = makeRepo("batch-e2e");+ let calls = 0;+ const synthesizer: Synthesizer = {+ async synthesize(files) {+ calls++;+ return files.map((f) => ({ name: f.path, type: "file", summary: "s", sources: [f.path], links: [] }));+ },+ };+ const orig = console.error;+ console.error = () => {};+ try {+ const first = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });+ assert.ok(first.batches >= 8, `need several batches for this to say anything, got ${first.batches}`);+ const cold = calls;+ assert.equal(cold, first.batches);++ calls = 0;+ const warm = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });+ assert.equal(calls, 0, "an unchanged repo spends nothing");+ assert.equal(warm.batches, first.batches);++ calls = 0;+ writeFileSync(join(dir, "src", "mod-100.ts"), fileBody(100, EDIT_CHARS));+ const after = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });+ assert.equal(after.batches, first.batches);+ assert.ok(+ calls >= 1 && calls <= 2,+ `one edited file of ${first.batches} batches cost ${calls} synthesis calls; it must cost its own batch`,+ );+ } finally {+ console.error = orig;+ rmSync(dir, { recursive: true, force: true });+ }+});diff --git a/test/context-synth-concurrency.test.ts b/test/context-synth-concurrency.test.tsnew file mode 100644index 00000000..8c30694d--- /dev/null+++ b/test/context-synth-concurrency.test.ts@@ -0,0 +1,200 @@+/**+ * The concept pass synthesizes its batches CONCURRENTLY (phase 2 of+ * `context/build.ts`). A batch is an independent unit of work — its call sees only+ * its own summaries, and the merge waits for every call — so the calls overlap+ * while the graph they produce has to stay indistinguishable from the serial one.+ *+ * These tests pin that with a synthesizer that answers OUT OF ORDER (the first call+ * is the slowest), which is exactly what an implementation that merged batches as+ * their calls landed would get wrong: same nodes, same slugs, same bytes, but a+ * first-wins tie broken by network timing instead of by batch order.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { createHash } from "node:crypto";+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";+import { join, relative } from "node:path";+import { setTimeout as sleep } from "node:timers/promises";+import { buildContext, type BuildProgress } from "../src/context/build.js";+import { tmpRepo, PassthroughSummarizer } from "./helpers.js";+import type { FileSummary, SynthNode, Synthesizer } from "../src/index.js";++/** A repo big enough to be cut into several synthesis batches (1 file each). */+const BATCHES = 6;++/** One file per batch: two of them overshoot the char budget together. */+function makeRepo(tag: string): string {+ const dir = tmpRepo(tag);+ mkdirSync(join(dir, "src"), { recursive: true });+ for (let i = 0; i < BATCHES; i++) {+ writeFileSync(join(dir, "src", `m${i}.ts`), `export const m${i} = 1;\n// ${"x".repeat(30_000)}\n`);+ }+ return dir;+}++/**+ * The nodes one batch contributes. Batch 0 and batch 1 both claim a `Shared` node+ * with DIFFERENT types, which is the merge's one first-wins tie: whichever batch+ * is merged first decides the type that lands on disk.+ */+function nodesFor(batch: number, files: FileSummary[]): SynthNode[] {+ const sources = files.map((f) => f.path);+ const nodes: SynthNode[] = [{ name: `Batch ${batch}`, type: "file", summary: `batch ${batch}`, sources, links: [] }];+ if (batch <= 1) {+ nodes.push({ name: "Shared", type: batch === 0 ? "system" : "api", summary: `shared from batch ${batch}`, sources, links: [] });+ }+ return nodes;+}++/**+ * Answers in reverse batch order — the first call started is the last to land — and+ * records both the completion order and the high-water mark of calls in flight, so+ * a test can show the calls really did overlap.+ */+class ReverseSynthesizer implements Synthesizer {+ readonly completionOrder: number[] = [];+ peakInFlight = 0;+ private inFlight = 0;+ private started = 0;++ constructor(private readonly stepMs: number) {}++ async synthesize(files: FileSummary[]): Promise<SynthNode[]> {+ // `mapWithConcurrency` hands each worker the next batch the moment it starts, so+ // the call order is the batch order.+ const batch = this.started++;+ this.inFlight++;+ this.peakInFlight = Math.max(this.peakInFlight, this.inFlight);+ try {+ await sleep(this.stepMs * (BATCHES - batch));+ this.completionOrder.push(batch);+ return nodesFor(batch, files);+ } finally {+ this.inFlight--;+ }+ }+}++/** Every file under `dir`, as `relpath → sha256`, for a byte-for-byte comparison. */+function snapshot(dir: string): Map<string, string> {+ const out = new Map<string, string>();+ const walk = (d: string): void => {+ for (const entry of readdirSync(d, { withFileTypes: true })) {+ const full = join(d, entry.name);+ if (entry.isDirectory()) walk(full);+ else out.set(relative(dir, full).split("\\").join("/"), createHash("sha256").update(readFileSync(full)).digest("hex"));+ }+ };+ walk(dir);+ return out;+}++function opts(synthesizer: Synthesizer, extra: Record<string, unknown> = {}) {+ return { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer, ...extra };+}++test("batches synthesize in parallel and the graph is byte-identical to a serial run", async () => {+ const serialDir = makeRepo("synth-serial");+ const parallelDir = makeRepo("synth-parallel");+ const quiet = () => {};+ const orig = console.error;+ console.error = quiet;+ try {+ const serial = new ReverseSynthesizer(5);+ const parallel = new ReverseSynthesizer(5);+ const a = await buildContext(serialDir, opts(serial, { synthConcurrency: 1, onProgress: quiet }));+ const b = await buildContext(parallelDir, opts(parallel, { synthConcurrency: BATCHES, onProgress: quiet }));++ assert.equal(a.batches, BATCHES);+ assert.equal(b.batches, BATCHES);+ assert.equal(serial.peakInFlight, 1, "synthConcurrency: 1 must not overlap calls");+ assert.ok(parallel.peakInFlight > 1, `expected overlapping calls, peak was ${parallel.peakInFlight}`);+ assert.deepEqual(+ parallel.completionOrder,+ [...parallel.completionOrder].sort((x, y) => y - x),+ "the stand-in must land out of batch order, or the run proves nothing",+ );++ const expected = snapshot(join(serialDir, "graft"));+ const actual = snapshot(join(parallelDir, "graft"));+ assert.deepEqual([...actual.keys()].sort(), [...expected.keys()].sort());+ for (const [file, hash] of expected) {+ assert.equal(actual.get(file), hash, `${file} differs between the serial and parallel runs`);+ }+ } finally {+ console.error = orig;+ rmSync(serialDir, { recursive: true, force: true });+ rmSync(parallelDir, { recursive: true, force: true });+ }+});++test("a first-wins tie is broken by batch order, not by which call landed first", async () => {+ const dir = makeRepo("synth-order");+ const orig = console.error;+ console.error = () => {};+ try {+ const synth = new ReverseSynthesizer(5);+ const r = await buildContext(dir, opts(synth, { synthConcurrency: BATCHES }));+ assert.ok(r.nodes >= BATCHES);+ // Batch 0 lands last under the stand-in above, so this is batch 0's type only+ // if the merge consumes the results in batch order.+ const shared = readFileSync(join(dir, "graft", "shared.md"), "utf8");+ assert.match(shared, /^type: system$/m);+ assert.doesNotMatch(shared, /^type: api$/m);+ } finally {+ console.error = orig;+ rmSync(dir, { recursive: true, force: true });+ }+});++test("the failure gate stops issuing synthesis calls once the provider is fatal", async () => {+ const dir = makeRepo("synth-gate");+ let calls = 0;+ const synthesizer: Synthesizer = {+ async synthesize() {+ calls++;+ throw new Error("429 insufficient_quota");+ },+ };+ const logged: string[] = [];+ const orig = console.error;+ console.error = (...args: unknown[]) => {+ logged.push(args.map(String).join(" "));+ };+ try {+ // 2 in flight, so the gate is fatal long before the last four batches run.+ const r = await buildContext(dir, opts(synthesizer, { synthConcurrency: 2 }));+ assert.ok(r.fatal, "a spent quota must end the pass");+ assert.match(r.fatal, /quota/);+ assert.equal(r.nodes, 0);+ assert.equal(r.errors.length, calls, "every issued call is reported as an error");+ assert.ok(calls < r.batches, `the gate must stop issuing calls: ${calls} of ${r.batches} were made`);+ assert.ok(logged.some((l) => /synthesis batch 1\/\d+: 0 nodes, 0 links \(failed\)/.test(l)));+ assert.ok(logged.some((l) => /\(skipped\)/.test(l)), "a batch the gate skipped is labelled, not silently empty");+ } finally {+ console.error = orig;+ rmSync(dir, { recursive: true, force: true });+ }+});++test("synthesis progress climbs monotonically under concurrency", async () => {+ const dir = makeRepo("synth-progress");+ const progress: BuildProgress[] = [];+ const orig = console.error;+ console.error = () => {};+ try {+ await buildContext(dir, opts(new ReverseSynthesizer(5), {+ synthConcurrency: BATCHES,+ onProgress: (info: BuildProgress) => progress.push(info),+ }));+ const synth = progress.filter((p) => p.phase === "synthesize");+ assert.equal(synth.length, BATCHES, "one report per batch, however they interleave");+ // The CLI overwrites one line with these, so a counter that went backwards+ // would read as the pass rewinding itself.+ assert.deepEqual(synth.map((p) => p.index), [...synth.map((p) => p.index)].sort((x, y) => x - y));+ for (const p of synth) assert.equal(p.total, BATCHES);+ } finally {+ console.error = orig;+ rmSync(dir, { recursive: true, force: true });+ }+});