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
write wiring.json atomically
anirudhkumar-nanonetse6cb2c592236
diff --git a/src/graph/write.ts b/src/graph/write.tsindex 8b993a88..05c080a0 100644--- a/src/graph/write.ts+++ b/src/graph/write.ts@@ -8,8 +8,9 @@* timestamps, so rebuilding an unchanged repo produces a byte-identical file and* git diffs stay minimal.*/-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";-import { dirname, join } from "node:path";+import { readFileSync } from "node:fs";+import { join } from "node:path";+import { writeFileAtomic } from "../util/state.js";import type { EdgeV1, GraphV1, NodeV1 } from "./types.js";/** Hidden subdir under the context dir that holds machine-only graph artifacts. */@@ -40,8 +41,12 @@ export function writeGraph(graph: GraphV1, outDir: string): string {edges: [...graph.edges].sort(edgeOrder),};const path = wiringPath(outDir);- mkdirSync(dirname(path), { recursive: true });- writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");+ // Atomic, because a query can now rebuild the graph (`graph/refresh.ts`) while+ // something else is reading it — a second MCP call, the statusline's poll, a+ // `graft check` from the edit hook, another graft process. None of those take+ // the build lock, and a truncating write would hand them a partial document,+ // which `readGraph` can only report as "no graph — run graft build".+ writeFileAtomic(path, JSON.stringify(sorted, null, 2) + "\n");return path;}diff --git a/src/util/state.ts b/src/util/state.tsindex 8f644170..ccc4c970 100644--- a/src/util/state.ts+++ b/src/util/state.ts@@ -35,15 +35,35 @@ 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 {+/**+ * Write `text` to `p` so a concurrent reader sees either the whole old file or the+ * whole new one — never a truncated prefix.+ *+ * `writeFileSync` truncates the destination to zero and *then* streams bytes into+ * it, so for the milliseconds that takes, anyone who opens the path reads a partial+ * document. Writing to a scratch file and renaming over the target avoids that+ * entirely: `rename` within a filesystem is atomic, and it replaces the directory+ * entry rather than modifying the file in place, so a reader that already opened+ * the old file keeps reading a complete one.+ *+ * The pid in the temp name keeps two concurrent writers off each other's scratch+ * file. This is the only atomic-write implementation in the codebase on purpose —+ * `graph/write.ts` uses it for `wiring.json`, which a query can now rewrite while+ * the statusline, a second graft process, or another MCP call is reading it.+ */+export function writeFileAtomic(p: string, text: string): void {mkdirSync(dirname(p), { recursive: true });const tmp = `${p}.${process.pid}.tmp`;- writeFileSync(tmp, compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));+ writeFileSync(tmp, text);renameSync(tmp, p);}+/** {@link writeFileAtomic} for JSON. `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 {+ writeFileAtomic(p, compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));+}+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 acceptablediff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.tsindex 7b0afc6b..00de9133 100644--- a/test/graph-refresh.test.ts+++ b/test/graph-refresh.test.ts@@ -7,7 +7,7 @@ import { test } from "node:test";import assert from "node:assert/strict";import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";-import { join } from "node:path";+import { dirname, join } from "node:path";import { buildGraph } from "../src/graph/build.js";import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "../src/graph/refresh.js";import { extractCachePath } from "../src/graph/extract-cache.js";@@ -162,17 +162,21 @@ test("a refresh updates the statusline stats, but only where they already exist"});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");+ if (process.getuid?.() === 0) return t.skip("root writes anywhere, so a read-only directory 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);+ // start erroring because a rebuild couldn't happen. The *directory* is what has+ // to be blocked — `writeGraph` installs the new graph with tmp+rename now (see+ // `graph-write-atomic.test.ts`), and both the scratch write and the rename need+ // write permission on the directory, while the old file's own mode is irrelevant.+ const graphDir = dirname(wiringPath(outOf(d)));+ chmodSync(graphDir, 0o500);const r = await ensureFreshGraph(d);- chmodSync(wiringPath(outOf(d)), 0o600);+ chmodSync(graphDir, 0o700);assert.equal(r.refreshed, false);assert.match(r.note ?? "", /refresh skipped/);diff --git a/test/graph-write-atomic.test.ts b/test/graph-write-atomic.test.tsnew file mode 100644index 00000000..cf9357ba--- /dev/null+++ b/test/graph-write-atomic.test.ts@@ -0,0 +1,148 @@+/**+ * `wiring.json` must never be observable half-written.+ *+ * This stopped being theoretical when a query gained the ability to rebuild the+ * graph (`graph/refresh.ts`): the writer takes the build lock, but no reader does —+ * not the statusline's poll, not a second MCP call, not another graft process, not+ * `graft check` from the edit hook. A truncating write hands all of them a partial+ * document, and `readGraph` can only report that as null, i.e. "no graph — run+ * graft build" on a repo that has one.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { closeSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";+import { spawn } from "node:child_process";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { readGraph, wiringPath, writeGraph } from "../src/graph/write.js";+import type { GraphV1, NodeV1 } from "../src/graph/types.js";++/** A graph big enough that serializing it isn't instantaneous — the race window+ * has to be wide enough for a concurrent reader to land inside it. */+function graph(nodeCount: number, marker: string): GraphV1 {+ const nodes: NodeV1[] = [];+ for (let i = 0; i < nodeCount; i++) {+ nodes.push({+ id: `src/m${i}.ts#fn${i}`,+ name: `fn${i}`,+ kind: "function",+ path: `src/m${i}.ts`,+ start_line: 1,+ end_line: 3,+ signature: `function fn${i}(a: number): number`,+ body_hash: `${marker}${i}`,+ summary: null,+ summary_state: "pending",+ // Padding, so the file is megabytes rather than kilobytes.+ doc: `${marker} `.repeat(40),+ } as unknown as NodeV1);+ }+ return {+ meta: { version: 1, nodeCount, edgeCount: 0, languages: ["ts"], scopes: [] },+ nodes,+ edges: [],+ } as unknown as GraphV1;+}++function outDir(): string {+ return join(mkdtempSync(join(tmpdir(), "graft-atomic-")), "graft");+}++test("writeGraph replaces the file instead of truncating it in place", () => {+ const out = outDir();+ writeGraph(graph(50, "a"), out);+ const path = wiringPath(out);+ const before = statSync(path).ino;++ writeGraph(graph(50, "b"), out);++ // A truncating `writeFileSync` keeps the same inode and empties it; a tmp+rename+ // installs a different one. This is the whole difference, and it needs no timing+ // to observe.+ assert.notEqual(statSync(path).ino, before, "the destination must be replaced, not modified in place");+ assert.equal(readGraph(path)?.nodes[0]?.body_hash, "b0");++ // And the scratch file must not be left lying around next to it.+ const strays = readdirSync(dirname(path)).filter((f) => f.includes(".tmp"));+ assert.deepEqual(strays, [], `left temp files behind: ${strays.join(", ")}`);+});++test("a reader holding the file open across a rewrite still reads a whole graph", () => {+ const out = outDir();+ writeGraph(graph(400, "a"), out);+ const path = wiringPath(out);+ const original = readFileSync(path, "utf8");++ // Exactly the statusline's position: it opened the file, and mid-read a query+ // rebuilt the graph underneath it.+ const fd = openSync(path, "r");+ try {+ const head = Buffer.alloc(64);+ readSync(fd, head, 0, 64, 0); // started reading...+ writeGraph(graph(400, "b"), out); // ...and the graph is rewritten now++ const size = statSync(path).size;+ const rest = Buffer.alloc(original.length);+ const n = readSync(fd, rest, 0, original.length, 0);+ const seen = rest.subarray(0, n).toString("utf8");++ // The open handle keeps the file it opened: complete, parseable, and the+ // version it started with. Under a truncating write this read would return the+ // new file's bytes at old offsets — a spliced document that parses to nothing.+ assert.equal(seen, original, "the reader must see the whole document it opened");+ assert.equal(JSON.parse(seen).nodes[0].body_hash, "a0");+ assert.ok(size > 0, "and the new file is fully on disk for the next reader");+ assert.equal(readGraph(path)?.nodes[0]?.body_hash, "b0");+ } finally {+ closeSync(fd);+ }+});++test("a concurrent reader never parses a torn graph", async () => {+ const out = outDir();+ writeGraph(graph(3000, "a"), out);+ const path = wiringPath(out);+ const bytes = statSync(path).size;+ assert.ok(bytes > 1_000_000, `fixture should be megabytes to widen the window, got ${bytes}`);++ // A separate process, because writes here are synchronous — nothing in this+ // process could observe a partial file even if one existed.+ const READ_MS = 600;+ const reader = spawn(+ process.execPath,+ [+ "-e",+ `const fs = require("fs");+ let ok = 0, bad = 0, empty = 0;+ const end = Date.now() + ${READ_MS};+ while (Date.now() < end) {+ let text;+ try { text = fs.readFileSync(process.argv[1], "utf8"); } catch { bad++; continue; }+ if (text.length === 0) { empty++; continue; }+ try { JSON.parse(text); ok++; } catch { bad++; }+ }+ process.stdout.write(JSON.stringify({ ok, bad, empty }));`,+ path,+ ],+ { stdio: ["ignore", "pipe", "inherit"] },+ );+ let stdout = "";+ reader.stdout.setEncoding("utf8");+ reader.stdout.on("data", (c: string) => (stdout += c));++ // Rewrite continuously for as long as it's reading.+ const deadline = Date.now() + READ_MS;+ let writes = 0;+ while (Date.now() < deadline) {+ writeGraph(graph(3000, writes % 2 === 0 ? "a" : "b"), out);+ writes++;+ }++ await new Promise<void>((resolve) => reader.on("close", () => resolve()));+ const r = JSON.parse(stdout) as { ok: number; bad: number; empty: number };++ assert.ok(writes > 1, `the writer should have rewritten the file repeatedly, did ${writes}`);+ assert.ok(r.ok > 0, `the reader should have read it repeatedly, got ${JSON.stringify(r)}`);+ assert.equal(r.empty, 0, "no reader may ever see a zero-length graph");+ assert.equal(r.bad, 0, `every read must parse; got ${JSON.stringify(r)} across ${writes} writes`);+});