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(deep): make the concept phase resumable across sessions
Shrish Dwivedi76f43cd27b5b
diff --git a/src/context/build.ts b/src/context/build.tsindex 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<Buiconst 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.tsnew file mode 100644index 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);+ }+});