ruact 0.0.2 → 0.0.3

data/vendor/javascript/vite-plugin-ruact/server-functions-codegen.test.mjs

@@ -0,0 +1,866 @@
+// Story 8.0a — vitest suite for the server-functions codegen sidecar.
+//
+// Covers the nine cases enumerated in AC9, plus the Ruby↔JS parity test
+// (Task 8.5). The parity test is the load-bearing CI guard against the two
+// codegen implementations drifting apart.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { execFileSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  render,
+  writeIfChanged,
+  readSnapshot,
+  generateOnce,
+  resolvePaths,
+  buildConfigContribution,
+  installServerFunctionsHooks,
+  RUNTIME_IMPORT_SPECIFIER,
+  runtimePackagePath,
+} from "./server-functions-codegen.mjs";
+
+let tmpdir;
+beforeEach(() => {
+  tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), "ruact-8-0a-"));
+  process.env.RUACT_SILENCE_LOG = "1";
+});
+afterEach(() => {
+  fs.rmSync(tmpdir, { recursive: true, force: true });
+  delete process.env.RUACT_SILENCE_LOG;
+});
+
+const baseSnapshot = (over = {}) => ({
+  version: 1,
+  generated_at: "2026-05-13T12:34:56Z",
+  functions: [],
+  ...over,
+});
+
+describe("Story 8.0a — render()", () => {
+  it("emits empty module when registry JSON has no functions", () => {
+    // Story 8.2 — the empty-registry branch now also emits the
+    // `export { revalidate } from "ruact/server-functions-runtime";`
+    // line so `import { revalidate } from "@/.ruact/server-functions"`
+    // works in projects that have not declared any server actions yet.
+    expect(render(baseSnapshot())).toEqual(
+      [
+        "// AUTO-GENERATED by vite-plugin-ruact (Story 8.0a). DO NOT EDIT.",
+        "// Source: tmp/cache/ruact/server-functions.json (version 1)",
+        "// Generated at: 2026-05-13T12:34:56Z",
+        `import { _makeRef } from "${RUNTIME_IMPORT_SPECIFIER}";`,
+        "",
+        "// (no server functions registered yet — Stories 8.1 / 9.1 populate)",
+        "void _makeRef;",
+        "",
+        `export { revalidate } from "${RUNTIME_IMPORT_SPECIFIER}";`,
+        "",
+      ].join("\n"),
+    );
+  });
+
+  it("references _makeRef via `void` even when empty so noUnusedLocals stays " +
+    "green (Re-run patch 2026-05-13)", () => {
+    expect(render(baseSnapshot())).toContain("void _makeRef;");
+  });
+
+  it("emits the revalidate re-export (Story 8.2) in both empty + populated branches", () => {
+    expect(render(baseSnapshot())).toContain(
+      `export { revalidate } from "${RUNTIME_IMPORT_SPECIFIER}";`,
+    );
+    expect(
+      render(
+        baseSnapshot({
+          functions: [{ ruby_symbol: "create_post", js_identifier: "createPost", kind: "action" }],
+        }),
+      ),
+    ).toContain(`export { revalidate } from "${RUNTIME_IMPORT_SPECIFIER}";`);
+  });
+
+  it("rejects a snapshot entry whose js_identifier is not a valid JS identifier " +
+    "(snapshot trust-boundary guard — Re-run patch 2026-05-13)", () => {
+    const evil = baseSnapshot({
+      functions: [
+        {
+          ruby_symbol: "create_post",
+          js_identifier: ');\nevil();_makeRef("x',
+          kind: "action",
+        },
+      ],
+    });
+    expect(() => render(evil)).toThrow(/valid JS identifier/);
+  });
+
+  it("JSON-escapes ruby_symbol in the _makeRef argument so quotes/backslashes " +
+    "cannot break out (Re-run patch 2026-05-13)", () => {
+    const weird = baseSnapshot({
+      functions: [
+        {
+          ruby_symbol: 'weird"\\name',
+          js_identifier: "weirdName",
+          kind: "action",
+        },
+      ],
+    });
+    // The emitted call site should contain a JSON-escaped string literal.
+    expect(render(weird)).toContain('_makeRef("weird\\"\\\\name");');
+  });
+
+  it("emits one export per registered function", () => {
+    const fns = [
+      { ruby_symbol: "create_post", js_identifier: "createPost", kind: "action" },
+      { ruby_symbol: "delete_post", js_identifier: "deletePost", kind: "action" },
+    ];
+    const out = render(baseSnapshot({ functions: fns }));
+    expect((out.match(/export const /g) || []).length).toBe(2);
+    expect(out).toContain("export const createPost:");
+    expect(out).toContain("export const deletePost:");
+  });
+
+  it("emits action and query exports with identical accessor mechanics " +
+    "(both call _makeRef)", () => {
+    const out = render(
+      baseSnapshot({
+        functions: [
+          { ruby_symbol: "create_post", js_identifier: "createPost", kind: "action" },
+          { ruby_symbol: "categories", js_identifier: "categories", kind: "query" },
+        ],
+      }),
+    );
+    expect(out).toContain(`_makeRef("create_post")`);
+    expect(out).toContain(`_makeRef("categories")`);
+  });
+
+  it("Story 8.2 — action signatures emit the intersection (direct callable + " +
+    "`<form action>`-compatible overload); query signatures stay narrow", () => {
+    // R1 (2026-05-17 review patch): the previous widening to
+    // `(args?: FormData | Record<string, unknown>) => Promise<unknown>`
+    // alone did NOT make `<form action={createPost}>` typecheck against
+    // React 19's `(formData: FormData) => void | Promise<void>` — Promise
+    // generics are invariant. The intersection adds a second
+    // `(formData: FormData) => Promise<void>` signature so the same export
+    // satisfies both call sites.
+    const out = render(
+      baseSnapshot({
+        functions: [
+          { ruby_symbol: "create_post", js_identifier: "createPost", kind: "action" },
+          { ruby_symbol: "categories", js_identifier: "categories", kind: "query" },
+        ],
+      }),
+    );
+    expect(out).toContain(
+      "export const createPost: ((args?: FormData | Record<string, unknown>) => Promise<unknown>) & ((formData: FormData) => Promise<void>) =",
+    );
+    expect(out).toContain("export const categories: () => Promise<unknown> =");
+  });
+
+  it("Story 8.2 — query signatures do NOT widen (regression guard against accidental " +
+    "carry-over of the action widening)", () => {
+    const out = render(
+      baseSnapshot({
+        functions: [{ ruby_symbol: "categories", js_identifier: "categories", kind: "query" }],
+      }),
+    );
+    // The literal action-style FormData union must NOT appear next to a query export.
+    expect(out).not.toMatch(/export const categories:[^=]*FormData/);
+    expect(out).toContain("export const categories: () => Promise<unknown> =");
+  });
+
+  it("ends with exactly one trailing newline", () => {
+    const out = render(baseSnapshot());
+    expect(out.endsWith("\n")).toBe(true);
+    expect(out.endsWith("\n\n")).toBe(false);
+  });
+});
+
+describe("Story 8.0a — writeIfChanged()", () => {
+  it("writes when the file does not exist", () => {
+    const file = path.join(tmpdir, "out.ts");
+    expect(writeIfChanged(file, "x")).toBe(true);
+    expect(fs.readFileSync(file, "utf8")).toBe("x");
+  });
+
+  it("skips writing when content is byte-identical", () => {
+    const file = path.join(tmpdir, "out.ts");
+    fs.writeFileSync(file, "x");
+    const before = fs.statSync(file).mtimeMs;
+    expect(writeIfChanged(file, "x")).toBe(false);
+    expect(fs.statSync(file).mtimeMs).toBe(before);
+  });
+
+  it("rewrites when content differs", () => {
+    const file = path.join(tmpdir, "out.ts");
+    fs.writeFileSync(file, "x");
+    expect(writeIfChanged(file, "y")).toBe(true);
+    expect(fs.readFileSync(file, "utf8")).toBe("y");
+  });
+});
+
+describe("Story 8.0a — generateOnce()", () => {
+  function setupSnapshot(snapshot) {
+    const jsonPath = path.join(tmpdir, "snap.json");
+    fs.writeFileSync(jsonPath, JSON.stringify(snapshot));
+    return jsonPath;
+  }
+
+  it("emits TS file from JSON snapshot on first call", () => {
+    const snapshotJson = setupSnapshot(baseSnapshot());
+    const generatedTs = path.join(tmpdir, "out.ts");
+    const result = generateOnce(tmpdir, { snapshotJson, generatedTs });
+    expect(result.wrote).toBe(true);
+    expect(fs.readFileSync(generatedTs, "utf8")).toContain(
+      "// AUTO-GENERATED by vite-plugin-ruact",
+    );
+  });
+
+  it("re-emits module when registry JSON mtime changes (Story 8.0a)", () => {
+    const snapshotJson = setupSnapshot(baseSnapshot());
+    const generatedTs = path.join(tmpdir, "out.ts");
+    generateOnce(tmpdir, { snapshotJson, generatedTs });
+
+    fs.writeFileSync(
+      snapshotJson,
+      JSON.stringify(
+        baseSnapshot({
+          functions: [{ ruby_symbol: "demo_ping", js_identifier: "demoPing", kind: "action" }],
+        }),
+      ),
+    );
+    const result = generateOnce(tmpdir, { snapshotJson, generatedTs });
+    expect(result.wrote).toBe(true);
+    expect(fs.readFileSync(generatedTs, "utf8")).toContain("export const demoPing");
+  });
+
+  it("does NOT re-emit when JSON content is byte-identical (write-if-changed)", () => {
+    const snapshotJson = setupSnapshot(baseSnapshot());
+    const generatedTs = path.join(tmpdir, "out.ts");
+    generateOnce(tmpdir, { snapshotJson, generatedTs });
+    const result = generateOnce(tmpdir, { snapshotJson, generatedTs });
+    expect(result.wrote).toBe(false);
+  });
+
+  it("gracefully handles malformed JSON (returns null snapshot, leaves last-good module)", () => {
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    fs.writeFileSync(snapshotJson, "{ not json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    fs.writeFileSync(generatedTs, "// last-good content");
+    const result = generateOnce(tmpdir, { snapshotJson, generatedTs });
+    expect(result.wrote).toBe(false);
+    expect(result.snapshot).toBeNull();
+    expect(fs.readFileSync(generatedTs, "utf8")).toBe("// last-good content");
+  });
+
+  it("returns wrote=false when snapshot file is absent", () => {
+    const result = generateOnce(tmpdir, {
+      snapshotJson: path.join(tmpdir, "missing.json"),
+      generatedTs: path.join(tmpdir, "out.ts"),
+    });
+    expect(result.wrote).toBe(false);
+  });
+});
+
+describe("Story 8.0a — buildConfigContribution() (AC6 — @ alias)", () => {
+  it("registers @ alias as <root>/app/javascript when host config does not define it " +
+    "(Chunk 2 patch 2026-05-13 — no placeholder, AC6 shape)", () => {
+    const contribution = buildConfigContribution({ root: "/my/app" });
+    expect(contribution.resolve.alias["@"]).toBe(path.resolve("/my/app", "app/javascript"));
+  });
+
+  it("falls back to process.cwd() when userConfig.root is absent", () => {
+    const contribution = buildConfigContribution({});
+    expect(contribution.resolve.alias["@"]).toBe(path.resolve(process.cwd(), "app/javascript"));
+  });
+
+  it("leaves @ alias intact when host pre-defines it", () => {
+    const contribution = buildConfigContribution({
+      resolve: { alias: { "@": "/custom/path" } },
+    });
+    expect(contribution.resolve.alias["@"]).toBeUndefined();
+  });
+
+  it("always registers the runtime alias (regardless of host config)", () => {
+    const contribution = buildConfigContribution({});
+    expect(contribution.resolve.alias[RUNTIME_IMPORT_SPECIFIER]).toBe(runtimePackagePath());
+  });
+
+  it("recognizes the array form of resolve.alias", () => {
+    const contribution = buildConfigContribution({
+      resolve: { alias: [{ find: "@", replacement: "/elsewhere" }] },
+    });
+    expect(contribution.resolve.alias["@"]).toBeUndefined();
+  });
+});
+
+describe("Story 8.0a — installServerFunctionsHooks() composition", () => {
+  it("preserves the host plugin's existing hooks", async () => {
+    const calls = [];
+    const plugin = {
+      name: "vite-plugin-ruact",
+      configResolved() {
+        calls.push("configResolved");
+      },
+      buildStart() {
+        calls.push("buildStart");
+      },
+    };
+    installServerFunctionsHooks(plugin);
+
+    await plugin.configResolved({ root: tmpdir });
+    await plugin.buildStart();
+
+    expect(calls).toEqual(["configResolved", "buildStart"]);
+  });
+
+  it("config() returns the resolved @ alias inline (Chunk 2 H1 — drop placeholder + " +
+    "configResolved rewrite)", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    installServerFunctionsHooks(plugin);
+
+    const merged = await plugin.config({ root: "/my/app" }, { mode: "development" });
+    expect(merged.resolve.alias["@"]).toBe(path.resolve("/my/app", "app/javascript"));
+  });
+
+  it("configResolved() re-canonicalizes @ when actual config.root differs from " +
+    "userConfig.root (Re-run 2026-05-14)", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    installServerFunctionsHooks(plugin);
+
+    // config() runs with userConfig.root=/cwd-guess (best effort)
+    const merged = await plugin.config({ root: "/cwd-guess" }, { mode: "development" });
+    expect(merged.resolve.alias["@"]).toBe(path.resolve("/cwd-guess", "app/javascript"));
+
+    // Vite then merges in the actual root from elsewhere (e.g., CLI flag) and
+    // hands us a resolved config — we must rewrite our best-effort placeholder.
+    const resolved = { root: "/real-root", resolve: { alias: { ...merged.resolve.alias } } };
+    await plugin.configResolved(resolved);
+    expect(resolved.resolve.alias["@"]).toBe(path.resolve("/real-root", "app/javascript"));
+  });
+
+  it("configResolved() leaves a host-defined @ alias alone even when canonical " +
+    "would differ (Re-run 2026-05-14)", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    installServerFunctionsHooks(plugin);
+
+    await plugin.config(
+      { root: "/cwd-guess", resolve: { alias: { "@": "/host/elsewhere" } } },
+      { mode: "development" },
+    );
+
+    const resolved = {
+      root: "/real-root",
+      resolve: { alias: { "@": "/host/elsewhere" } },
+    };
+    await plugin.configResolved(resolved);
+    // Host's value must survive the canonicalization step
+    expect(resolved.resolve.alias["@"]).toBe("/host/elsewhere");
+  });
+
+  it("config() awaits an async upstream handler (Chunk 2 M2 — async hook support)", async () => {
+    const calls = [];
+    const plugin = {
+      name: "vite-plugin-ruact",
+      async config() {
+        await new Promise((r) => setTimeout(r, 5));
+        calls.push("upstream-resolved");
+        return { server: { port: 5173 } };
+      },
+    };
+    installServerFunctionsHooks(plugin);
+
+    const merged = await plugin.config({ root: tmpdir }, { mode: "development" });
+    expect(calls).toEqual(["upstream-resolved"]);
+    // upstream survives merge
+    expect(merged.server.port).toBe(5173);
+    // sidecar contribution wins on resolve.alias
+    expect(merged.resolve.alias[RUNTIME_IMPORT_SPECIFIER]).toBe(runtimePackagePath());
+  });
+
+  it("config() preserves upstream's array-form resolve.alias instead of corrupting it " +
+    "into numeric-keyed object (Chunk 2 M2 — alias-array safety)", async () => {
+    const plugin = {
+      name: "vite-plugin-ruact",
+      config() {
+        return {
+          resolve: {
+            alias: [
+              { find: "~components", replacement: "/host/components" },
+              { find: "~lib", replacement: "/host/lib" },
+            ],
+          },
+        };
+      },
+    };
+    installServerFunctionsHooks(plugin);
+
+    const merged = await plugin.config({ root: "/my/app" }, { mode: "development" });
+    // After the patch, merged alias is still array-form (host's shape preserved)
+    expect(Array.isArray(merged.resolve.alias)).toBe(true);
+    // Sidecar entries prepended (so they take precedence in Vite's top-down order)
+    const finds = merged.resolve.alias.map((e) => e.find);
+    expect(finds).toContain("~components");
+    expect(finds).toContain("~lib");
+    expect(finds).toContain("@");
+    expect(finds).toContain(RUNTIME_IMPORT_SPECIFIER);
+  });
+
+  it("buildStart() awaits async upstream before running codegen (Chunk 2 M2)", async () => {
+    const order = [];
+    const plugin = {
+      name: "vite-plugin-ruact",
+      async buildStart() {
+        await new Promise((r) => setTimeout(r, 5));
+        order.push("upstream");
+      },
+    };
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    fs.writeFileSync(snapshotJson, JSON.stringify(baseSnapshot()));
+
+    installServerFunctionsHooks(plugin, { snapshotJson, generatedTs });
+    await plugin.configResolved({ root: tmpdir });
+    await plugin.buildStart();
+    order.push("after-buildStart");
+
+    // If upstream weren't awaited, "after-buildStart" would precede "upstream"
+    expect(order).toEqual(["upstream", "after-buildStart"]);
+    expect(fs.existsSync(generatedTs)).toBe(true);
+  });
+});
+
+describe("Story 8.0a — snapshot validation (Chunk 2 M1 — trust-boundary guards)", () => {
+  it("rejects snapshot whose version contains a newline (would break out of comment)", () => {
+    const evil = baseSnapshot({ version: "1\n// injected" });
+    expect(() => render(evil)).toThrow(/version.*line break|line break.*version/i);
+  });
+
+  it("rejects snapshot whose generated_at contains a newline", () => {
+    const evil = baseSnapshot({ generated_at: "2026-05-13\n// injected" });
+    expect(() => render(evil)).toThrow(/generated_at.*line break|line break.*generated_at/i);
+  });
+
+  it("rejects snapshot whose functions field is not an array", () => {
+    const evil = baseSnapshot({ functions: "oops" });
+    expect(() => render(evil)).toThrow(/functions.*array/);
+  });
+
+  it("rejects snapshot entry with unknown kind", () => {
+    const evil = baseSnapshot({
+      functions: [{ ruby_symbol: "foo", js_identifier: "foo", kind: "mutation" }],
+    });
+    expect(() => render(evil)).toThrow(/invalid kind/);
+  });
+
+  it("rejects snapshot with duplicate js_identifier entries", () => {
+    const evil = baseSnapshot({
+      functions: [
+        { ruby_symbol: "foo", js_identifier: "foo", kind: "action" },
+        { ruby_symbol: "bar", js_identifier: "foo", kind: "query" },
+      ],
+    });
+    expect(() => render(evil)).toThrow(/duplicate js_identifier "foo"/);
+  });
+
+  it("rejects snapshot entry whose js_identifier is a JS reserved word", () => {
+    const evil = baseSnapshot({
+      functions: [{ ruby_symbol: "delete", js_identifier: "delete", kind: "action" }],
+    });
+    expect(() => render(evil)).toThrow(/reserved JS word/);
+  });
+
+  it("R12 — rejects snapshot entry whose js_identifier is reserved by ruact " +
+    "(`revalidate` — would clash with the helper re-export)", () => {
+    const evil = baseSnapshot({
+      functions: [{ ruby_symbol: "revalidate", js_identifier: "revalidate", kind: "action" }],
+    });
+    expect(() => render(evil)).toThrow(/reserved by the ruact runtime\/codegen surface/);
+  });
+
+  it("R12 — rejects snapshot entry whose js_identifier is `_makeRef` " +
+    "(would clash with the codegen's runtime import)", () => {
+    const evil = baseSnapshot({
+      functions: [{ ruby_symbol: "make_ref", js_identifier: "_makeRef", kind: "action" }],
+    });
+    expect(() => render(evil)).toThrow(/reserved by the ruact runtime\/codegen surface/);
+  });
+
+  it("rejects snapshot whose version contains U+2028 LINE SEPARATOR " +
+    "(Pass-2 patch 2026-05-14 — JS LineTerminator parity)", () => {
+    const evil = baseSnapshot({ version: "1
// injected" });
+    expect(() => render(evil)).toThrow(/U\+2028/);
+  });
+
+  it("rejects snapshot whose generated_at contains U+2029 PARAGRAPH SEPARATOR " +
+    "(Pass-2 patch 2026-05-14)", () => {
+    const evil = baseSnapshot({ generated_at: "2026-05-14
// injected" });
+    expect(() => render(evil)).toThrow(/U\+2029/);
+  });
+
+  it("rejects snapshot missing a root key (Pass-2 patch 2026-05-14)", () => {
+    const evil = { generated_at: "x", functions: [] }; // no version
+    expect(() => render(evil)).toThrow(/missing required key "version"/);
+  });
+
+  it("rejects entry with empty ruby_symbol so we never emit _makeRef(\"\") " +
+    "(Pass-2 patch 2026-05-14)", () => {
+    const evil = baseSnapshot({
+      functions: [{ ruby_symbol: "", js_identifier: "foo", kind: "action" }],
+    });
+    expect(() => render(evil)).toThrow(/missing or empty ruby_symbol/);
+  });
+
+  it("rejects entry with missing ruby_symbol field (Pass-2 patch 2026-05-14)", () => {
+    const evil = baseSnapshot({
+      functions: [{ js_identifier: "foo", kind: "action" }],
+    });
+    expect(() => render(evil)).toThrow(/missing or empty ruby_symbol/);
+  });
+
+  it("rejects when snapshot itself is not an object (e.g., an array) " +
+    "(Pass-2 patch 2026-05-14)", () => {
+    expect(() => render([])).toThrow(/snapshot is not an object/);
+  });
+});
+
+describe("Story 8.0a — readSnapshot() (Chunk 2 M3 — log malformed JSON)", () => {
+  it("logs an error and returns null when JSON is malformed", () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    delete process.env.RUACT_SILENCE_LOG;
+    try {
+      const snap = path.join(tmpdir, "bad.json");
+      fs.writeFileSync(snap, "{ not json");
+      const result = readSnapshot(snap);
+      expect(result).toBeNull();
+      expect(errSpy).toHaveBeenCalledTimes(1);
+      expect(errSpy.mock.calls[0][0]).toMatch(/failed to parse server-functions bridge JSON/);
+    } finally {
+      errSpy.mockRestore();
+      process.env.RUACT_SILENCE_LOG = "1";
+    }
+  });
+
+  it("returns null silently (no error log) when file is simply absent", () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    delete process.env.RUACT_SILENCE_LOG;
+    try {
+      expect(readSnapshot(path.join(tmpdir, "missing.json"))).toBeNull();
+      expect(errSpy).not.toHaveBeenCalled();
+    } finally {
+      errSpy.mockRestore();
+      process.env.RUACT_SILENCE_LOG = "1";
+    }
+  });
+});
+
+describe("Story 8.0a — configureServer watcher (Chunk 2 m1 + m2)", () => {
+  function buildMockServer() {
+    const watcher = new EventEmitter();
+    watcher.add = vi.fn();
+    return { watcher };
+  }
+
+  it("registers the canonical snapshot path with chokidar (AC9)", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    installServerFunctionsHooks(plugin, { snapshotJson, generatedTs });
+
+    await plugin.configResolved({ root: tmpdir });
+    const server = buildMockServer();
+    await plugin.configureServer(server);
+
+    expect(server.watcher.add).toHaveBeenCalledWith(path.resolve(snapshotJson));
+  });
+
+  it("re-runs codegen when the watcher emits 'change' for the snapshot path", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    fs.writeFileSync(snapshotJson, JSON.stringify(baseSnapshot()));
+    installServerFunctionsHooks(plugin, { snapshotJson, generatedTs });
+
+    await plugin.configResolved({ root: tmpdir });
+    const server = buildMockServer();
+    await plugin.configureServer(server);
+
+    fs.writeFileSync(
+      snapshotJson,
+      JSON.stringify(
+        baseSnapshot({
+          functions: [{ ruby_symbol: "demo_ping", js_identifier: "demoPing", kind: "action" }],
+        }),
+      ),
+    );
+    server.watcher.emit("change", snapshotJson);
+
+    expect(fs.readFileSync(generatedTs, "utf8")).toContain("export const demoPing");
+  });
+
+  it("re-runs codegen when the watcher emits 'add' for the snapshot path", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    installServerFunctionsHooks(plugin, { snapshotJson, generatedTs });
+
+    await plugin.configResolved({ root: tmpdir });
+    const server = buildMockServer();
+    await plugin.configureServer(server);
+
+    fs.writeFileSync(snapshotJson, JSON.stringify(baseSnapshot()));
+    server.watcher.emit("add", snapshotJson);
+
+    expect(fs.existsSync(generatedTs)).toBe(true);
+    expect(fs.readFileSync(generatedTs, "utf8")).toContain("AUTO-GENERATED");
+  });
+
+  it("ignores events for unrelated files", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    installServerFunctionsHooks(plugin, { snapshotJson, generatedTs });
+
+    await plugin.configResolved({ root: tmpdir });
+    const server = buildMockServer();
+    await plugin.configureServer(server);
+
+    server.watcher.emit("change", path.join(tmpdir, "other.json"));
+    expect(fs.existsSync(generatedTs)).toBe(false);
+  });
+
+  it("matches non-canonical event paths against the snapshot path (Chunk 2 m1 — " +
+    "path.resolve canonicalization)", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    fs.writeFileSync(snapshotJson, JSON.stringify(baseSnapshot()));
+    installServerFunctionsHooks(plugin, { snapshotJson, generatedTs });
+
+    await plugin.configResolved({ root: tmpdir });
+    const server = buildMockServer();
+    await plugin.configureServer(server);
+
+    fs.writeFileSync(
+      snapshotJson,
+      JSON.stringify(
+        baseSnapshot({
+          functions: [{ ruby_symbol: "categories", js_identifier: "categories", kind: "query" }],
+        }),
+      ),
+    );
+    // Emit a path that's logically the same file but with `./` inserted
+    const noncanonical = path.join(path.dirname(snapshotJson), ".", path.basename(snapshotJson));
+    server.watcher.emit("change", noncanonical);
+
+    expect(fs.readFileSync(generatedTs, "utf8")).toContain("export const categories");
+  });
+
+  it("resolves relative event paths against rootDir, not process.cwd() " +
+    "(Re-run m4 2026-05-14)", async () => {
+    const plugin = { name: "vite-plugin-ruact" };
+    const snapshotJson = path.join(tmpdir, "snap.json");
+    const generatedTs = path.join(tmpdir, "out.ts");
+    fs.writeFileSync(snapshotJson, JSON.stringify(baseSnapshot()));
+    installServerFunctionsHooks(plugin, { snapshotJson, generatedTs });
+
+    // rootDir is tmpdir; cwd is the test runner's cwd (NOT tmpdir).
+    await plugin.configResolved({ root: tmpdir });
+    const server = buildMockServer();
+    await plugin.configureServer(server);
+
+    fs.writeFileSync(
+      snapshotJson,
+      JSON.stringify(
+        baseSnapshot({
+          functions: [{ ruby_symbol: "demo_ping", js_identifier: "demoPing", kind: "action" }],
+        }),
+      ),
+    );
+
+    // Chokidar can emit a path relative to the watched root (not cwd).
+    // path.relative(rootDir, snapshotJson) is "snap.json" — when watcher
+    // emits that bare name, we must resolve it against rootDir.
+    const relative = path.relative(tmpdir, snapshotJson);
+    server.watcher.emit("change", relative);
+
+    expect(fs.readFileSync(generatedTs, "utf8")).toContain("export const demoPing");
+  });
+});
+
+describe("Story 8.0a — Ruby parity (Task 8.5)", () => {
+  // The Ruby codegen reads the same fixture and must produce byte-identical
+  // output. If this test fails, the Ruby OR JS side drifted — diff the outputs
+  // and bring them back into sync rather than normalizing in the assertion.
+
+  const fixture = {
+    version: 1,
+    generated_at: "2026-05-13T12:34:56Z",
+    functions: [
+      {
+        ruby_symbol: "alpha",
+        js_identifier: "alpha",
+        kind: "query",
+        controller: "AlphaController",
+      },
+      {
+        ruby_symbol: "create_post",
+        js_identifier: "createPost",
+        kind: "action",
+        controller: "PostsController",
+      },
+      {
+        ruby_symbol: "_internal_dump",
+        js_identifier: "_internalDump",
+        kind: "action",
+        controller: "InternalsController",
+      },
+    ],
+  };
+
+  it("Ruby's Codegen.render and JS's render produce byte-identical output", () => {
+    const jsOutput = render(fixture);
+
+    // Shell out to Ruby. The gem lib path is two levels up from this file.
+    const gemLibPath = path.resolve(
+      path.dirname(new URL(import.meta.url).pathname),
+      "..",
+      "..",
+      "..",
+      "lib",
+    );
+    const fixtureJson = JSON.stringify(fixture);
+    const script =
+      'require "ruact/server_functions/codegen"; ' +
+      'require "json"; ' +
+      `print Ruact::ServerFunctions::Codegen.render(JSON.parse('${fixtureJson}'))`;
+    const rubyOutput = execFileSync("ruby", ["-I", gemLibPath, "-e", script], {
+      encoding: "utf8",
+    });
+
+    expect(jsOutput).toBe(rubyOutput);
+  });
+});
+
+describe("Story 9.3 — route-driven (v2) render + parity", () => {
+  const v2Fixture = {
+    version: 2,
+    generated_at: "2026-06-09T00:00:00Z",
+    functions: [
+      {
+        js_identifier: "createPost",
+        kind: "action",
+        http_method: "POST",
+        path: "/posts",
+        segments: [],
+        controller: "posts",
+        action: "create",
+      },
+      {
+        js_identifier: "updatePost",
+        kind: "action",
+        http_method: "PATCH",
+        path: "/posts/:id",
+        segments: ["id"],
+        controller: "posts",
+        action: "update",
+      },
+    ],
+  };
+
+  it("dispatches on version 2 and emits _makeServerFunction calls with real path+verb", () => {
+    const out = render(v2Fixture);
+    expect(out).toContain('import { _makeServerFunction } from "ruact/server-functions-runtime";');
+    expect(out).toContain('_makeServerFunction({ method: "POST", path: "/posts", segments: [] });');
+    expect(out).toContain('_makeServerFunction({ method: "PATCH", path: "/posts/:id", segments: ["id"] });');
+    expect(out).toContain('export { revalidate } from "ruact/server-functions-runtime";');
+    // v2 actions keep the Story 8.2 intersection signature (form action support)
+    expect(out).toContain("& ((formData: FormData) => Promise<void>)");
+  });
+
+  it("emits the empty-v2 module when no routes are exposed", () => {
+    const out = render({ version: 2, generated_at: "2026-06-09T00:00:00Z", functions: [] });
+    expect(out).toContain("void _makeServerFunction;");
+    expect(out).toContain("(no server functions exposed yet");
+  });
+
+  it("rejects a v2 entry with an invalid http_method", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "createPost", kind: "action", http_method: "GET", path: "/posts", segments: [] },
+        ],
+      }),
+    ).toThrow(/invalid.*http_method/i);
+  });
+
+  it("rejects a v2 entry declaring a segment absent from the path", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "updatePost", kind: "action", http_method: "PATCH", path: "/posts", segments: ["id"] },
+        ],
+      }),
+    ).toThrow(/absent from path/);
+  });
+
+  it("rejects a v2 path with an undeclared dynamic segment (bidirectional guard)", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "updatePost", kind: "action", http_method: "PATCH", path: "/posts/:id", segments: [] },
+        ],
+      }),
+    ).toThrow(/not declared in segments/);
+  });
+
+  it("rejects a v2 segment that only substring-matches a longer path token", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "updatePost", kind: "action", http_method: "PATCH", path: "/posts/:id_extra", segments: ["id"] },
+        ],
+      }),
+    ).toThrow(/absent from path/);
+  });
+
+  it("rejects a v2 entry named after the v2 runtime accessor (_makeServerFunction)", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "_makeServerFunction", kind: "action", http_method: "POST", path: "/x", segments: [] },
+        ],
+      }),
+    ).toThrow(/reserved/);
+  });
+
+  it("Ruby's render and JS's render produce byte-identical v2 output", () => {
+    const jsOutput = render(v2Fixture);
+    const gemLibPath = path.resolve(
+      path.dirname(new URL(import.meta.url).pathname),
+      "..",
+      "..",
+      "..",
+      "lib",
+    );
+    const fixtureJson = JSON.stringify(v2Fixture);
+    const script =
+      'require "ruact/server_functions/codegen"; ' +
+      'require "json"; ' +
+      `print Ruact::ServerFunctions::Codegen.render(JSON.parse('${fixtureJson}'))`;
+    const rubyOutput = execFileSync("ruby", ["-I", gemLibPath, "-e", script], {
+      encoding: "utf8",
+    });
+
+    expect(jsOutput).toBe(rubyOutput);
+  });
+});