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(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.tsindex 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 fielddiff --git a/src/graph/load.ts b/src/graph/load.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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");+});