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
refresh the graph before every query, incrementally
anirudhkumar-nanonets14abd300518f
diff --git a/.claude/settings.json b/.claude/settings.jsonindex 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.mdindex 8fa0d9bb..7fcedc87 100644--- a/README.md+++ b/README.md@@ -119,7 +119,9 @@ flowchart LRP2 --> 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'sgraft 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 cachegraft 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 agraft 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 localhostgraft viz --port 5000 --no-open # pick a port; don't auto-open the browserdiff --git a/src/claude/settings-merge.ts b/src/claude/settings-merge.tsindex 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.tsindex 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 taskdiff --git a/src/claude/state.ts b/src/claude/state.tsindex 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.tsindex 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.tsindex 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 @@ programconst 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 rebuildif (!opts.json && readWorkspace(root, globalOpts.dir)) {runWorkspaceMap(root, globalOpts.dir, { maxDirs: maxDirsW });return;diff --git a/src/engine.ts b/src/engine.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 loadeassert.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.tsnew file mode 100644index 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.tsindex 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 depthassert.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 symassert.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);});