Skip to content

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

refresh the graph before every query, incrementally

anirudhkumar-nanonets14abd300518f
diff --git a/.claude/settings.json b/.claude/settings.json
index 2c42314b..75d6b239 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -50,7 +50,7 @@
{
"type": "command",
"command": "node \"${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/graft-hooks.cjs\" prompt",
- "timeout": 8000
+ "timeout": 15000
}
]
}
diff --git a/README.md b/README.md
index 8fa0d9bb..7fcedc87 100644
--- a/README.md
+++ b/README.md
@@ -119,7 +119,9 @@ flowchart LR
P2 --> N["graft/*.md<br/>markdown node graph"]
```
-Both LLM passes are cached by content hash. Re-running only touches the files that changed, so the second build is fast and cheap.
+Every pass is cached by content hash — the LLM ones and the tree-sitter parse alike. Re-running only touches the files that changed, so the second build is fast and cheap (on this repo, 124 files: 0.74s cold, 0.18s after one edited file, 0.18s with nothing changed). `graft build --no-reuse` forces a cold re-parse.
+
+That cheapness is what lets **every query refresh the graph before it answers**. A retrieval call stats the tree against the last build's fingerprint (~3ms), and rebuilds only if something moved — so `ask`/`grep`/`callers`/`skeleton`/`map` describe the code as it is right now, including edits that are unsaved to git: uncommitted, unstaged, or staged all look the same to graft, which never reads git at all. The refresh is structural and `$0`; it never calls the LLM. Turn it off per-command with `--no-refresh`, or everywhere with `GRAFT_NO_REFRESH=1`.
Alongside the markdown graph, `graft build` builds `graft/.graph/wiring.json` — a per-symbol code graph — plus a per-file wiring card mirroring your source tree. Tier 1 is pure tree-sitter (every function, class, and call edge; deterministic, no model, no network), which is why plain `graft build` needs no key. The `--deep` pass adds a one-line summary and a crux excerpt per symbol, cached by body hash.
@@ -220,8 +222,8 @@ Where a CLI agent supports user-level `hooks.json`, `init` also installs Graft's
`graft init` always wires up Claude Code, and Claude Code gets more than an instruction file. From then on, any Claude Code session opened in the repo gets:
-- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph
-- **auto-sync** — after you edit code, Graft rebuilds the graph in the background at the end of the turn (structural, `$0` — it never calls the LLM on its own)
+- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph (it flips back to `✓ synced` as soon as any graft query refreshes it, without waiting for the turn to end)
+- **auto-sync** — every graft query brings the graph up to date first, so an answer always describes the code as it is right now, uncommitted edits included; a background rebuild also runs at the end of a turn that touched code. Both are structural and `$0` — auto-sync never calls the LLM on its own
- **context on tap** — each prompt pulls the matching nodes into the session; editing a file surfaces what depends on it ("blast radius"); new sessions start with the repo map
<p align="center">
@@ -239,6 +241,7 @@ Where a CLI agent supports user-level `hooks.json`, `init` also installs Graft's
graft build [dir] # build graft/ from the code at [dir]: wiring graph + per-file cards (no LLM, no key)
graft build --deep # add the LLM layer: concept nodes + per-symbol summary/crux (cached)
graft build --extensions .ts .py # only include these code extensions
+graft build --no-reuse # re-parse every file instead of replaying unchanged ones from cache
graft ask "<task>" [dir] # query the graph — ranked nodes + exact file:line (no LLM, no key)
graft ask "<task>" --json # machine-readable result
@@ -257,9 +260,14 @@ graft grep "<regex>" -i --fixed # case-insensitive; treat the pattern as a
graft map [dir] # token-budgeted repo orientation — dir clusters, hubs, hotspots (no LLM, no key)
graft map --max-dirs N # raise/lower the number of directories shown
-graft check [dir] # fail (exit 1) if graft/ has drifted from the code
+graft check [dir] # fail (exit 1) if graft/ has drifted from the code (never auto-refreshes — it's the drift report)
graft check --json # print the drift report as JSON
+# ask / skeleton / callers / grep / map all refresh the graph first if the working tree moved:
+# --no-refresh # answer from the graph exactly as it is on disk
+# GRAFT_NO_REFRESH=1 # same, for every command
+# GRAFT_REFRESH=hash # hash every file instead of trusting size+mtime
+
graft viz [dir] # see the graph: serves an interactive viewer on localhost
graft viz --port 5000 --no-open # pick a port; don't auto-open the browser
diff --git a/src/claude/settings-merge.ts b/src/claude/settings-merge.ts
index f1aeadc4..90540b62 100644
--- a/src/claude/settings-merge.ts
+++ b/src/claude/settings-merge.ts
@@ -17,7 +17,10 @@ function graftBlocks(): Record<string, Json[]> {
// is actually present, so non-graft Bash calls cost only a stdin read.
{ matcher: 'Bash|mcp__graft__', hooks: [{ type: 'command', command: hookCmd('tool-savings'), timeout: 8000 }] },
],
- UserPromptSubmit: [{ hooks: [{ type: 'command', command: hookCmd('prompt'), timeout: 8000 }] }],
+ // Longer budget than the other hooks: its `graft ask` is a real query, and a
+ // query now brings the graph up to date first (graph/refresh.ts) — usually
+ // milliseconds, but the first one after an upgrade re-parses the repo once.
+ UserPromptSubmit: [{ hooks: [{ type: 'command', command: hookCmd('prompt'), timeout: 15000 }] }],
SessionStart: [{ hooks: [{ type: 'command', command: hookCmd('session-start'), timeout: 8000 }] }],
Stop: [{ hooks: [{ type: 'command', command: hookCmd('stop'), timeout: 8000 }] }],
};
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
index 2791310d..87bd0bd6 100644
--- a/src/claude/skill-template.ts
+++ b/src/claude/skill-template.ts
@@ -80,9 +80,11 @@ hotspots, straight from the wiring graph.
or ask your way through every subsystem it lists. \`--max-dirs N\` widens it.
### 6 · Lifecycle: \`graft build\` / \`graft check\`
-\`build\` regenerates the graph after code changes (\`$0\`; \`--deep\` adds an LLM
-concept map, skip unless asked). \`check\` fails when \`graft/\` is stale (for CI).
-You rarely touch these mid-task; the graph is already built and committed.
+Every tool above refreshes the graph itself before answering, so what you get back
+always describes the code as it is right now — including edits you just made and
+have not committed. You do **not** need to run \`build\` after editing.
+\`build\` is for the LLM layer (\`--deep\` adds a concept map; skip unless asked);
+\`check\` fails when \`graft/\` is stale, for CI.
## Scenarios: the shortest path through a coding task
diff --git a/src/claude/state.ts b/src/claude/state.ts
index a7b5f353..2b1290a1 100644
--- a/src/claude/state.ts
+++ b/src/claude/state.ts
@@ -1,12 +1,26 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, rmSync, statSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+/**
+ * Claude Code session state. The shared `graft/.cache/` pieces (the statusline's
+ * `Stats` snapshot and the build lock) live in `../util/state.js` so the graph's
+ * pre-query auto-refresh can take the same lock; they are re-exported here so
+ * every existing import path keeps working.
+ */
+import { join } from 'node:path';
+import { cacheDir, readJson, writeJsonAtomic } from '../util/state.js';
+
+export {
+ LOCK_STALE_MS,
+ acquireLock,
+ acquireLockIn,
+ releaseLockIn,
+ cacheDir,
+ emptyStats,
+ patchStats,
+ readStats,
+ releaseLock,
+ writeStats,
+} from '../util/state.js';
+export type { Stats } from '../util/state.js';
-export interface Stats {
- nodeCount: number; edgeCount: number; languages: string[];
- totalCount: number; readyCount: number;
- staleCount: number; dirty: boolean; syncing: boolean;
- syncedAt: string | null; lastFile: string | null;
-}
export interface SessionState {
lastQuery: string | null;
perAgentQuery: Record<string, string>;
@@ -19,62 +33,15 @@ export interface SessionState {
injectedPointers?: string[];
}
-export const LOCK_STALE_MS = 300000;
-
-export function emptyStats(): Stats {
- return { nodeCount: 0, edgeCount: 0, languages: [], totalCount: 0, readyCount: 0,
- staleCount: 0, dirty: false, syncing: false, syncedAt: null, lastFile: null };
-}
function emptySession(): SessionState {
return { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0, savedTokens: 0, injectedPointers: [] };
}
-export function cacheDir(projectDir: string): string { return join(projectDir, 'graft', '.cache'); }
-function statsPath(d: string): string { return join(cacheDir(d), 'stats.json'); }
function sessionPath(d: string, id: string): string { return join(cacheDir(d), 'session', `${id}.json`); }
-function lockPath(d: string): string { return join(cacheDir(d), '.sync.lock'); }
-
-function readJson<T>(p: string): T | null {
- try { return JSON.parse(readFileSync(p, 'utf8')) as T; } catch { return null; }
-}
-function writeJsonAtomic(p: string, value: unknown): void {
- mkdirSync(dirname(p), { recursive: true });
- const tmp = `${p}.${process.pid}.tmp`;
- writeFileSync(tmp, JSON.stringify(value, null, 2));
- renameSync(tmp, p);
-}
-export function readStats(d: string): Stats | null { return readJson<Stats>(statsPath(d)); }
-export function writeStats(d: string, s: Stats): void { writeJsonAtomic(statsPath(d), s); }
-// Best-effort read-modify-write; not atomic across concurrent processes, but acceptable
-// for episodic hook writes (worst case is a lost update, not corruption).
-export function patchStats(d: string, patch: Partial<Stats>): Stats {
- const next: Stats = { ...(readStats(d) ?? emptyStats()), ...patch };
- writeStats(d, next);
- return next;
-}
export function readSession(d: string, id: string): SessionState {
return readJson<SessionState>(sessionPath(d, id)) ?? emptySession();
}
export function writeSession(d: string, id: string, s: SessionState): void {
writeJsonAtomic(sessionPath(d, id), s);
}
-
-export function acquireLock(d: string): boolean {
- const p = lockPath(d);
- mkdirSync(cacheDir(d), { recursive: true });
- const payload = JSON.stringify({ pid: process.pid, at: new Date().toISOString() });
- try {
- writeFileSync(p, payload, { flag: 'wx' }); // atomic exclusive create
- return true;
- } catch (e: any) {
- if (e?.code !== 'EEXIST') throw e;
- let stale: boolean;
- try { stale = Date.now() - statSync(p).mtimeMs >= LOCK_STALE_MS; } catch { stale = true; }
- if (!stale) return false;
- try { rmSync(p); } catch { /* another process reclaimed it */ }
- try { writeFileSync(p, payload, { flag: 'wx' }); return true; }
- catch (e2: any) { if (e2?.code === 'EEXIST') return false; throw e2; }
- }
-}
-export function releaseLock(d: string): void { try { rmSync(lockPath(d)); } catch { /* already gone */ } }
diff --git a/src/claude/stats.ts b/src/claude/stats.ts
index 6d85f1ac..15ac5b28 100644
--- a/src/claude/stats.ts
+++ b/src/claude/stats.ts
@@ -1,25 +1,14 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import type { GraphV1 } from '../graph/types.js';
-import type { Stats } from './state.js';
+
+/** `computeStats` lives in `util/state.ts` alongside the rest of the `.cache/`
+ * state, so the hooks and the graph's own pre-query refresh report the same
+ * numbers. Re-exported here because that's where callers already import it from. */
+export { computeStats } from '../util/state.js';
export function readWiring(projectDir: string): GraphV1 | null {
try {
return JSON.parse(readFileSync(join(projectDir, 'graft', '.graph', 'wiring.json'), 'utf8')) as GraphV1;
} catch { return null; }
}
-
-export function computeStats(
- w: GraphV1,
-): Pick<Stats, 'nodeCount' | 'edgeCount' | 'languages' | 'totalCount' | 'readyCount'> {
- const nodes = w.nodes ?? [];
- const edges = w.edges ?? [];
- const readyCount = nodes.filter((n) => n.summary_state === 'ready').length;
- return {
- nodeCount: w.meta?.nodeCount ?? nodes.length,
- edgeCount: w.meta?.edgeCount ?? edges.length,
- languages: w.meta?.languages ?? [],
- totalCount: nodes.length,
- readyCount,
- };
-}
diff --git a/src/cli.ts b/src/cli.ts
index 80ccd533..73677571 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -18,6 +18,7 @@ import { runHostsInit } from "./hosts/init.js";
import { hostIds } from "./hosts/registry.js";
import { contextDirFor } from "./context/node-file.js";
import { loadGraphCached } from "./graph/load.js";
+import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "./graph/refresh.js";
import { isWorkspaceBuildRoot, readWorkspace } from "./graph/workspace.js";
import {
runWorkspaceAsk,
@@ -67,6 +68,29 @@ function cliConfig(): EngineConfig {
}
const engineFrom = (): Graft => new Graft(cliConfig());
+
+/**
+ * Bring the graph up to date with the working tree before a query answers from it
+ * — the same gate the MCP tools run (see `graph/refresh.ts`). Cheap when nothing
+ * moved; a structural, $0 rebuild when it did. The note goes to stderr so `--json`
+ * stdout stays machine-readable.
+ */
+async function refreshBefore(dir: string, opts: { refresh?: boolean }): Promise<void> {
+ const globalDir = program.opts<GlobalOpts>().dir;
+ const root = resolve(dir);
+ const disabled = opts.refresh === false;
+ const ws = readWorkspace(root, globalDir);
+ const r = ws
+ ? await ensureFreshChildren(root, ws.children, { contextDir: globalDir, disabled })
+ : await ensureFreshGraph(root, { contextDir: globalDir, disabled });
+ const note = refreshNote(r);
+ if (note) console.error(note);
+}
+
+/** Attached to every query command: `--no-refresh` answers from the graph exactly
+ * as it is on disk, no rebuild. */
+const NO_REFRESH_FLAG = ["--no-refresh", "skip the freshness check — answer from the graph as-is"] as const;
+
program
.command("version")
.description("Print the installed version and the latest published on npm")
@@ -94,7 +118,8 @@ program
.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")')
.option("-j, --concurrency <n>", "files summarized in parallel during --deep (default 5)")
- .action(async (dir: string, opts: { deep?: boolean; extensions?: string[]; concurrency?: string }) => {
+ .option("--no-reuse", "re-parse every file instead of replaying unchanged ones from the extraction cache")
+ .action(async (dir: string, opts: { deep?: boolean; extensions?: string[]; concurrency?: string; reuse?: boolean }) => {
const concurrency = opts.concurrency ? Math.max(1, Number(opts.concurrency)) : undefined;
if (opts.concurrency && !Number.isFinite(concurrency)) {
console.error(`✗ --concurrency must be a number, got "${opts.concurrency}"`);
@@ -158,6 +183,7 @@ program
const g = await engine.graph(dir, {
llm: deep,
concurrency,
+ reuse: opts.reuse,
onProgress: ({ phase, index, total, file }) =>
process.stderr.write(
`\r${phase === "enrich" ? "summarizing" : "parsing"} ${index + 1}/${total}: ${file.slice(0, 50).padEnd(50)}`,
@@ -165,6 +191,7 @@ program
});
process.stderr.write("\n");
console.log(`✓ wiring: ${g.nodes} nodes (${fmt(g.byKind)}), ${g.edges} edges, ${g.cards} cards [${g.languages.join(", ")}]`);
+ console.log(` parsed: ${g.parsed} of ${g.files} files (${g.reused} replayed from cache)`);
if (deep) {
const m = g.meaning;
console.log(` meaning: ${m.computed} computed, ${m.cached} cached, ${m.stale} stale, ${m.pending} pending`);
@@ -186,7 +213,9 @@ program
.option("--full", "with --source: inline whole definition spans instead of the default ≤8-line crux excerpts")
.option("--in <path>", "narrow to nodes under this path prefix, filtered before scoring (segment-aware, like scopeOf)")
.option("--json", "output the result as JSON")
- .action(async (query: string, dir: string, opts: { limit: string; source?: boolean; full?: boolean; in?: string; json?: boolean }) => {
+ .option(...NO_REFRESH_FLAG)
+ .action(async (query: string, dir: string, opts: { limit: string; source?: boolean; full?: boolean; in?: string; json?: boolean; refresh?: boolean }) => {
+ await refreshBefore(dir, opts);
const askGlobalDir = program.opts<GlobalOpts>().dir;
if (readWorkspace(resolve(dir), askGlobalDir)) {
runWorkspaceAsk(resolve(dir), askGlobalDir, query, {
@@ -217,7 +246,9 @@ program
.argument("<file>", "repo-relative path (or unique basename) of the file")
.argument("[dir]", "repository root", ".")
.option("--json", "output the result as JSON")
- .action(async (file: string, dir: string, opts: { json?: boolean }) => {
+ .option(...NO_REFRESH_FLAG)
+ .action(async (file: string, dir: string, opts: { json?: boolean; refresh?: boolean }) => {
+ await refreshBefore(dir, opts);
const { skeleton, formatSkeleton } = await import("./ask/ask.js");
const globalOpts = program.opts<{ dir?: string }>();
const r = skeleton(dir, file, { contextDir: globalOpts.dir });
@@ -322,12 +353,14 @@ program
.option("-d, --depth <n>", 'walk transitively up to N hops for blast radius, or "all" for the full connected closure (default 1)')
.option("--in <path>", "narrow matches to nodes whose path contains this substring")
.option("--json", "output as JSON")
+ .option(...NO_REFRESH_FLAG)
.action(
async (
symbol: string,
dir: string,
- opts: { direction?: string; depth?: string; in?: string; json?: boolean },
+ opts: { direction?: string; depth?: string; in?: string; json?: boolean; refresh?: boolean },
) => {
+ await refreshBefore(dir, opts);
const globalOpts = program.opts<{ dir?: string }>();
if (!opts.json && readWorkspace(resolve(dir), globalOpts.dir)) {
runWorkspaceCallers(resolve(dir), globalOpts.dir, symbol, {
@@ -359,12 +392,14 @@ program
.option("--fixed", "treat pattern as a literal string, not a regex")
.option("--in <path>", "narrow to files whose path contains this substring")
.option("--json", "output as JSON")
+ .option(...NO_REFRESH_FLAG)
.action(
async (
pattern: string,
dir: string,
- opts: { ignoreCase?: boolean; fixed?: boolean; in?: string; json?: boolean },
+ opts: { ignoreCase?: boolean; fixed?: boolean; in?: string; json?: boolean; refresh?: boolean },
) => {
+ await refreshBefore(dir, opts);
const globalOpts = program.opts<{ dir?: string }>();
if (readWorkspace(resolve(dir), globalOpts.dir)) {
runWorkspaceGrep(resolve(dir), globalOpts.dir, pattern, {
@@ -391,7 +426,8 @@ program
.argument("[dir]", "repository root", ".")
.option("--max-dirs <n>", "max directory entries shown, rest counted into dropped (default 16)")
.option("--json", "output as JSON")
- .action(async (dir: string, opts: { json?: boolean; maxDirs?: string }) => {
+ .option(...NO_REFRESH_FLAG)
+ .action(async (dir: string, opts: { json?: boolean; maxDirs?: string; refresh?: boolean }) => {
const root = resolve(dir);
const globalOpts = program.opts<{ dir?: string }>();
let maxDirsW: number | undefined;
@@ -404,6 +440,7 @@ program
}
maxDirsW = n;
}
+ await refreshBefore(dir, opts); // after arg validation: a bad flag shouldn't cost a rebuild
if (!opts.json && readWorkspace(root, globalOpts.dir)) {
runWorkspaceMap(root, globalOpts.dir, { maxDirs: maxDirsW });
return;
diff --git a/src/engine.ts b/src/engine.ts
index 4526613c..d401e7c4 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -41,6 +41,8 @@ export interface GraphRunOptions {
llm?: boolean;
/** Max files summarized in parallel during the LLM pass. */
concurrency?: number;
+ /** Replay unchanged files from the extraction cache (default true). */
+ reuse?: boolean;
onProgress?: GraphBuildOptions["onProgress"];
}
@@ -83,6 +85,7 @@ export class Graft {
contextDir: this.cfg.contextDir,
summarizer: opts.llm ? this.cruxSummarizer() : undefined,
concurrency: opts.concurrency,
+ reuse: opts.reuse,
onProgress: opts.onProgress,
});
}
diff --git a/src/graph/build.ts b/src/graph/build.ts
index e885f0db..3546a015 100644
--- a/src/graph/build.ts
+++ b/src/graph/build.ts
@@ -6,12 +6,27 @@
* 2. Parse each with tree-sitter and emit one NodeV1 per definition.
* 3. Write a sorted graph.json.
* Edges (M2) and LLM summary/crux (M3) layer onto this without changing it.
+ *
+ * Step 2 is memoized per file (`extract-cache.ts`): a file whose bytes haven't
+ * moved replays its last parse instead of re-running tree-sitter, so a rebuild
+ * costs ~the files that changed. Everything after extraction still runs over the
+ * whole node set, so an incremental build's output is byte-identical to a cold
+ * one — the invariant `test/graph-incremental.test.ts` pins down.
*/
import { readFileSync } from "node:fs";
import { basename, dirname, relative, resolve, sep } from "node:path";
import { walkDir } from "../ingest/fs.js";
import { contextDirFor, ensureGitignored } from "../context/node-file.js";
import { extractFile, languageOf, type Language, type RawEdge } from "./extract.js";
+import { contentHash } from "../util/id.js";
+import {
+ emptyExtractCache,
+ readExtractCache,
+ writeExtractCache,
+ type ExtractEntry,
+} from "./extract-cache.js";
+import { writeFingerprint } from "./fingerprint.js";
+import { listSourceStats } from "./source-files.js";
import { resolveEdges, type GoModule } from "./resolve.js";
import { enrichGraph, type EnrichStats } from "./enrich.js";
import { readGraph, writeGraph, wiringPath } from "./write.js";
@@ -21,6 +36,8 @@ import { discoverScopes, scopeOf } from "./scopes.js";
import type { GraphV1, Kind, NodeV1, Relation, ScopeV1 } from "./types.js";
import type { CruxSummarizer } from "../ai/crux.js";
+export { listSourceFiles } from "./source-files.js";
+
/** Minimum non-file node count for a discovered sub-scope to stand on its own
* (over-split guard 3). A scope with fewer nodes than this is folded into the
* root scope — node counts aren't known until after the graph is assembled,
@@ -49,6 +66,9 @@ function applyMinSubstanceGuard(scopes: ScopeV1[], nodes: NodeV1[]): ScopeV1[] {
export interface GraphBuildOptions {
/** Override the output dir (default: `<root>/.context`). */
contextDir?: string;
+ /** Replay unchanged files from the extraction cache instead of re-parsing them
+ * (default true). False forces a cold parse of the whole repo. */
+ reuse?: boolean;
/** Run the Tier-2 LLM meaning pass. Absent → Tier-1 only (cache is still preserved). */
summarizer?: CruxSummarizer;
/** Max files summarized in parallel during the Tier-2 pass. Default is set in enrich. */
@@ -67,6 +87,10 @@ export interface GraphBuildResult {
/** Per-file wiring cards written (Tier-2 passive surface). */
cards: number;
files: number;
+ /** Files re-parsed this run (the rest were replayed from the extraction cache). */
+ parsed: number;
+ /** Files replayed from the extraction cache. */
+ reused: number;
nodes: number;
edges: number;
byKind: Record<Kind, number>;
@@ -76,11 +100,6 @@ export interface GraphBuildResult {
errors: string[];
}
-/** The source files a graph build parses: supported languages, minus the output dir. */
-export function listSourceFiles(root: string, outDir: string): string[] {
- return walkDir(root).filter((f) => !f.startsWith(outDir) && languageOf(f) !== null);
-}
-
/** Every Go module in the repo: each `go.mod`'s declared `module` path and the repo
* directory it lives in (posix, `.` for the root). Found anywhere in the tree, so a
* monorepo whose module is in a subdir (e.g. `backend/go.mod`) resolves too. Lets edge
@@ -107,7 +126,7 @@ export async function buildGraph(
): Promise<GraphBuildResult> {
const root = resolve(dir);
const outDir = contextDirFor(root, opts.contextDir);
- const files = listSourceFiles(root, outDir);
+ const files = listSourceStats(root, outDir);
const discoveredScopes = discoverScopes(root);
const nodes: NodeV1[] = [];
@@ -116,28 +135,85 @@ export async function buildGraph(
const langs = new Set<Language>();
const errors: string[] = [];
- files.forEach((file, i) => {
- const rel = relative(root, file);
+ // Tier-1 memo: unchanged files replay their last parse. `entries` is rebuilt
+ // from scratch each run and keyed only by files currently on disk, so deletions
+ // fall out of both the cache and the fingerprint with no separate pruning pass.
+ const priorExtract = opts.reuse === false ? emptyExtractCache() : readExtractCache(outDir);
+ const entries: Record<string, ExtractEntry> = {};
+ // The Tier-2 pass reads source text for any node it must summarize, including
+ // one in a file we didn't re-parse — so when a summarizer is in play, read
+ // every file. Reading is ~0.05ms/file; parsing is the ~4.6ms we're skipping.
+ const needAllSources = !!opts.summarizer;
+ let parsed = 0;
+ let reused = 0;
+
+ files.forEach((f, i) => {
+ const rel = f.rel;
opts.onProgress?.({ phase: "parse", index: i, total: files.length, file: rel });
- const lang = languageOf(file)!;
- let source: string;
- try {
- source = readFileSync(file, "utf8");
- } catch (err) {
- errors.push(`${rel}: ${err instanceof Error ? err.message : String(err)}`);
+ const lang = languageOf(f.abs)!;
+ const cached = priorExtract.files[rel];
+ // An entry that failed last time never takes the stat fast path: a `chmod`
+ // that makes the file readable again changes neither size nor mtime, so
+ // trusting the stat would keep it broken until someone edited it.
+ const unchanged = !!cached && !cached.error && cached.size === f.size && cached.mtimeMs === f.mtimeMs;
+
+ let source: string | null = null;
+ if (!unchanged || needAllSources) {
+ try {
+ source = readFileSync(f.abs, "utf8");
+ } catch (err) {
+ const message = `${rel}: ${err instanceof Error ? err.message : String(err)}`;
+ errors.push(message);
+ // Record it anyway (with the stat we do have) so the freshness probe's
+ // fast path doesn't report this file as new on every single query.
+ entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash: "", nodes: [], rawEdges: [], error: message };
+ return;
+ }
+ }
+
+ // A stat mismatch is only a *suspicion*; confirm by bytes so a touch, or a
+ // checkout that restores identical content, still replays the cache.
+ const hash = source === null ? cached!.hash : contentHash(source);
+ if (cached && hash === cached.hash) {
+ entries[rel] = { ...cached, size: f.size, mtimeMs: f.mtimeMs };
+ if (source !== null) sources.set(rel, source);
+ reused++;
+ if (cached.error) {
+ errors.push(cached.error); // this file failed to parse last time too
+ return;
+ }
+ nodes.push(...cached.nodes);
+ rawEdges.push(...cached.rawEdges);
+ langs.add(lang);
return;
}
+
+ parsed++;
try {
- const { nodes: fileNodes, rawEdges: fileEdges } = extractFile(rel, source, lang);
+ const { nodes: fileNodes, rawEdges: fileEdges } = extractFile(rel, source!, lang);
nodes.push(...fileNodes);
rawEdges.push(...fileEdges);
- sources.set(rel, source);
+ sources.set(rel, source!);
langs.add(lang);
+ entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash, nodes: fileNodes, rawEdges: fileEdges };
} catch (err) {
- errors.push(`${rel}: parse failed — ${err instanceof Error ? err.message : String(err)}`);
+ const message = `${rel}: parse failed — ${err instanceof Error ? err.message : String(err)}`;
+ errors.push(message);
+ entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash, nodes: [], rawEdges: [], error: message };
}
});
+ // Persist the memo BEFORE enrichment, because `enrichGraph` mutates these very
+ // node objects (summary/crux/summary_state) and the cache must only ever hold
+ // pristine Tier-1 output — otherwise a replayed node would arrive pre-enriched
+ // and a cold build and an incremental build could disagree. The meaning layer
+ // has its own cache (wiring.json itself, keyed on body_hash); this one is
+ // strictly about not re-parsing.
+ const memoWritten = writeExtractCache(outDir, {
+ ...emptyExtractCache(),
+ files: entries,
+ });
+
const edges = resolveEdges(nodes, rawEdges, { goModules: readGoModules(root) });
// graph.json is its own Tier-2 cache: fold in the prior meaning layer so an
@@ -172,6 +248,11 @@ export async function buildGraph(
// The graph is a local, regenerable cache — make sure git ignores it. Runs on
// every build (cheap, idempotent), so a fresh clone's first build self-ignores.
ensureGitignored(root, outDir);
+ // The freshness fingerprint claims "the graph on disk describes these exact
+ // bytes", so it may only be written now that wiring.json is actually there —
+ // and only if the memo it projects from made it to disk. If either write fails
+ // the next probe reports drift and rebuilds, which is the safe direction.
+ if (memoWritten) writeFingerprint(outDir, entries);
// `ask`'s token/IDF sidecar — moves per-query corpus tokenization to build
// time (~45% of query time on a 32k-node graph, profiled). Lives in the
// cache dir; `ask` falls back to live tokenization when it's absent/stale.
@@ -207,6 +288,8 @@ export async function buildGraph(
graphPath,
cards: cardStats.written,
files: files.length,
+ parsed,
+ reused,
nodes: nodes.length,
edges: edges.length,
byKind,
diff --git a/src/graph/cards.ts b/src/graph/cards.ts
index c58e78b6..3fe4ead3 100644
--- a/src/graph/cards.ts
+++ b/src/graph/cards.ts
@@ -143,6 +143,14 @@ function pruneEmptyDirs(outDir: string): void {
if (existsSync(outDir)) visit(outDir);
}
+function readIfExists(path: string): string | null {
+ try {
+ return readFileSync(path, "utf8");
+ } catch {
+ return null;
+ }
+}
+
/**
* Write one wiring card per source file into `outDir`, mirroring the source tree,
* and prune cards whose source no longer exists. Returns what changed.
@@ -164,7 +172,12 @@ export function writeCards(graph: GraphV1, outDir: string): CardStats {
const symbols = group.filter((n) => n.kind !== "file");
const cardPath = cardPathFor(outDir, sourcePath);
mkdirSync(dirname(cardPath), { recursive: true });
- writeFileSync(cardPath, renderCard(sourcePath, fileNode, symbols, concepts.get(sourcePath) ?? []));
+ const rendered = renderCard(sourcePath, fileNode, symbols, concepts.get(sourcePath) ?? []);
+ // Skip identical rewrites. Cards are a pure projection, so most of them are
+ // unchanged on a rebuild — and now that a rebuild can run before any query
+ // (graph/refresh.ts), churning every card's mtime would wake editors and file
+ // watchers on files that didn't actually change.
+ if (readIfExists(cardPath) !== rendered) writeFileSync(cardPath, rendered);
written.add(cardPath);
files.push({ card: relative(outDir, cardPath), path: sourcePath, symbols: symbols.length });
}
diff --git a/src/graph/extract-cache.ts b/src/graph/extract-cache.ts
new file mode 100644
index 00000000..9ec53813
--- /dev/null
+++ b/src/graph/extract-cache.ts
@@ -0,0 +1,103 @@
+/**
+ * Per-file memo for Tier-1 extraction — `<outDir>/.cache/extract.json`.
+ *
+ * `extractFile` is pure and file-local (`rel`, `source`, `lang` → `{nodes,
+ * rawEdges}`), which is the whole trick: an unchanged file's parse result can be
+ * replayed from disk instead of re-running tree-sitter. That turns
+ * {@link buildGraph} from "always re-parse the repo" (~4.6ms/file) into "re-parse
+ * only what moved", which is what makes a rebuild cheap enough to run *before*
+ * every query (see `graph/refresh.ts`).
+ *
+ * Everything downstream of extraction (edge resolution, enrichment, the graph
+ * write, the ask sidecar, cards) still runs over the whole merged node set, so no
+ * other invariant changes — an incremental build must produce a byte-identical
+ * `wiring.json` to a cold one.
+ *
+ * Crucially the cached nodes keep `body_text`: `writeGraph` strips it before
+ * serializing, so `wiring.json` can never be the reuse source — the ask sidecar
+ * needs a body for every node, including the ones we didn't re-parse.
+ *
+ * Lives under `.cache/` (gitignored, regenerate-anytime) next to `ask-index.json`
+ * and `summaries.json`. Two things invalidate the whole file: a bump of
+ * {@link CACHE_VERSION}, and a change to the extractor module itself (stamped by
+ * its mtime+size, so an npm upgrade or a local rebuild drops stale parses without
+ * anyone remembering to bump anything).
+ */
+import { statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { CACHE_DIR } from "../context/node-file.js";
+import { readJson, writeJsonAtomic } from "../util/state.js";
+import type { RawEdge } from "./extract.js";
+import type { NodeV1 } from "./types.js";
+
+/** Bump when the on-disk shape below changes. */
+const CACHE_VERSION = 1;
+const EXTRACT_CACHE_FILE = "extract.json";
+
+export interface ExtractEntry {
+ size: number;
+ mtimeMs: number;
+ /** sha256 of the file's bytes — the same value as its `kind:"file"` node's `body_hash`. */
+ hash: string;
+ nodes: NodeV1[];
+ rawEdges: RawEdge[];
+ /** Set when this file couldn't be read or parsed. The entry exists anyway so the
+ * freshness probe doesn't flag the file as new on every query; replaying it
+ * re-reports the same error and contributes no nodes, exactly as a cold build
+ * would. */
+ error?: string;
+}
+
+export interface ExtractCache {
+ version: number;
+ /** Identity of the extractor that produced these entries. */
+ extractor: string;
+ /** repo-relative source path → its last parse. */
+ files: Record<string, ExtractEntry>;
+}
+
+export function extractCachePath(outDir: string): string {
+ return join(outDir, CACHE_DIR, EXTRACT_CACHE_FILE);
+}
+
+/** `mtime:size` of the extractor module, or `"unknown"` when it can't be stat'd.
+ * Resolved by rewriting this module's own URL, so it works both in `dist/` (.js)
+ * and under tsx (.ts) without knowing which layout we're in. */
+function extractorStamp(): string {
+ try {
+ const url = import.meta.url.replace(/extract-cache\.(c|m)?([jt]s)$/, "extract.$1$2");
+ if (url === import.meta.url) return "unknown";
+ const s = statSync(fileURLToPath(url));
+ return `${s.mtimeMs}:${s.size}`;
+ } catch {
+ return "unknown";
+ }
+}
+
+export function emptyExtractCache(): ExtractCache {
+ return { version: CACHE_VERSION, extractor: extractorStamp(), files: {} };
+}
+
+/** The cache for `outDir`, or an empty one when it's absent, unparseable, or was
+ * written by a different cache version / extractor build. */
+export function readExtractCache(outDir: string): ExtractCache {
+ const c = readJson<ExtractCache>(extractCachePath(outDir));
+ const stamp = extractorStamp();
+ if (!c || c.version !== CACHE_VERSION || c.extractor !== stamp || typeof c.files !== "object") {
+ return emptyExtractCache();
+ }
+ return { version: c.version, extractor: c.extractor, files: c.files ?? {} };
+}
+
+/** Best-effort write — a full graph is already on disk by the time this runs, so
+ * an unwritable cache dir must never fail the build (it only costs the next
+ * build its reuse). Returns false when the write failed. */
+export function writeExtractCache(outDir: string, cache: ExtractCache): boolean {
+ try {
+ writeJsonAtomic(extractCachePath(outDir), cache, true);
+ return true;
+ } catch {
+ return false;
+ }
+}
diff --git a/src/graph/fingerprint.ts b/src/graph/fingerprint.ts
new file mode 100644
index 00000000..b2603583
--- /dev/null
+++ b/src/graph/fingerprint.ts
@@ -0,0 +1,126 @@
+/**
+ * The cheap "has the working tree moved?" probe that gates the pre-query rebuild.
+ *
+ * Every graft retrieval call runs this, so it has to be ~free on the common
+ * unchanged path: a walk + one `stat` per source file, no reads, no parsing.
+ * Measured at ~3ms for 280 files. Only files whose `(size, mtimeMs)` disagree
+ * with the last build's record get read and hashed, which is what keeps a `touch`
+ * or a `git checkout` of identical bytes from triggering a pointless rebuild.
+ *
+ * Note graft has no notion of git here (it never shells out to git, never reads
+ * `.git`): drift is measured against the bytes in the working tree, so an
+ * uncommitted, staged, or committed edit all look the same — which is the point.
+ *
+ * `<outDir>/.cache/fingerprint.json` is a projection of the extraction cache
+ * (`extract-cache.ts`) minus the parse results, written by the same build. Keeping
+ * it separate means the probe reads ~10KB instead of the multi-MB parse cache. The
+ * two can only ever disagree by one sidecar going missing, and both directions
+ * degrade safely: no fingerprint → "unknown, rebuild"; no parse cache → the
+ * rebuild is just cold.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CACHE_DIR } from "../context/node-file.js";
+import { contentHash } from "../util/id.js";
+import { readJson, writeJsonAtomic } from "../util/state.js";
+import type { ExtractEntry } from "./extract-cache.js";
+import { listSourceStats } from "./source-files.js";
+
+const FINGERPRINT_FILE = "fingerprint.json";
+const FINGERPRINT_VERSION = 1;
+
+/** `[size, mtimeMs, hash]` — positional to keep the file small. */
+type Print = [number, number, string];
+
+export interface Fingerprint {
+ version: number;
+ files: Record<string, Print>;
+}
+
+/** What moved since the last build. Empty in all three arrays = nothing to do. */
+export interface Drift {
+ /** Recorded files whose bytes differ now. */
+ changed: string[];
+ /** Source files with no record — new, or never indexed. */
+ added: string[];
+ /** Recorded files that are gone from disk. */
+ removed: string[];
+}
+
+export function fingerprintPath(outDir: string): string {
+ return join(outDir, CACHE_DIR, FINGERPRINT_FILE);
+}
+
+export function readFingerprint(outDir: string): Fingerprint | null {
+ const f = readJson<Fingerprint>(fingerprintPath(outDir));
+ if (!f || f.version !== FINGERPRINT_VERSION || typeof f.files !== "object" || !f.files) return null;
+ return f;
+}
+
+/** Project the extraction cache's entries into the probe sidecar. Best-effort:
+ * the graph is already on disk when this runs, so a failed write costs the next
+ * probe its fast path and nothing more. */
+export function writeFingerprint(outDir: string, entries: Record<string, ExtractEntry>): boolean {
+ const files: Record<string, Print> = {};
+ for (const [rel, e] of Object.entries(entries)) files[rel] = [e.size, e.mtimeMs, e.hash];
+ try {
+ writeJsonAtomic(fingerprintPath(outDir), { version: FINGERPRINT_VERSION, files }, true);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export function isClean(d: Drift): boolean {
+ return d.changed.length === 0 && d.added.length === 0 && d.removed.length === 0;
+}
+
+export function driftCount(d: Drift): number {
+ return d.changed.length + d.added.length + d.removed.length;
+}
+
+/**
+ * Diff the working tree against the last build's fingerprint. Returns null when
+ * there is no fingerprint to compare against (never built, or built by a version
+ * that didn't write one) — callers should treat that as "unknown", not "clean".
+ *
+ * `GRAFT_REFRESH=hash` skips the stat fast path and hashes every file, for the
+ * rare tooling that rewrites content while preserving size and mtime.
+ */
+export function probeDrift(root: string, outDir: string): Drift | null {
+ const fp = readFingerprint(outDir);
+ if (!fp) return null;
+ const alwaysHash = process.env.GRAFT_REFRESH === "hash";
+
+ const drift: Drift = { changed: [], added: [], removed: [] };
+ const seen = new Set<string>();
+
+ for (const f of listSourceStats(root, outDir)) {
+ seen.add(f.rel);
+ const print = fp.files[f.rel];
+ if (!print) {
+ drift.added.push(f.rel);
+ continue;
+ }
+ const [size, mtimeMs, hash] = print;
+ if (!alwaysHash && size === f.size && mtimeMs === f.mtimeMs) continue;
+ // Suspect: confirm by bytes, so a touch (or a checkout that restores the
+ // same content) doesn't cost a rebuild.
+ let now: string;
+ try {
+ now = contentHash(readFileSync(f.abs, "utf8"));
+ } catch {
+ continue; // unreadable right now — leave it to the next probe
+ }
+ if (now !== hash) drift.changed.push(f.rel);
+ }
+
+ for (const rel of Object.keys(fp.files)) {
+ if (!seen.has(rel)) drift.removed.push(rel);
+ }
+
+ drift.changed.sort();
+ drift.added.sort();
+ drift.removed.sort();
+ return drift;
+}
diff --git a/src/graph/load.ts b/src/graph/load.ts
index ddcc1ac4..c07eb42d 100644
--- a/src/graph/load.ts
+++ b/src/graph/load.ts
@@ -98,3 +98,18 @@ export function loadAskIndexCached(outDir: string): AskIndex | null {
__parseCount.askIndex++;
});
}
+
+/**
+ * Drop the cached graph + sidecar for `outDir`, forcing the next load to re-read.
+ *
+ * The `(mtimeMs, size)` key above is a good invalidator for a build that happened
+ * in *another* process, but not for one this process just performed: the
+ * pre-query auto-refresh (`refresh.ts`) rewrites the graph and then immediately
+ * queries it, and on a filesystem with coarse mtime resolution a same-tick rewrite
+ * of the same size would be served from the stale entry. Callers that rebuild must
+ * therefore invalidate explicitly rather than trust the clock.
+ */
+export function invalidateGraphCaches(outDir: string): void {
+ graphCache.delete(wiringPath(outDir));
+ askIndexCache.delete(askIndexPath(outDir));
+}
diff --git a/src/graph/refresh.ts b/src/graph/refresh.ts
new file mode 100644
index 00000000..2a699a2c
--- /dev/null
+++ b/src/graph/refresh.ts
@@ -0,0 +1,179 @@
+/**
+ * `ensureFreshGraph` — the pre-query gate that keeps retrieval honest.
+ *
+ * Freshness used to be someone else's job: the Claude Code `Stop` hook spawned a
+ * background `graft build` *after* the turn ended, so every query an agent made
+ * between its first edit and the end of the turn answered from a graph that no
+ * longer matched the file it had just changed. Worse, an edit made outside the
+ * agent (your editor, a branch switch, a stash) set no `dirty` flag at all, so
+ * nothing ever triggered a resync.
+ *
+ * So freshness moves into the query path: every retrieval call probes the working
+ * tree (`fingerprint.ts`, ~3ms) and, when something moved, rebuilds the structural
+ * graph before answering. Properties worth keeping:
+ *
+ * - **$0 and offline.** Tier-1 only — never a summarizer, never `--deep`. Same
+ * money guard `claude/sync-run.ts` carries: auto-anything must not spend money.
+ * - **Never fatal.** A failed refresh degrades to answering from the graph on
+ * disk. A query that works today must not start failing because a rebuild did.
+ * - **Never a stampede.** It takes the same `graft/.cache/.sync.lock` the
+ * background sync uses, so concurrent MCP calls and the Stop hook can't pile up
+ * rebuilds on top of each other.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { contextDirFor } from "../context/node-file.js";
+import { acquireLockIn, computeStats, patchStats, readStats, releaseLockIn } from "../util/state.js";
+import { CACHE_DIR } from "../context/node-file.js";
+import { buildGraph } from "./build.js";
+import { driftCount, isClean, probeDrift, type Drift } from "./fingerprint.js";
+import { invalidateGraphCaches } from "./load.js";
+import { readGraph, wiringPath } from "./write.js";
+
+/** How long to wait for another process's in-flight rebuild before giving up and
+ * answering from the current graph. Long enough to ride out a small repo's build,
+ * short enough that a tool call never feels hung. */
+const LOCK_WAIT_MS = 2000;
+const LOCK_POLL_MS = 50;
+
+export interface RefreshResult {
+ /** True when the graph on disk was rebuilt by this call. */
+ refreshed: boolean;
+ /** What the probe found, when it ran and found something. */
+ drift?: Drift;
+ /** One-line explanation for the agent/user, when there's something worth saying. */
+ note?: string;
+}
+
+export interface RefreshOptions {
+ contextDir?: string;
+ /** Skip everything (the `--no-refresh` flag). */
+ disabled?: boolean;
+}
+
+const CLEAN: RefreshResult = { refreshed: false };
+
+/** Env kill switch, for CI or anyone who wants queries to never write. */
+function envDisabled(): boolean {
+ const v = process.env.GRAFT_NO_REFRESH;
+ return v !== undefined && v !== "" && v !== "0" && v !== "false";
+}
+
+function sleep(ms: number): Promise<void> {
+ return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Wait out someone else's rebuild, then take the lock. False when we couldn't. */
+async function waitForLock(cache: string): Promise<boolean> {
+ const deadline = Date.now() + LOCK_WAIT_MS;
+ for (;;) {
+ if (acquireLockIn(cache)) return true;
+ if (Date.now() >= deadline) return false;
+ await sleep(LOCK_POLL_MS);
+ }
+}
+
+/**
+ * Rebuild `root`'s structural graph if the working tree has moved since the last
+ * build. Cheap and side-effect-free when nothing changed, which is the usual case.
+ *
+ * `root` is the repository root (the same value the query itself is given), not
+ * the context dir.
+ */
+export async function ensureFreshGraph(root: string, opts: RefreshOptions = {}): Promise<RefreshResult> {
+ if (opts.disabled || envDisabled()) return CLEAN;
+ try {
+ const dir = resolve(root);
+ const outDir = contextDirFor(dir, opts.contextDir);
+ // Nothing built yet: the caller's own "no graph — run graft build" message is
+ // the right answer. Auto-building a whole repo under a query is a surprise,
+ // and it's the one case where the user hasn't opted into graft at all yet.
+ if (!existsSync(wiringPath(outDir))) return CLEAN;
+
+ // null = no fingerprint at all: a graph built before this mechanism existed,
+ // or by a different extractor build. Rebuild once — that lays the fingerprint
+ // down, so it costs exactly one build, not one per query.
+ const drift = probeDrift(dir, outDir);
+ if (drift && isClean(drift)) return CLEAN;
+
+ // On the default layout this is `<root>/graft/.cache/.sync.lock`, the very file
+ // the Claude Code hooks lock — so this refresh and the background sync can
+ // never rebuild at the same time.
+ const lockCache = join(outDir, CACHE_DIR);
+ if (!(await waitForLock(lockCache))) {
+ return {
+ refreshed: false,
+ drift: drift ?? undefined,
+ note: "a graph rebuild is already in flight — answering from the current graph",
+ };
+ }
+ try {
+ // Tier-1 only: no summarizer, so no LLM call and no network, ever.
+ await buildGraph(dir, { contextDir: opts.contextDir });
+ invalidateGraphCaches(outDir);
+ syncStats(dir, outDir);
+ return { refreshed: true, drift: drift ?? undefined };
+ } finally {
+ releaseLockIn(lockCache);
+ }
+ } catch (err) {
+ // Answering from a slightly stale graph beats failing the query.
+ return { refreshed: false, note: `graph refresh skipped: ${err instanceof Error ? err.message : String(err)}` };
+ }
+}
+
+/** Mirror what the background sync writes, so the statusline flips to `✓ synced`
+ * mid-turn instead of showing `⚠ stale` until the turn ends. Best-effort: this is
+ * a display cache, and the stats file only exists in a hooked-up repo anyway. */
+function syncStats(dir: string, outDir: string): void {
+ try {
+ if (!readStats(dir)) return; // no hooks in this repo — nothing reads it
+ const w = readGraph(wiringPath(outDir));
+ if (!w) return;
+ patchStats(dir, {
+ dirty: false,
+ staleCount: 0,
+ syncing: false,
+ syncedAt: new Date().toISOString(),
+ ...computeStats(w),
+ });
+ } catch {
+ /* display-only — never let this fail a query */
+ }
+}
+
+/**
+ * Workspace variant: refresh each child repo's own graph (a workspace parent holds
+ * an index, never nodes). Children are independent, but they're refreshed in
+ * sequence — a fan-out of concurrent tree-sitter builds would spike CPU on the
+ * very path that's supposed to feel free.
+ */
+export async function ensureFreshChildren(
+ root: string,
+ children: string[],
+ opts: RefreshOptions = {},
+): Promise<RefreshResult> {
+ if (opts.disabled || envDisabled()) return CLEAN;
+ const refreshedIn: string[] = [];
+ let files = 0;
+ for (const child of children) {
+ const r = await ensureFreshGraph(resolve(root, child), opts);
+ if (!r.refreshed) continue;
+ refreshedIn.push(child);
+ files += r.drift ? driftCount(r.drift) : 0;
+ }
+ if (!refreshedIn.length) return CLEAN;
+ return {
+ refreshed: true,
+ note: `refreshed ${refreshedIn.join(", ")} (${files || "?"} file${files === 1 ? "" : "s"} changed) before answering`,
+ };
+}
+
+/** The one-line note a CLI/MCP surface prints when a refresh actually happened.
+ * Null when there's nothing to say (the overwhelmingly common case). */
+export function refreshNote(r: RefreshResult): string | null {
+ if (r.note) return `[graft] ${r.note}`;
+ if (!r.refreshed) return null;
+ const n = r.drift ? driftCount(r.drift) : 0;
+ return `[graft] refreshed the graph (${n || "?"} file${n === 1 ? "" : "s"} changed) before answering`;
+}
diff --git a/src/graph/source-files.ts b/src/graph/source-files.ts
new file mode 100644
index 00000000..474e7219
--- /dev/null
+++ b/src/graph/source-files.ts
@@ -0,0 +1,46 @@
+/**
+ * The file set a graph build parses, and its stat metadata.
+ *
+ * Split out of `build.ts` so the freshness probe (`fingerprint.ts`) can enumerate
+ * exactly the same files without importing the builder (which would be an import
+ * cycle: build → fingerprint → build). `build.ts` re-exports
+ * {@link listSourceFiles} so its existing importers are unaffected.
+ */
+import { statSync } from "node:fs";
+import { relative } from "node:path";
+import { walkDir } from "../ingest/fs.js";
+import { languageOf } from "./extract.js";
+
+/** The source files a graph build parses: supported languages, minus the output dir. */
+export function listSourceFiles(root: string, outDir: string): string[] {
+ return walkDir(root).filter((f) => !f.startsWith(outDir) && languageOf(f) !== null);
+}
+
+export interface SourceStat {
+ /** Absolute path. */
+ abs: string;
+ /** `relative(root, abs)` — exactly the form `buildGraph` uses for node ids and
+ * `checkGraph` diffs against, so cache keys and ids can never disagree. */
+ rel: string;
+ size: number;
+ mtimeMs: number;
+}
+
+/**
+ * {@link listSourceFiles} plus each file's `(size, mtimeMs)` — the currency of
+ * both the freshness probe and the extraction cache. Files that vanish between
+ * the walk and the stat are dropped (same fail-soft posture as `walkDir`).
+ */
+export function listSourceStats(root: string, outDir: string): SourceStat[] {
+ const out: SourceStat[] = [];
+ for (const abs of listSourceFiles(root, outDir)) {
+ let s: { size: number; mtimeMs: number };
+ try {
+ s = statSync(abs);
+ } catch {
+ continue;
+ }
+ out.push({ abs, rel: relative(root, abs), size: s.size, mtimeMs: s.mtimeMs });
+ }
+ return out;
+}
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index f2edf059..df7f3845 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -54,8 +54,14 @@ export function startMcpServer(root: string, dirOverride?: string): void {
if (isNotification) return;
const name = String(params?.name ?? '');
const args = (params?.arguments ?? {}) as Record<string, unknown>;
- const r = callTool(root, name, args, dirOverride);
- reply(id, { content: [{ type: 'text', text: r.text }], isError: r.isError });
+ // Async because a tool call may rebuild the graph first (see
+ // graph/refresh.ts). `callTool` absorbs its own errors, so the only thing
+ // that can reject here is a bug — surface it as a JSON-RPC error rather
+ // than an unhandled rejection that kills the server.
+ callTool(root, name, args, dirOverride).then(
+ (r) => reply(id, { content: [{ type: 'text', text: r.text }], isError: r.isError }),
+ (err) => replyError(id, -32603, err instanceof Error ? err.message : String(err)),
+ );
return;
}
default:
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 5637a153..3bd472e8 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -7,6 +7,7 @@ import { formatAsk, skeleton, formatSkeleton } from '../ask/ask.js';
import { formatCheckReport } from '../context/check.js';
import { formatGraphCheckReport } from '../graph/check.js';
import { loadGraphCached } from '../graph/load.js';
+import { ensureFreshChildren, ensureFreshGraph, refreshNote } from '../graph/refresh.js';
import { contextDirFor } from '../context/node-file.js';
import { resolveSymbol, edgeWalk, type Direction, type EdgeHit } from '../graph/traverse.js';
import { callersSavings, headerOf, hitLine, looseNoteFor } from '../graph/traverse-cli.js';
@@ -195,18 +196,44 @@ function callWorkspaceTool(
}
}
-export function callTool(
+/** Tools whose whole job is to REPORT drift. Rebuilding first would make
+ * `graft_check` answer about a graph it just fixed, i.e. always "OK". */
+const NO_REFRESH_TOOLS = new Set(['graft_check']);
+
+export async function callTool(
root: string,
name: string,
args: Record<string, unknown>,
dirOverride?: string,
-): { text: string; isError: boolean } {
+): Promise<{ text: string; isError: boolean }> {
try {
- if (readWorkspace(root, dirOverride)) {
- const fed = callWorkspaceTool(root, dirOverride, name, args);
- if (fed) return fed;
+ const ws = readWorkspace(root, dirOverride);
+ // Freshness first: an answer that cites file:line has to be about the code as
+ // it is right now, including edits nobody has committed (or even saved through
+ // this agent). ~3ms when nothing moved; a structural, $0 rebuild when it did.
+ let note: string | null = null;
+ if (!NO_REFRESH_TOOLS.has(name)) {
+ const r = ws
+ ? await ensureFreshChildren(root, ws.children, { contextDir: dirOverride })
+ : await ensureFreshGraph(root, { contextDir: dirOverride });
+ note = refreshNote(r);
}
- switch (name) {
+ const fed = ws ? callWorkspaceTool(root, dirOverride, name, args) : null;
+ const res = fed ?? callSingleTool(root, name, args, dirOverride);
+ return note ? { ...res, text: `${note}\n${res.text}` } : res;
+ } catch (err) {
+ return { text: err instanceof Error ? err.message : String(err), isError: true };
+ }
+}
+
+/** The single-graph path: every tool, answered from one repo's graph. */
+function callSingleTool(
+ root: string,
+ name: string,
+ args: Record<string, unknown>,
+ dirOverride?: string,
+): { text: string; isError: boolean } {
+ switch (name) {
case 'graft_ask': {
const query = String(args.query ?? '');
if (!query) return { text: 'graft_ask requires a query', isError: true };
@@ -279,10 +306,7 @@ export function callTool(
const map = buildRepoMap(w, { maxDirs });
return { text: formatRepoMap(map), isError: false };
}
- default:
- return { text: `unknown tool: ${name}`, isError: true };
- }
- } catch (err) {
- return { text: err instanceof Error ? err.message : String(err), isError: true };
+ default:
+ return { text: `unknown tool: ${name}`, isError: true };
}
}
diff --git a/src/util/state.ts b/src/util/state.ts
new file mode 100644
index 00000000..8f644170
--- /dev/null
+++ b/src/util/state.ts
@@ -0,0 +1,106 @@
+/**
+ * The `graft/.cache/` sidecar state: the statusline's stats snapshot and the
+ * build lock that serializes rebuilds.
+ *
+ * Lives in `util/` rather than `claude/` because two very different callers need
+ * it: the Claude Code hooks (which flip `dirty` on an edit and clear it after a
+ * background sync) and the graph's own pre-query auto-refresh
+ * (`graph/refresh.ts`), which must take the same lock so the two never rebuild
+ * on top of each other. `claude/state.ts` re-exports all of this, so nothing
+ * outside had to change when it moved.
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import type { GraphV1 } from '../graph/types.js';
+
+export interface Stats {
+ nodeCount: number; edgeCount: number; languages: string[];
+ totalCount: number; readyCount: number;
+ staleCount: number; dirty: boolean; syncing: boolean;
+ syncedAt: string | null; lastFile: string | null;
+}
+
+export const LOCK_STALE_MS = 300000;
+
+export function emptyStats(): Stats {
+ return { nodeCount: 0, edgeCount: 0, languages: [], totalCount: 0, readyCount: 0,
+ staleCount: 0, dirty: false, syncing: false, syncedAt: null, lastFile: null };
+}
+
+const LOCK_FILE = '.sync.lock';
+
+export function cacheDir(projectDir: string): string { return join(projectDir, 'graft', '.cache'); }
+function statsPath(d: string): string { return join(cacheDir(d), 'stats.json'); }
+
+export function readJson<T>(p: string): T | null {
+ try { return JSON.parse(readFileSync(p, 'utf8')) as T; } catch { return null; }
+}
+/** Atomic write via tmp+rename. `compact` drops the indentation, for the caches
+ * only a machine ever opens — it's ~30% of the bytes on a big, deep object. */
+export function writeJsonAtomic(p: string, value: unknown, compact = false): void {
+ mkdirSync(dirname(p), { recursive: true });
+ const tmp = `${p}.${process.pid}.tmp`;
+ writeFileSync(tmp, compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));
+ renameSync(tmp, p);
+}
+
+export function readStats(d: string): Stats | null { return readJson<Stats>(statsPath(d)); }
+export function writeStats(d: string, s: Stats): void { writeJsonAtomic(statsPath(d), s); }
+// Best-effort read-modify-write; not atomic across concurrent processes, but acceptable
+// for episodic hook writes (worst case is a lost update, not corruption).
+export function patchStats(d: string, patch: Partial<Stats>): Stats {
+ const next: Stats = { ...(readStats(d) ?? emptyStats()), ...patch };
+ writeStats(d, next);
+ return next;
+}
+
+export function acquireLock(d: string): boolean {
+ return acquireLockIn(cacheDir(d));
+}
+export function releaseLock(d: string): void {
+ releaseLockIn(cacheDir(d));
+}
+
+/**
+ * The lock, addressed by cache dir rather than project dir. For the default layout
+ * `<root>/graft/.cache` these are the same file, which is the point: the Claude Code
+ * hooks lock by project dir and the graph's auto-refresh locks by the context dir it
+ * is actually writing, and the two must collide so they can't rebuild at once.
+ */
+export function acquireLockIn(cache: string): boolean {
+ const p = join(cache, LOCK_FILE);
+ mkdirSync(cache, { recursive: true });
+ const payload = JSON.stringify({ pid: process.pid, at: new Date().toISOString() });
+ try {
+ writeFileSync(p, payload, { flag: 'wx' }); // atomic exclusive create
+ return true;
+ } catch (e: any) {
+ if (e?.code !== 'EEXIST') throw e;
+ let stale: boolean;
+ try { stale = Date.now() - statSync(p).mtimeMs >= LOCK_STALE_MS; } catch { stale = true; }
+ if (!stale) return false;
+ try { rmSync(p); } catch { /* another process reclaimed it */ }
+ try { writeFileSync(p, payload, { flag: 'wx' }); return true; }
+ catch (e2: any) { if (e2?.code === 'EEXIST') return false; throw e2; }
+ }
+}
+export function releaseLockIn(cache: string): void {
+ try { rmSync(join(cache, LOCK_FILE)); } catch { /* already gone */ }
+}
+
+/** The graph-derived half of {@link Stats} — everything the statusline shows that
+ * isn't drift state. Lives here so the hooks and the pre-query auto-refresh report
+ * identical numbers. */
+export function computeStats(
+ w: GraphV1,
+): Pick<Stats, 'nodeCount' | 'edgeCount' | 'languages' | 'totalCount' | 'readyCount'> {
+ const nodes = w.nodes ?? [];
+ const edges = w.edges ?? [];
+ return {
+ nodeCount: w.meta?.nodeCount ?? nodes.length,
+ edgeCount: w.meta?.edgeCount ?? edges.length,
+ languages: w.meta?.languages ?? [],
+ totalCount: nodes.length,
+ readyCount: nodes.filter((n) => n.summary_state === 'ready').length,
+ };
+}
diff --git a/test/graph-incremental.test.ts b/test/graph-incremental.test.ts
new file mode 100644
index 00000000..453cb788
--- /dev/null
+++ b/test/graph-incremental.test.ts
@@ -0,0 +1,191 @@
+/**
+ * The extraction cache's contract: replaying unchanged files must be
+ * indistinguishable from re-parsing them. Every test here is a variation on
+ * "cold build == incremental build" — because that equality is what lets a
+ * rebuild run before every query.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildGraph } from "../src/graph/build.js";
+import { readExtractCache } from "../src/graph/extract-cache.js";
+import { isClean, probeDrift, readFingerprint } from "../src/graph/fingerprint.js";
+import { readAskIndex } from "../src/ask/index-file.js";
+import { readGraph, wiringPath } from "../src/graph/write.js";
+import type { GraphV1 } from "../src/graph/types.js";
+
+const MATH = [
+ "export function add(a: number, b: number): number {",
+ " return a + b;",
+ "}",
+ "export function sub(a: number, b: number): number {",
+ " return add(a, -b);",
+ "}",
+ "",
+].join("\n");
+
+const APP = ['import { add } from "./math.js";', "export function main(): number {", " return add(1, 2);", "}", ""].join("\n");
+
+function repo(): string {
+ const d = mkdtempSync(join(tmpdir(), "graft-incr-"));
+ mkdirSync(join(d, "src"), { recursive: true });
+ writeFileSync(join(d, "src", "math.ts"), MATH);
+ writeFileSync(join(d, "src", "app.ts"), APP);
+ return d;
+}
+
+const outOf = (d: string): string => join(d, "graft");
+const wiringOf = (d: string): string => readFileSync(wiringPath(outOf(d)), "utf8");
+
+test("an incremental rebuild writes byte-identical wiring.json to a cold one", async () => {
+ const d = repo();
+ await buildGraph(d, { reuse: false });
+ const cold = wiringOf(d);
+ await buildGraph(d);
+ assert.equal(wiringOf(d), cold, "replaying cached parses must not change a single byte of the graph");
+});
+
+test("unchanged files are replayed, not re-parsed", async () => {
+ const d = repo();
+ const first = await buildGraph(d);
+ assert.equal(first.parsed, 2, "cold build parses every file");
+ assert.equal(first.reused, 0);
+
+ const second = await buildGraph(d);
+ assert.equal(second.parsed, 0, "nothing changed — nothing to parse");
+ assert.equal(second.reused, 2);
+
+ // Same content, newer mtime: the stat check misses, the hash check saves it.
+ const later = new Date(Date.now() + 5000);
+ utimesSync(join(d, "src", "math.ts"), later, later);
+ const third = await buildGraph(d);
+ assert.equal(third.parsed, 0, "a touch changes no bytes, so it must not cost a parse");
+ assert.equal(third.reused, 2);
+});
+
+test("an edit re-parses only the file that changed, and lands in the graph", async () => {
+ const d = repo();
+ await buildGraph(d);
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export function mul(a: number, b: number): number {\n return a * b;\n}\n`);
+ const r = await buildGraph(d);
+ assert.equal(r.parsed, 1);
+ assert.equal(r.reused, 1);
+ const g = readGraph(wiringPath(outOf(d))) as GraphV1;
+ assert.ok(g.nodes.some((n) => n.id === "src/math.ts#mul"), "the new symbol must be in the graph");
+
+ // ...and the result is still exactly what a cold build would produce.
+ const warm = wiringOf(d);
+ await buildGraph(d, { reuse: false });
+ assert.equal(warm, wiringOf(d));
+});
+
+test("adding and deleting files stays consistent with a cold build", async () => {
+ const d = repo();
+ await buildGraph(d);
+
+ writeFileSync(join(d, "src", "extra.ts"), "export const EXTRA = 1;\n");
+ const added = await buildGraph(d);
+ assert.equal(added.parsed, 1, "only the new file is parsed");
+ assert.equal(added.reused, 2);
+
+ rmSync(join(d, "src", "app.ts"));
+ await buildGraph(d);
+ const g = readGraph(wiringPath(outOf(d))) as GraphV1;
+ assert.ok(!g.nodes.some((n) => n.path === "src/app.ts"), "a deleted file leaves no nodes behind");
+
+ const cache = readExtractCache(outOf(d));
+ assert.ok(!("src/app.ts" in cache.files), "and no cache entry");
+ const fp = readFingerprint(outOf(d));
+ assert.ok(fp && !("src/app.ts" in fp.files), "and no fingerprint entry");
+
+ const warm = wiringOf(d);
+ await buildGraph(d, { reuse: false });
+ assert.equal(warm, wiringOf(d));
+});
+
+test("the ask sidecar still covers every node after an incremental rebuild", async () => {
+ const d = repo();
+ await buildGraph(d);
+ writeFileSync(join(d, "src", "app.ts"), `${APP}export function other(): number {\n return 7;\n}\n`);
+ await buildGraph(d);
+
+ const g = readGraph(wiringPath(outOf(d))) as GraphV1;
+ const idx = readAskIndex(outOf(d));
+ assert.ok(idx, "sidecar written");
+ // ask.ts falls back to live tokenization unless the sidecar covers every node
+ // by id — a replayed node with no body would silently degrade ranking.
+ assert.equal(idx!.docs.length, g.nodes.length);
+ const ids = new Set(idx!.docs.map((doc) => doc.id));
+ for (const n of g.nodes) assert.ok(ids.has(n.id), `sidecar missing ${n.id}`);
+ const replayed = idx!.docs.find((doc) => doc.id === "src/math.ts#add");
+ assert.ok(replayed && replayed.body.length > 0, "a replayed node must keep its body tokens");
+});
+
+test("the cache holds pristine Tier-1 output — no enrichment leaks into it", async () => {
+ const d = repo();
+ await buildGraph(d);
+ // Stamp a summary onto the graph the way a `--deep` build would, then rebuild
+ // structurally: the meaning layer must survive (it is keyed on body_hash in
+ // wiring.json) while the extraction cache stays free of it.
+ const path = wiringPath(outOf(d));
+ const g = readGraph(path) as GraphV1;
+ const target = g.nodes.find((n) => n.id === "src/math.ts#add");
+ assert.ok(target);
+ target!.summary = "adds two numbers";
+ target!.summary_state = "ready";
+ writeFileSync(path, `${JSON.stringify(g, null, 2)}\n`);
+
+ await buildGraph(d);
+ const after = readGraph(path) as GraphV1;
+ const kept = after.nodes.find((n) => n.id === "src/math.ts#add");
+ assert.equal(kept?.summary, "adds two numbers", "an unchanged body keeps its summary");
+ assert.equal(kept?.summary_state, "ready");
+
+ const cache = readExtractCache(outOf(d));
+ const cachedNode = cache.files["src/math.ts"].nodes.find((n) => n.id === "src/math.ts#add");
+ assert.ok(cachedNode);
+ assert.equal(cachedNode!.summary, null, "the parse memo must not carry meaning-layer state");
+ assert.equal(cachedNode!.summary_state, "pending", "it holds extractFile's output, pre-enrichment");
+});
+
+test("every file on disk lands in the fingerprint", async () => {
+ const d = repo();
+ await buildGraph(d);
+ const fp = readFingerprint(outOf(d));
+ assert.ok(fp);
+ assert.deepEqual(Object.keys(fp!.files).sort(), ["src/app.ts", "src/math.ts"]);
+});
+
+test("an unreadable file is still recorded, so it can't look new on every probe", async (t) => {
+ if (process.getuid?.() === 0) return t.skip("root reads anything, so chmod 000 proves nothing");
+ const d = repo();
+ const secret = join(d, "src", "secret.ts");
+ writeFileSync(secret, "export function secretFn(): number {\n return 1;\n}\n");
+ chmodSync(secret, 0o000);
+
+ const r = await buildGraph(d);
+ assert.ok(
+ r.errors.some((e) => e.startsWith("src/secret.ts:")),
+ `expected a read error for src/secret.ts, got ${JSON.stringify(r.errors)}`,
+ );
+ // The point: it IS in the fingerprint. Otherwise the probe would report it as a
+ // new file forever and every single query would trigger a rebuild.
+ const fp = readFingerprint(outOf(d));
+ assert.ok(fp && "src/secret.ts" in fp.files);
+ const drift = probeDrift(d, outOf(d));
+ assert.ok(drift && isClean(drift), `expected a clean probe, got ${JSON.stringify(drift)}`);
+
+ // And the error keeps being reported while the file stays unreadable.
+ const again = await buildGraph(d);
+ assert.ok(again.errors.some((e) => e.startsWith("src/secret.ts:")));
+
+ // A chmod changes neither size nor mtime, so recovery must not depend on the
+ // stat fast path — the file has to be retried on the next build regardless.
+ chmodSync(secret, 0o644);
+ const recovered = await buildGraph(d);
+ assert.deepEqual(recovered.errors, []);
+ const g = readGraph(wiringPath(outOf(d))) as GraphV1;
+ assert.ok(g.nodes.some((n) => n.id === "src/secret.ts#secretFn"), "the once-unreadable file is indexed now");
+});
diff --git a/test/graph-load.test.ts b/test/graph-load.test.ts
index d7d0b45f..f3a3124e 100644
--- a/test/graph-load.test.ts
+++ b/test/graph-load.test.ts
@@ -118,7 +118,12 @@ test("loadAskIndexCached: caches and invalidates the same way as the graph loade
assert.equal(__parseCount.askIndex, 2);
});
-test("callTool: graft_callers on the same dir twice doesn't reparse the graph", () => {
+// This file pins the mtime-keyed load cache, so the pre-query auto-refresh —
+// which deliberately invalidates that cache after a rebuild — has to stay out of
+// the way. `graph-refresh.test.ts` covers the refresh itself.
+process.env.GRAFT_NO_REFRESH = "1";
+
+test("callTool: graft_callers on the same dir twice doesn't reparse the graph", async () => {
const dir = fixtureDir();
mkdirSync(join(dir, "src"), { recursive: true });
writeFileSync(join(dir, "src", "math.ts"), "export function add() { return 1; }\n");
@@ -142,11 +147,11 @@ test("callTool: graft_callers on the same dir twice doesn't reparse the graph",
writeGraph(graph, outDir);
__resetParseCounts();
- const r1 = callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
+ const r1 = await callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
assert.equal(r1.isError, false);
assert.equal(__parseCount.graph, 1);
- const r2 = callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
+ const r2 = await callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
assert.equal(r2.isError, false);
assert.equal(__parseCount.graph, 1, "second call on the same dir must not reparse");
});
diff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.ts
new file mode 100644
index 00000000..c75cd81a
--- /dev/null
+++ b/test/graph-refresh.test.ts
@@ -0,0 +1,206 @@
+/**
+ * The pre-query freshness gate. Two things matter: it notices working-tree edits
+ * that nobody committed (or even made through the agent), and it never turns a
+ * working query into a failing one.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildGraph } from "../src/graph/build.js";
+import { ensureFreshGraph, refreshNote } from "../src/graph/refresh.js";
+import { isClean, probeDrift } from "../src/graph/fingerprint.js";
+import { readGraph, wiringPath } from "../src/graph/write.js";
+import { acquireLock, readStats, releaseLock, writeStats, emptyStats } from "../src/util/state.js";
+import { callTool } from "../src/mcp/tools.js";
+import type { GraphV1 } from "../src/graph/types.js";
+
+const MATH = "export function add(a: number, b: number): number {\n return a + b;\n}\n";
+
+function repo(): string {
+ const d = mkdtempSync(join(tmpdir(), "graft-refresh-"));
+ mkdirSync(join(d, "src"), { recursive: true });
+ writeFileSync(join(d, "src", "math.ts"), MATH);
+ return d;
+}
+
+const outOf = (d: string): string => join(d, "graft");
+const graphOf = (d: string): GraphV1 => readGraph(wiringPath(outOf(d))) as GraphV1;
+const hasSymbol = (d: string, id: string): boolean => graphOf(d).nodes.some((n) => n.id === id);
+
+/** Each test owns the env switch; `graph-load.test.ts` sets it process-wide for
+ * its own file, and these run in a separate process. */
+function withRefreshDisabled<T>(fn: () => T): T {
+ process.env.GRAFT_NO_REFRESH = "1";
+ try {
+ return fn();
+ } finally {
+ delete process.env.GRAFT_NO_REFRESH;
+ }
+}
+
+test("probeDrift: clean after a build, then reports what moved", async () => {
+ const d = repo();
+ await buildGraph(d);
+ const clean = probeDrift(d, outOf(d));
+ assert.ok(clean && isClean(clean));
+
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);
+ writeFileSync(join(d, "src", "new.ts"), "export const N = 2;\n");
+ const drift = probeDrift(d, outOf(d));
+ assert.deepEqual(drift, { changed: ["src/math.ts"], added: ["src/new.ts"], removed: [] });
+
+ rmSync(join(d, "src", "new.ts"));
+ rmSync(join(d, "src", "math.ts"));
+ assert.deepEqual(probeDrift(d, outOf(d)), { changed: [], added: [], removed: ["src/math.ts"] });
+});
+
+test("probeDrift returns null when no fingerprint was ever written", () => {
+ const d = repo();
+ mkdirSync(outOf(d), { recursive: true });
+ assert.equal(probeDrift(d, outOf(d)), null);
+});
+
+test("ensureFreshGraph picks up an uncommitted edit before the query sees the graph", async () => {
+ const d = repo();
+ await buildGraph(d);
+ assert.equal(hasSymbol(d, "src/math.ts#mul"), false);
+
+ // Exactly the state that used to answer stale: a file edited in the working
+ // tree, nothing committed, no hook having flagged anything.
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export function mul(a: number, b: number): number {\n return a * b;\n}\n`);
+
+ const r = await ensureFreshGraph(d);
+ assert.equal(r.refreshed, true);
+ assert.deepEqual(r.drift?.changed, ["src/math.ts"]);
+ assert.equal(hasSymbol(d, "src/math.ts#mul"), true);
+ assert.match(refreshNote(r) ?? "", /^\[graft\] refreshed the graph \(1 file changed\)/);
+});
+
+test("ensureFreshGraph is a no-op on a clean tree", async () => {
+ const d = repo();
+ await buildGraph(d);
+ const before = readFileSync(wiringPath(outOf(d)), "utf8");
+ const r = await ensureFreshGraph(d);
+ assert.equal(r.refreshed, false);
+ assert.equal(refreshNote(r), null, "silence when there is nothing to say");
+ assert.equal(readFileSync(wiringPath(outOf(d)), "utf8"), before, "the graph is not even rewritten");
+});
+
+test("ensureFreshGraph rebuilds once when the graph predates the fingerprint", async () => {
+ const d = repo();
+ await buildGraph(d);
+ rmSync(join(outOf(d), ".cache", "fingerprint.json"));
+
+ const first = await ensureFreshGraph(d);
+ assert.equal(first.refreshed, true, "no fingerprint = unknown state, so rebuild");
+ assert.equal(first.drift, undefined);
+ // ...and that rebuild lays one down, so it costs one build, not one per query.
+ const second = await ensureFreshGraph(d);
+ assert.equal(second.refreshed, false);
+});
+
+test("ensureFreshGraph does nothing when there is no graph at all", async () => {
+ const d = repo();
+ const r = await ensureFreshGraph(d);
+ assert.equal(r.refreshed, false);
+ assert.equal(probeDrift(d, outOf(d)), null, "and it did not build one behind the user's back");
+});
+
+test("GRAFT_NO_REFRESH and { disabled } both short-circuit", async () => {
+ const d = repo();
+ await buildGraph(d);
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);
+
+ const off = await withRefreshDisabled(() => ensureFreshGraph(d));
+ assert.equal(off.refreshed, false);
+ const flagged = await ensureFreshGraph(d, { disabled: true });
+ assert.equal(flagged.refreshed, false);
+ assert.equal(hasSymbol(d, "src/math.ts#X"), false, "the graph must be untouched");
+
+ const on = await ensureFreshGraph(d);
+ assert.equal(on.refreshed, true);
+});
+
+test("a rebuild already in flight is waited out, then reported — never a hang", async () => {
+ const d = repo();
+ await buildGraph(d);
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);
+
+ assert.equal(acquireLock(d), true, "hold the lock the way a background sync would");
+ const started = Date.now();
+ const r = await ensureFreshGraph(d);
+ const waited = Date.now() - started;
+ releaseLock(d);
+
+ assert.equal(r.refreshed, false);
+ assert.match(r.note ?? "", /already in flight/);
+ assert.ok(waited >= 1000 && waited < 10000, `should wait out the lock briefly, waited ${waited}ms`);
+});
+
+test("a refresh updates the statusline stats, but only where they already exist", async () => {
+ const d = repo();
+ await buildGraph(d);
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);
+
+ // No stats file (a repo with no Claude Code wiring): nothing is created.
+ await ensureFreshGraph(d);
+ assert.equal(readStats(d), null);
+
+ // With one, the refresh clears the drift flags the edit hook set mid-turn —
+ // that's what flips the statusline from `⚠ stale` to `✓ synced`.
+ writeStats(d, { ...emptyStats(), dirty: true, staleCount: 3 });
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export const Y = 2;\n`);
+ await ensureFreshGraph(d);
+ const s = readStats(d);
+ assert.equal(s?.dirty, false);
+ assert.equal(s?.staleCount, 0);
+ assert.ok((s?.nodeCount ?? 0) > 0, "and it refreshes the counts from the new graph");
+ assert.ok(s?.syncedAt);
+});
+
+test("a failed rebuild still answers from the graph on disk", async (t) => {
+ if (process.getuid?.() === 0) return t.skip("root writes anywhere, so a read-only file proves nothing");
+ const d = repo();
+ await buildGraph(d);
+ const before = readFileSync(wiringPath(outOf(d)), "utf8");
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);
+
+ // Make the graph write itself fail: the query must degrade to the old graph, not
+ // start erroring because a rebuild couldn't happen.
+ chmodSync(wiringPath(outOf(d)), 0o400);
+ const r = await ensureFreshGraph(d);
+ chmodSync(wiringPath(outOf(d)), 0o600);
+
+ assert.equal(r.refreshed, false);
+ assert.match(r.note ?? "", /refresh skipped/);
+ assert.equal(readFileSync(wiringPath(outOf(d)), "utf8"), before, "the old graph is intact");
+ assert.match(refreshNote(r) ?? "", /^\[graft\] graph refresh skipped/);
+
+ // The lock must have been released, or every later query would report a
+ // rebuild-in-flight that will never finish.
+ assert.equal(acquireLock(d), true);
+ releaseLock(d);
+});
+
+test("callTool refreshes before answering — except for graft_check", async () => {
+ const d = repo();
+ await buildGraph(d);
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}export function mul(a: number, b: number): number {\n return a * b;\n}\n`);
+
+ // graft_check is the drift report: refreshing first would make it always say OK.
+ const check = await callTool(d, "graft_check", {});
+ assert.equal(check.isError, false);
+ assert.ok(!check.text.startsWith("[graft] refreshed"));
+ assert.equal(hasSymbol(d, "src/math.ts#mul"), false, "check must not rebuild");
+
+ const ask = await callTool(d, "graft_ask", { query: "multiply two numbers" });
+ assert.equal(ask.isError, false);
+ assert.match(ask.text, /^\[graft\] refreshed the graph/);
+ assert.equal(hasSymbol(d, "src/math.ts#mul"), true);
+ assert.match(ask.text, /mul/, "and the answer knows about the symbol that was never committed");
+
+ const again = await callTool(d, "graft_ask", { query: "multiply two numbers" });
+ assert.ok(!again.text.startsWith("[graft] refreshed"), "nothing moved — no note, no rebuild");
+});
diff --git a/test/mcp-tools.test.ts b/test/mcp-tools.test.ts
index 737de550..15fd77a5 100644
--- a/test/mcp-tools.test.ts
+++ b/test/mcp-tools.test.ts
@@ -72,7 +72,7 @@ function multiDirRepo(): string {
return d;
}
-test('TOOLS lists the six tools with schemas', () => {
+test('TOOLS lists the six tools with schemas', async () => {
assert.deepEqual(TOOLS.map((t) => t.name), [
'graft_ask',
'graft_skeleton',
@@ -93,101 +93,101 @@ test('TOOLS lists the six tools with schemas', () => {
assert.ok('depth' in props, 'graft_callers schema should document `depth`');
});
-test('graft_ask returns ranked hits for a built repo', () => {
+test('graft_ask returns ranked hits for a built repo', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_ask', { query: 'how do I add numbers' });
+ const r = await callTool(d, 'graft_ask', { query: 'how do I add numbers' });
assert.equal(r.isError, false);
assert.match(r.text, /add/);
assert.match(r.text, /src\/math\.ts/);
});
-test('graft_ask: `in` arg round-trips — narrows results to the prefix and is a soft isError on an unknown one', () => {
+test('graft_ask: `in` arg round-trips — narrows results to the prefix and is a soft isError on an unknown one', async () => {
const d = builtRepo();
- const ok = callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'src' });
+ const ok = await callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'src' });
assert.equal(ok.isError, false);
assert.match(ok.text, /src\/math\.ts/);
- const miss = callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'nosuchdir' });
+ const miss = await callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'nosuchdir' });
assert.equal(miss.isError, true);
assert.match(miss.text, /nothing indexed under "nosuchdir\/"/);
assert.match(miss.text, /or any path prefix/);
});
-test('graft_check reports the wiring state', () => {
+test('graft_check reports the wiring state', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_check', {});
+ const r = await callTool(d, 'graft_check', {});
assert.equal(r.isError, false);
assert.match(r.text, /graph check: OK/);
});
-test('graft_callers with depth names dependents of a file (blast radius)', () => {
+test('graft_callers with depth names dependents of a file (blast radius)', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_callers', { symbol: 'src/math.ts', depth: 2 });
+ const r = await callTool(d, 'graft_callers', { symbol: 'src/math.ts', depth: 2 });
assert.equal(r.isError, false);
assert.ok(r.text.length > 0);
});
-test('unbuilt repo and unknown tool are soft errors', () => {
+test('unbuilt repo and unknown tool are soft errors', async () => {
const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-bare-'));
- const r1 = callTool(bare, 'graft_callers', { symbol: 'x.ts', depth: 2 });
+ const r1 = await callTool(bare, 'graft_callers', { symbol: 'x.ts', depth: 2 });
assert.equal(r1.isError, true);
assert.match(r1.text, /graft build/);
- const r2 = callTool(bare, 'nope', {});
+ const r2 = await callTool(bare, 'nope', {});
assert.equal(r2.isError, true);
assert.match(r2.text, /unknown tool/i);
});
-test('graft_callers round-trips a caller on the built fixture', () => {
+test('graft_callers round-trips a caller on the built fixture', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_callers', { symbol: 'add' });
+ const r = await callTool(d, 'graft_callers', { symbol: 'add' });
assert.equal(r.isError, false);
assert.match(r.text, /add · function · src\/math\.ts:/);
assert.match(r.text, /calls ← sub \(src\/math\.ts:/);
});
-test('graft_callers: qualified/--in narrowing still resolves through the shared resolver', () => {
+test('graft_callers: qualified/--in narrowing still resolves through the shared resolver', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_callers', { symbol: 'add', in: 'math' });
+ const r = await callTool(d, 'graft_callers', { symbol: 'add', in: 'math' });
assert.equal(r.isError, false);
assert.match(r.text, /calls ← sub/);
- const miss = callTool(d, 'graft_callers', { symbol: 'add', in: 'nowhere' });
+ const miss = await callTool(d, 'graft_callers', { symbol: 'add', in: 'nowhere' });
assert.equal(miss.isError, true);
assert.match(miss.text, /no symbol "add" in the graph/);
});
-test('graft_callers direction:out round-trips a callee, and reports a loud note when there are none', () => {
+test('graft_callers direction:out round-trips a callee, and reports a loud note when there are none', async () => {
const d = builtRepo();
- const callee = callTool(d, 'graft_callers', { symbol: 'sub', direction: 'out' });
+ const callee = await callTool(d, 'graft_callers', { symbol: 'sub', direction: 'out' });
assert.equal(callee.isError, false);
assert.match(callee.text, /calls → add \(src\/math\.ts:/);
// `add` calls nothing, so its callees are empty — must be a loud note, not silence.
- const empty = callTool(d, 'graft_callers', { symbol: 'add', direction: 'out' });
+ const empty = await callTool(d, 'graft_callers', { symbol: 'add', direction: 'out' });
assert.equal(empty.isError, false);
assert.match(empty.text, /no indexed callees/);
assert.match(empty.text, /graft grep "add"/);
});
-test('graft_callers: unknown symbol / missing symbol are soft isErrors', () => {
+test('graft_callers: unknown symbol / missing symbol are soft isErrors', async () => {
const d = builtRepo();
- const r1 = callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere' });
+ const r1 = await callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere' });
assert.equal(r1.isError, true);
assert.match(r1.text, /no symbol "noSuchSymbolAnywhere" in the graph/);
assert.match(r1.text, /check spelling|graft build/);
- const r2 = callTool(d, 'graft_callers', {});
+ const r2 = await callTool(d, 'graft_callers', {});
assert.equal(r2.isError, true);
assert.match(r2.text, /requires a symbol/);
});
-test('graft_callers: depth param is honored (depth 2 reaches further than depth 1)', () => {
+test('graft_callers: depth param is honored (depth 2 reaches further than depth 1)', async () => {
const d = chainRepo();
- const shallow = callTool(d, 'graft_callers', { symbol: 'add', depth: 1 });
+ const shallow = await callTool(d, 'graft_callers', { symbol: 'add', depth: 1 });
assert.equal(shallow.isError, false);
assert.match(shallow.text, /← sub \(/);
assert.doesNotMatch(shallow.text, /compute/);
- const deeper = callTool(d, 'graft_callers', { symbol: 'add', depth: 2 });
+ const deeper = await callTool(d, 'graft_callers', { symbol: 'add', depth: 2 });
assert.equal(deeper.isError, false);
assert.match(deeper.text, /← sub \(/);
assert.match(deeper.text, /\[depth 1\]/);
@@ -195,9 +195,9 @@ test('graft_callers: depth param is honored (depth 2 reaches further than depth
assert.match(deeper.text, /\[depth 2\]/);
});
-test('graft_callers depth>1 on a file aggregates dependents that call into a symbol the file defines, not just file-level imports', () => {
+test('graft_callers depth>1 on a file aggregates dependents that call into a symbol the file defines, not just file-level imports', async () => {
const d = fileScopeRepo();
- const r = callTool(d, 'graft_callers', { symbol: 'src/a.ts', depth: 2 });
+ const r = await callTool(d, 'graft_callers', { symbol: 'src/a.ts', depth: 2 });
assert.equal(r.isError, false);
// Walking only the FILE node's incoming edges would find b.ts via `imports`
// but drop it via `calls`, since a `calls` edge targets the SYMBOL id
@@ -206,95 +206,95 @@ test('graft_callers depth>1 on a file aggregates dependents that call into a sym
assert.match(r.text, /calls ← useB \(src\/b\.ts/);
});
-test('graft_callers: unknown symbol is a soft isError with the check-spelling message', () => {
+test('graft_callers: unknown symbol is a soft isError with the check-spelling message', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere', depth: 2 });
+ const r = await callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere', depth: 2 });
assert.equal(r.isError, true);
assert.match(r.text, /no symbol "noSuchSymbolAnywhere" in the graph/);
assert.match(r.text, /check spelling/);
});
-test('graft_grep round-trips a hit on the built fixture, grouped by enclosing symbol', () => {
+test('graft_grep round-trips a hit on the built fixture, grouped by enclosing symbol', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_grep', { pattern: 'add' });
+ const r = await callTool(d, 'graft_grep', { pattern: 'add' });
assert.equal(r.isError, false);
assert.match(r.text, /"add" — \d+ hits? in \d+ symbols? across \d+ files? \(searched \d+ indexed files\)/);
assert.match(r.text, /src\/math\.ts/);
});
-test('graft_grep: no hits is a soft (non-error) result with the loud fallback note', () => {
+test('graft_grep: no hits is a soft (non-error) result with the loud fallback note', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_grep', { pattern: 'noSuchPatternAnywhere' });
+ const r = await callTool(d, 'graft_grep', { pattern: 'noSuchPatternAnywhere' });
assert.equal(r.isError, false);
assert.match(r.text, /no hits for "noSuchPatternAnywhere"/);
assert.match(r.text, /retry graft grep/);
});
-test('graft_grep: missing pattern and unbuilt repo are soft errors', () => {
+test('graft_grep: missing pattern and unbuilt repo are soft errors', async () => {
const d = builtRepo();
- const r1 = callTool(d, 'graft_grep', {});
+ const r1 = await callTool(d, 'graft_grep', {});
assert.equal(r1.isError, true);
assert.match(r1.text, /requires a pattern/);
const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-grep-bare-'));
- const r2 = callTool(bare, 'graft_grep', { pattern: 'add' });
+ const r2 = await callTool(bare, 'graft_grep', { pattern: 'add' });
assert.equal(r2.isError, true);
assert.match(r2.text, /graft build/);
});
-test('graft_map round-trips a repo orientation on the built fixture', () => {
+test('graft_map round-trips a repo orientation on the built fixture', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_map', {});
+ const r = await callTool(d, 'graft_map', {});
assert.equal(r.isError, false);
assert.match(r.text, /^repo map — \d+ files · \d+ symbols · \d+ edges/);
assert.match(r.text, /src/);
assert.match(r.text, /hotspots:/);
});
-test('graft_map: unbuilt repo is a soft isError with the no-graph message', () => {
+test('graft_map: unbuilt repo is a soft isError with the no-graph message', async () => {
const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-map-bare-'));
- const r = callTool(bare, 'graft_map', {});
+ const r = await callTool(bare, 'graft_map', {});
assert.equal(r.isError, true);
assert.match(r.text, /graft build/);
});
-test('graft_map: max_dirs arg is honored — the MCP escape hatch for dropped dirs', () => {
+test('graft_map: max_dirs arg is honored — the MCP escape hatch for dropped dirs', async () => {
const d = multiDirRepo();
- const capped = callTool(d, 'graft_map', { max_dirs: 1 });
+ const capped = await callTool(d, 'graft_map', { max_dirs: 1 });
assert.equal(capped.isError, false);
assert.match(capped.text, /\+4 more directories not shown/);
- const raised = callTool(d, 'graft_map', { max_dirs: 10 });
+ const raised = await callTool(d, 'graft_map', { max_dirs: 10 });
assert.equal(raised.isError, false);
assert.doesNotMatch(raised.text, /more directories? not shown/);
});
-test('callTool honors a dirOverride for a graph built in a non-default dir', () => {
+test('callTool honors a dirOverride for a graph built in a non-default dir', async () => {
const { repo, graphDir } = customDirRepo();
// With the override pointing at the actual graph location, tools find it.
- const check = callTool(repo, 'graft_check', {}, graphDir);
+ const check = await callTool(repo, 'graft_check', {}, graphDir);
assert.equal(check.isError, false);
assert.match(check.text, /graph check: OK/);
- const callers = callTool(repo, 'graft_callers', { symbol: 'add' }, graphDir);
+ const callers = await callTool(repo, 'graft_callers', { symbol: 'add' }, graphDir);
assert.equal(callers.isError, false);
assert.match(callers.text, /calls ← sub \(src\/math\.ts:/);
// Without the override, tools fall back to the default `<repo>/graft`,
// which doesn't exist here — must report no graph, not silently succeed.
- const noOverride = callTool(repo, 'graft_callers', { symbol: 'add' });
+ const noOverride = await callTool(repo, 'graft_callers', { symbol: 'add' });
assert.equal(noOverride.isError, true);
assert.match(noOverride.text, /graft build/);
});
-test('graft_skeleton returns signatures for a file, errors on unknown file', () => {
+test('graft_skeleton returns signatures for a file, errors on unknown file', async () => {
const d = builtRepo();
- const r = callTool(d, 'graft_skeleton', { file: 'src/math.ts' });
+ const r = await callTool(d, 'graft_skeleton', { file: 'src/math.ts' });
assert.equal(r.isError, false);
assert.match(r.text, /graft skeleton — src\/math\.ts/);
assert.match(r.text, /function add {2}function add\(a: number, b: number\): number/);
- const miss = callTool(d, 'graft_skeleton', { file: 'src/nope.ts' });
+ const miss = await callTool(d, 'graft_skeleton', { file: 'src/nope.ts' });
assert.equal(miss.isError, true);
});