Skip to content

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

feat(deep): make the concept phase resumable across sessions

Shrish Dwivedi76f43cd27b5b
diff --git a/src/context/build.ts b/src/context/build.ts
index 45936ea3..da6c3ace 100644
--- a/src/context/build.ts
+++ b/src/context/build.ts
@@ -11,7 +11,7 @@
* source files so staleness stays exact.
* 5. Write one markdown file per node (preserving human notes) + a manifest.
*/
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from "node:fs";
import { join, resolve } from "node:path";
import { walkDir } from "../ingest/fs.js";
import { contentHash } from "../util/id.js";
@@ -63,6 +63,8 @@ export interface BuildOptions {
model: string;
summarizer: Summarizer;
synthesizer: Synthesizer;
+ /** Files summarized in parallel during phase 1. Default 8. Raised via `graft build -j`. */
+ concurrency?: number;
onProgress?: (info: BuildProgress) => void;
}
@@ -112,6 +114,18 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
.filter((f) => !f.startsWith(outDir));
const cache = loadCache(outDir);
+ // Flush the summary cache to disk during phase 1 so a build interrupted
+ // partway (session/rate limit, crash, Ctrl-C) resumes without re-summarizing
+ // the files it already did. Throttled to keep disk churn negligible; on the
+ // next run every already-summarized file is a content-hash cache hit ($0).
+ let lastFlush = Date.now();
+ const flushEveryMs = summaryCheckpointMs();
+ const maybeFlush = (): void => {
+ const now = Date.now();
+ if (now - lastFlush < flushEveryMs) return;
+ lastFlush = now;
+ saveCache(outDir, cache);
+ };
const result: BuildResult = {
contextDir: outDir,
files: 0,
@@ -124,7 +138,7 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
};
// Phase 1: summarize each file, concurrent, content-hash cached.
- const work = await mapWithConcurrency(files, 8, async (file, i): Promise<FileWork | undefined> => {
+ const work = await mapWithConcurrency(files, Math.max(1, opts.concurrency ?? 8), async (file, i): Promise<FileWork | undefined> => {
const rel = relPosix(root, file);
opts.onProgress?.({ phase: "summarize", index: i, total: files.length, file: rel });
let code: string;
@@ -146,6 +160,7 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
const summary = await opts.summarizer.summarize(code, { path: rel });
cache.summaries[rel] = { hash, summary };
result.summarized++;
+ maybeFlush();
return { rel, hash, summary };
} catch (err) {
result.errors.push(`${rel}: ${errMsg(err)}`);
@@ -153,6 +168,10 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
}
});
+ // Phase 1 done: persist every summary before the (also LLM-backed) synthesis
+ // phase, so an interruption there never discards phase-1 work.
+ saveCache(outDir, cache);
+
const processed = work.filter((w): w is FileWork => w !== undefined);
result.files = processed.length;
const hashByPath = new Map(processed.map((w) => [w.rel, w.hash]));
@@ -336,7 +355,17 @@ function loadCache(outDir: string): BuildCache {
function saveCache(outDir: string, cache: BuildCache): void {
const path = cachePath(outDir);
mkdirSync(join(outDir, CACHE_DIR), { recursive: true });
- writeFileSync(path, JSON.stringify(cache, null, 2));
+ // Atomic: a kill mid-write can't leave a truncated (unparseable) cache that
+ // would throw away every prior summary on the next load.
+ const tmp = `${path}.tmp`;
+ writeFileSync(tmp, JSON.stringify(cache, null, 2));
+ renameSync(tmp, path);
+}
+
+/** Min interval between phase-1 cache flushes. Env seam for tests. */
+function summaryCheckpointMs(): number {
+ const raw = Number(process.env.GRAFT_SUMMARY_CHECKPOINT_MS);
+ return Number.isFinite(raw) && raw >= 0 ? raw : 15_000;
}
/** Run `fn` over `items` with at most `limit` in flight, preserving order. */
diff --git a/test/context-checkpoint.test.ts b/test/context-checkpoint.test.ts
new file mode 100644
index 00000000..4298fb47
--- /dev/null
+++ b/test/context-checkpoint.test.ts
@@ -0,0 +1,96 @@
+/**
+ * The concept phase must be resumable across runs: a build interrupted partway
+ * (session/rate limit, crash) has to pick up where it left off, not re-summarize
+ * files it already did. That rests on the phase-1 summary cache being flushed to
+ * disk *during* the pass, not only at the end.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { buildContext } from "../src/context/build.js";
+import { BracketSynthesizer, PassthroughSummarizer } from "./helpers.js";
+import type { Summarizer } from "../src/ai/summarize.js";
+
+const rmDir = (dir: string): void => rmSync(dir, { recursive: true, force: true });
+
+const cachePath = (dir: string): string => join(dir, "graft", ".cache", "summaries.json");
+
+function fixture(n: number): string {
+ const dir = mkdtempSync(join(tmpdir(), "ctxflush-"));
+ for (let i = 0; i < n; i++) {
+ writeFileSync(join(dir, `f${i}.ts`), `// [[Node ${i}]]\nexport const v${i} = ${i};\n`);
+ }
+ return dir;
+}
+
+function diskSummaryCount(dir: string): number {
+ const p = cachePath(dir);
+ if (!existsSync(p)) return 0;
+ const parsed = JSON.parse(readFileSync(p, "utf8")) as { summaries?: Record<string, unknown> };
+ return Object.keys(parsed.summaries ?? {}).length;
+}
+
+test("phase-1 summaries flush to disk mid-run, so an interrupted build resumes", async () => {
+ const dir = fixture(4);
+ const prev = process.env.GRAFT_SUMMARY_CHECKPOINT_MS;
+ process.env.GRAFT_SUMMARY_CHECKPOINT_MS = "0"; // flush after every file
+ let calls = 0;
+ let diskAtThird = -1;
+ const summarizer: Summarizer = {
+ async summarize(code: string): Promise<string> {
+ calls++;
+ // By the time the 3rd file is being summarized (concurrency 1, in order),
+ // the first two must already be persisted — that is what makes a kill here
+ // survivable.
+ if (calls === 3) diskAtThird = diskSummaryCount(dir);
+ return code;
+ },
+ };
+ try {
+ await buildContext(dir, {
+ model: "fake",
+ summarizer,
+ synthesizer: new BracketSynthesizer(),
+ concurrency: 1,
+ });
+ assert.equal(calls, 4);
+ assert.ok(diskAtThird >= 2, `expected ≥2 summaries flushed before the 3rd file, saw ${diskAtThird}`);
+ } finally {
+ if (prev === undefined) delete process.env.GRAFT_SUMMARY_CHECKPOINT_MS;
+ else process.env.GRAFT_SUMMARY_CHECKPOINT_MS = prev;
+ rmDir(dir);
+ }
+});
+
+test("a rerun re-summarizes nothing — resume is $0 for unchanged files", async () => {
+ const dir = fixture(4);
+ try {
+ const first = await buildContext(dir, {
+ model: "fake",
+ summarizer: new PassthroughSummarizer(),
+ synthesizer: new BracketSynthesizer(),
+ });
+ assert.equal(first.summarized, 4);
+ assert.equal(first.cached, 0);
+
+ let called = false;
+ const summarizer: Summarizer = {
+ async summarize(code: string): Promise<string> {
+ called = true;
+ return code;
+ },
+ };
+ const second = await buildContext(dir, {
+ model: "fake",
+ summarizer,
+ synthesizer: new BracketSynthesizer(),
+ });
+ assert.equal(called, false, "no file should be re-summarized on an unchanged rerun");
+ assert.equal(second.summarized, 0);
+ assert.equal(second.cached, 4);
+ } finally {
+ rmDir(dir);
+ }
+});