Skip to content

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

perf(ask): mtime-keyed graph/index cache — warm queries in long-lived processes

Shrish Dwivediaba4c16796d4
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index 408c64a5..81b4de5f 100644
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@ -17,10 +17,10 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
import { join, resolve } from "node:path";
import matter from "gray-matter";
import { contextDirFor } from "../context/node-file.js";
-import { readGraph, wiringPath } from "../graph/write.js";
+import { loadGraphCached, loadAskIndexCached } from "../graph/load.js";
import type { EdgeV1, GraphV1, NodeV1, Relation } from "../graph/types.js";
import { personalizedPageRank } from "./graphrank.js";
-import { counts, readAskIndex, tokenize, type AskIndex, type AskIndexDoc } from "./index-file.js";
+import { counts, tokenize, type AskIndex, type AskIndexDoc } from "./index-file.js";
export interface AskHit {
kind: "concept" | "symbol" | "caller" | "callee";
@@ -97,7 +97,7 @@ function loadCorpus(outDir: string): Corpus {
});
}
}
- return { concepts, graph: readGraph(wiringPath(outDir)), askIndex: readAskIndex(outDir) };
+ return { concepts, graph: loadGraphCached(outDir), askIndex: loadAskIndexCached(outDir) };
}
/** Score a document's token counts against the query counts (name field
diff --git a/src/graph/load.ts b/src/graph/load.ts
new file mode 100644
index 00000000..8af71aef
--- /dev/null
+++ b/src/graph/load.ts
@@ -0,0 +1,91 @@
+/**
+ * mtime-keyed in-process cache over the two readers `ask()` calls on every
+ * query: the wiring graph (`readGraph`) and the ask sidecar (`readAskIndex`).
+ * `graft ask` re-parses these from disk on every invocation; in a long-lived
+ * process — the MCP server, or `graft ask` invoked repeatedly in one process —
+ * that means re-parsing the same ~tens-of-MB JSON on every tool call.
+ *
+ * Keyed by `(path, mtimeMs, size)` from `statSync`, so a rebuild (`graft
+ * build`) is picked up on the very next call with no polling and no TTL: the
+ * stat is cheap relative to the parse it guards, and a changed mtime or size
+ * invalidates the entry. A missing file returns null and is never cached — the
+ * next call re-stats, so a file created after a prior miss is picked up
+ * immediately (no negative caching).
+ *
+ * Dependency-free by design: this module imports only `node:fs`, `./write.js`,
+ * and `../ask/index-file.js`, so it can be imported from both `ask.ts` and
+ * `mcp/tools.ts` without creating an import cycle.
+ */
+import { statSync } from "node:fs";
+import { readGraph, wiringPath } from "./write.js";
+import { readAskIndex, askIndexPath, type AskIndex } from "../ask/index-file.js";
+import type { GraphV1 } from "./types.js";
+
+interface CacheEntry<T> {
+ mtimeMs: number;
+ size: number;
+ value: T | null;
+}
+
+const graphCache = new Map<string, CacheEntry<GraphV1>>();
+const askIndexCache = new Map<string, CacheEntry<AskIndex>>();
+
+/** Real parses performed (cache misses), not cache hits — exported for tests
+ * so the invalidation contract can be pinned down without spying on `fs`. */
+export const __parseCount = { graph: 0, askIndex: 0 };
+
+/** Test-only: zero the counters (module state persists across a test file). */
+export function __resetParseCounts(): void {
+ __parseCount.graph = 0;
+ __parseCount.askIndex = 0;
+}
+
+function statOf(path: string): { mtimeMs: number; size: number } | null {
+ try {
+ const s = statSync(path);
+ return { mtimeMs: s.mtimeMs, size: s.size };
+ } catch {
+ return null;
+ }
+}
+
+function loadCached<T>(
+ cache: Map<string, CacheEntry<T>>,
+ path: string,
+ parse: () => T | null,
+ onParse: () => void,
+): T | null {
+ const st = statOf(path);
+ if (!st) {
+ // Missing file: don't negatively cache, and drop any stale entry so a
+ // subsequently-created file at the same path is re-parsed, not served
+ // from a cache keyed to the old (mtime, size).
+ cache.delete(path);
+ return null;
+ }
+ const cached = cache.get(path);
+ if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) {
+ return cached.value;
+ }
+ onParse();
+ const value = parse();
+ cache.set(path, { mtimeMs: st.mtimeMs, size: st.size, value });
+ return value;
+}
+
+/** Cached `readGraph(wiringPath(outDir))` — same null-on-missing/unparseable
+ * semantics, re-reads only when the wiring file's `(mtimeMs, size)` changed. */
+export function loadGraphCached(outDir: string): GraphV1 | null {
+ const path = wiringPath(outDir);
+ return loadCached(graphCache, path, () => readGraph(path), () => {
+ __parseCount.graph++;
+ });
+}
+
+/** Cached `readAskIndex(outDir)` — same semantics, keyed on the sidecar file. */
+export function loadAskIndexCached(outDir: string): AskIndex | null {
+ const path = askIndexPath(outDir);
+ return loadCached(askIndexCache, path, () => readAskIndex(outDir), () => {
+ __parseCount.askIndex++;
+ });
+}
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index d55fda1d..1f6aa964 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -7,7 +7,7 @@ import { formatAsk } from '../ask/ask.js';
import { formatCheckReport } from '../context/check.js';
import { formatGraphCheckReport } from '../graph/check.js';
import { formatBlastRadius } from '../claude/format.js';
-import { readGraph, wiringPath } from '../graph/write.js';
+import { loadGraphCached } from '../graph/load.js';
import { contextDirFor } from '../context/node-file.js';
export interface ToolDef {
@@ -72,7 +72,7 @@ export function callTool(
case 'graft_blast_radius': {
const file = String(args.file ?? '');
if (!file) return { text: 'graft_blast_radius requires a file', isError: true };
- const w = readGraph(wiringPath(contextDirFor(root)));
+ const w = loadGraphCached(contextDirFor(root));
if (!w) return { text: 'no graph found — run `graft build` first', isError: true };
const br = formatBlastRadius(w, file);
return { text: br ?? `no known dependents of ${file}`, isError: false };
diff --git a/test/graph-load.test.ts b/test/graph-load.test.ts
new file mode 100644
index 00000000..2cdd388e
--- /dev/null
+++ b/test/graph-load.test.ts
@@ -0,0 +1,145 @@
+/**
+ * Tests for the mtime-keyed loader cache (`src/graph/load.ts`) that sits in
+ * front of `readGraph`/`readAskIndex` so a long-lived process (the MCP server;
+ * `graft ask` invoked repeatedly in one process) doesn't re-parse the wiring
+ * graph and ask sidecar on every query.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, utimesSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+ loadGraphCached,
+ loadAskIndexCached,
+ __parseCount,
+ __resetParseCounts,
+} from "../src/graph/load.js";
+import { writeGraph, wiringPath } from "../src/graph/write.js";
+import { writeAskIndex, askIndexPath } from "../src/ask/index-file.js";
+import { callTool } from "../src/mcp/tools.js";
+import type { GraphV1, NodeV1 } from "../src/graph/types.js";
+
+function node(id: string): NodeV1 {
+ return {
+ id,
+ name: id,
+ kind: "function",
+ path: `${id}.ts`,
+ span: "L1-L1",
+ signature: null,
+ exported: true,
+ origin: "ast",
+ body_hash: id,
+ summary_state: "pending",
+ summary: null,
+ crux: null,
+ };
+}
+
+function fixtureDir(): string {
+ return mkdtempSync(join(tmpdir(), "graft-load-"));
+}
+
+/** Force a distinct (mtimeMs, size) from the previous write, even on
+ * filesystems with coarse mtime resolution. */
+function bump(path: string): void {
+ const st = statSync(path);
+ const future = new Date(st.mtimeMs + 1000);
+ utimesSync(path, future, future);
+}
+
+test("loadGraphCached: two loads of an unchanged file return the same parsed object", () => {
+ const dir = fixtureDir();
+ writeGraph({ version: 1, nodes: [node("a")], edges: [] } as GraphV1, dir);
+ __resetParseCounts();
+
+ const g1 = loadGraphCached(dir);
+ const g2 = loadGraphCached(dir);
+ assert.ok(g1);
+ assert.strictEqual(g1, g2, "second load must reuse the cached object, not re-parse");
+ assert.equal(__parseCount.graph, 1);
+});
+
+test("loadGraphCached: rewriting the wiring file invalidates the cache", () => {
+ const dir = fixtureDir();
+ writeGraph({ version: 1, nodes: [node("a")], edges: [] } as GraphV1, dir);
+ __resetParseCounts();
+
+ const g1 = loadGraphCached(dir);
+ assert.equal(g1?.nodes[0]?.id, "a");
+ assert.equal(__parseCount.graph, 1);
+
+ // Rewrite with a changed node, then force a distinct mtime so the cache
+ // can't coast on a filesystem with coarse mtime granularity.
+ writeGraph({ version: 1, nodes: [node("b")], edges: [] } as GraphV1, dir);
+ bump(wiringPath(dir));
+
+ const g2 = loadGraphCached(dir);
+ assert.equal(g2?.nodes[0]?.id, "b", "reload must see the new content");
+ assert.equal(__parseCount.graph, 2, "changed (mtime, size) must trigger a re-parse");
+ assert.notStrictEqual(g1, g2);
+});
+
+test("loadGraphCached: missing file returns null and a later-created file is picked up", () => {
+ const dir = fixtureDir();
+ __resetParseCounts();
+
+ const miss = loadGraphCached(dir);
+ assert.equal(miss, null);
+ assert.equal(__parseCount.graph, 0, "a miss must not count as a parse");
+
+ const missAgain = loadGraphCached(dir);
+ assert.equal(missAgain, null, "missing file must not be negatively cached forever");
+
+ writeGraph({ version: 1, nodes: [node("late")], edges: [] } as GraphV1, dir);
+ const found = loadGraphCached(dir);
+ assert.equal(found?.nodes[0]?.id, "late");
+ assert.equal(__parseCount.graph, 1);
+});
+
+test("loadAskIndexCached: caches and invalidates the same way as the graph loader", () => {
+ const dir = fixtureDir();
+ const graph = { version: 1, nodes: [node("a"), node("b")], edges: [] } as GraphV1;
+ writeAskIndex(dir, graph);
+ __resetParseCounts();
+
+ const i1 = loadAskIndexCached(dir);
+ const i2 = loadAskIndexCached(dir);
+ assert.ok(i1);
+ assert.strictEqual(i1, i2);
+ assert.equal(__parseCount.askIndex, 1);
+
+ writeAskIndex(dir, { version: 1, nodes: [node("a")], edges: [] } as GraphV1);
+ bump(askIndexPath(dir));
+
+ const i3 = loadAskIndexCached(dir);
+ assert.equal(i3?.docCount, 1);
+ assert.equal(__parseCount.askIndex, 2);
+});
+
+test("callTool: graft_blast_radius on the same dir twice doesn't reparse the graph", () => {
+ const dir = fixtureDir();
+ mkdirSync(join(dir, "src"), { recursive: true });
+ writeFileSync(join(dir, "src", "math.ts"), "export function add() { return 1; }\n");
+ const graph: GraphV1 = {
+ version: 1,
+ nodes: [{ ...node("src/math.ts#add"), path: "src/math.ts" }],
+ edges: [],
+ } as GraphV1;
+ // graft_blast_radius reads through `contextDirFor(root)`, i.e. `<root>/graft`
+ // by default — write the graph there directly rather than round-tripping
+ // through a real `graft build`.
+ const outDir = join(dir, "graft");
+ mkdirSync(outDir, { recursive: true });
+ writeGraph(graph, outDir);
+ __resetParseCounts();
+
+ const r1 = callTool(dir, "graft_blast_radius", { file: "src/math.ts" });
+ assert.equal(r1.isError, false);
+ assert.equal(__parseCount.graph, 1);
+
+ const r2 = callTool(dir, "graft_blast_radius", { file: "src/math.ts" });
+ assert.equal(r2.isError, false);
+ assert.equal(__parseCount.graph, 1, "second call on the same dir must not reparse");
+});