Skip to content

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

write wiring.json atomically

anirudhkumar-nanonetse6cb2c592236
diff --git a/src/graph/write.ts b/src/graph/write.ts
index 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.ts
index 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 acceptable
diff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.ts
index 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.ts
new file mode 100644
index 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`);
+});