@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/incrementalBuilder/buildBatchProtocol.ts

@@ -3,23 +3,10 @@ import type { BaseBuildArtifact, CssPayload, PagesBundlePayload } from "akanjs/s
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
-/**
- * `base` is the boot build (`SsrBaseArtifactBuilder`) and is never batched with the others: it is what a
- * builder runs before it can serve anything, where the rest are per-save work. It earns its place here
- * for the same reason as the others — measured on `apps/akan`, it retains **+1143 MB** of bundler arena
- * that only a process exit returns, which was 65 % of the builder's whole idle footprint.
- */
+// `base` is the boot build: it always runs alone, before the builder can serve anything.
 export type BuildBatchNeed = "base" | "pages" | "css" | "csr";
 
-/**
- * One generation of build work, handed to a process that exits when it is done.
- *
- * Everything here is JSON: the worker is spawned per batch, so state that the long-lived watcher
- * caches for the session has to travel by value. Two fields exist purely to keep behaviour identical
- * to the in-process version — `pageKeys` because rediscovering them costs ~220ms on a 177-route app
- * (route-export validation), and `optimizedFonts` because fonts are only re-optimized when a font file
- * actually changed.
- */
+// JSON only: the worker is spawned per batch and receives this in its argv.
 export interface BuildBatchRequest {
   appName: string;
   workspaceRoot: string;
@@ -27,37 +14,22 @@ export interface BuildBatchRequest {
   generation: number;
   needs: BuildBatchNeed[];
   changedFiles: string[];
-  /** Page keys the watcher already validated, or null to make the worker discover them itself. */
-  pageKeys: string[] | null;
-  /** Previous font optimization, reused unless this batch touched one of its files. */
-  optimizedFonts: OptimizedFonts | null;
-  /** Previous css assets, so an unchanged compile skips the broadcast instead of busting hashes. */
-  cssAssets: PagesBatchCssAssets | null;
-  /** Absolute artifact directory; the worker writes css assets under it. */
+  pageKeys: string[] | null; // null: the worker discovers them itself
+  optimizedFonts: OptimizedFonts | null; // reused unless this batch touched one of its files
+  cssAssets: PagesBatchCssAssets | null; // an unchanged compile skips the broadcast instead of busting hashes
   artifactDir: string;
 }
 
 export type PagesBatchCssAssets = CssPayload["cssAssets"];
 
-/**
- * What the watcher folds back into its own state once the worker is done.
- *
- * Deliberately small: the payloads browsers are waiting on are *streamed* as each need finishes
- * (`pages-updated`, `css-updated`, `build-status`, relayed straight through), so a page reload is not
- * held back by a css compile that has not started yet. Only state the next batch needs travels here.
- */
+// Browser payloads stream as each need finishes; only state the next batch needs travels back here.
 export interface BuildBatchResult {
   generation: number;
   cssAssets?: PagesBatchCssAssets;
   optimizedFonts?: OptimizedFonts;
-  /**
-   * Present only for a `base` batch. The same object the worker wrote to `base-artifact.json`, returned
-   * here so the watcher does not have to read its own boot build back off disk.
-   */
-  artifact?: BaseBuildArtifact;
+  artifact?: BaseBuildArtifact; // `base` batches only
   errors: Partial<Record<BuildBatchNeed, string>>;
-  /** The worker died before reporting, so it streamed no `build-status` of its own for these needs. */
-  crashed?: boolean;
+  crashed?: boolean; // died before reporting, so it streamed no build-status for these needs
 }
 
 export type BuildBatchMessage = { type: "build-batch-result"; data: BuildBatchResult };

package/incrementalBuilder/buildBatchRunner.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { createTempApp, tempRoots, writeText } from "../testHelpers";
+import { BuildBatchRunner } from "./buildBatchRunner";
+
+const track = tempRoots();
+
+describe("BuildBatchRunner", () => {
+  test("reports a boot build the bundler refuses with where each reason sits in the workspace", async () => {
+    // Inside the checkout so `akanjs/server` resolves to its source: from the OS temp dir Bun auto-installs npm's 2.x.
+    const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(path.join(appDir, "env/env.client.ts"), "export const env = {} as const;\n");
+    await writeText(
+      path.join(appDir, "page/_index.tsx"),
+      'import { gone } from "./not-there";\nexport default gone;\n',
+    );
+
+    const result = await new BuildBatchRunner({ workspaceRoot: root, cwd: appDir }).run({
+      appName: "demo",
+      workspaceRoot: root,
+      repoName: "repo",
+      generation: 0,
+      needs: ["base"],
+      changedFiles: [],
+      pageKeys: null,
+      optimizedFonts: null,
+      cssAssets: null,
+      artifactDir: path.join(appDir, ".akan/artifact"),
+    });
+
+    expect(result.errors.base).toContain('"./not-there" (apps/demo/page/_index.tsx:1:22)');
+  }, 30_000);
+});

package/incrementalBuilder/buildBatchRunner.ts

@@ -3,25 +3,9 @@ import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
 import type { BuildBatchMessage, BuildBatchRequest, BuildBatchResult } from "./buildBatchProtocol";
 
-/**
- * Runs one `BuildBatchRequest` in a fresh process and resolves with what it produced.
- *
- * The watcher serializes every batch through its own work queue, so this deliberately has no pool: one
- * worker exists at a time, and it exits before the next one starts. That is the whole point — the
- * bundler arenas `Bun.build` never frees go back to the OS with the process.
- *
- * A worker that dies without reporting is not fatal. Every need it was given comes back as an error, the
- * watcher reports a red build-status for that generation, and the last-good artifact keeps serving —
- * the same contract a failed in-process build had. It must never take the watcher down with it: the
- * watcher is the dev server's file watcher, so nothing would notice the fix.
- */
+// No pool on purpose: one worker at a time, exiting after its batch, returns the arenas `Bun.build` never frees.
+// A worker that dies without reporting must not take the watcher down; its needs come back as errors.
 export class BuildBatchRunner {
-  static readonly #entryCandidates = (workspaceRoot: string) => [
-    path.join(workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(import.meta.dir, "buildBatch.proc.js"),
-    path.join(import.meta.dir, "buildBatch.proc.ts"),
-  ];
   #logger = new Logger("BuildBatchRunner");
   #entry: string | null = null;
   #workspaceRoot: string;
@@ -33,7 +17,12 @@ export class BuildBatchRunner {
 
   async #resolveEntry(): Promise<string> {
     if (this.#entry) return this.#entry;
-    const candidates = BuildBatchRunner.#entryCandidates(this.#workspaceRoot);
+    const candidates = [
+      path.join(this.#workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(this.#workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(import.meta.dir, "buildBatch.proc.js"),
+      path.join(import.meta.dir, "buildBatch.proc.ts"),
+    ];
     for (const candidate of candidates) {
       if (!(await Bun.file(candidate).exists())) continue;
       this.#entry = candidate;
@@ -42,11 +31,6 @@ export class BuildBatchRunner {
     throw new Error(`[build-batch] worker entry not found; looked in: ${candidates.join(", ")}`);
   }
 
-  /**
-   * `onMessage` receives everything the worker streams as it goes — `pages-updated`, `css-updated`,
-   * `build-status` — so the watcher can relay each one the moment it is produced instead of holding a
-   * page reload until the whole batch is done.
-   */
   async run(
     request: BuildBatchRequest,
     onMessage: (message: BuilderMessage) => void = () => undefined,
@@ -54,8 +38,7 @@ export class BuildBatchRunner {
     const started = Date.now();
     const entry = await this.#resolveEntry();
     let result: BuildBatchResult | null = null;
-    // The request travels in argv rather than over IPC so the worker can start on its first tick
-    // instead of waiting for a handshake it would have to synchronize against.
+    // argv rather than IPC, so the worker starts on its first tick instead of waiting for a handshake.
     const proc = Bun.spawn(["bun", entry, JSON.stringify(request)], {
       cwd: this.#cwd,
       env: process.env,
@@ -74,11 +57,7 @@ export class BuildBatchRunner {
       );
       return result;
     }
-    // A worker the kernel OOM-killed exits with code `null` and `SIGKILL`, which without the signal
-    // reads exactly like an ordinary crash — and the two have opposite fixes: one is a build error to
-    // find, the other is a memory limit to raise. The peak here is the largest transient in the tree
-    // (a boot build measured 548MB on a tenant app, 1.1GB on apps/akan), so on a small sandbox this is
-    // the process the kernel reaches for first.
+    // An OOM kill (code null, SIGKILL) reads like a crash without the signal, and needs the opposite fix.
     const message = proc.signalCode
       ? `build worker was killed by ${proc.signalCode} before reporting a result${
           proc.signalCode === "SIGKILL" ? " — most often the kernel OOM killer; check the sandbox's memory limit" : ""

package/incrementalBuilder/builderChannel.test.ts

@@ -1,30 +1,18 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
+import { tempDirs } from "../testHelpers";
 import { BuilderChannel } from "./builderChannel";
 
-const tempDirs: string[] = [];
-
-afterEach(async () => {
-  for (const dir of tempDirs.splice(0)) await rm(dir, { recursive: true, force: true });
-});
+const tempDir = tempDirs("builder-channel-");
 
 type SendMode = "drain" | "await" | "bare";
 
-/**
- * Run a child that sends what the builder sends and then exits the way the recycle drain does, and
- * report what the parent actually received.
- *
- * `payload` picks the message shape, because shape decides whether a bare send survives: `manifest` is a
- * map of many short strings (a `build-route-res` delta), `css` is one long string (a base64 stylesheet).
- */
+// Shape decides whether a bare send survives: `manifest` is many short strings, `css` one long string.
 const sendThenExit = async (
   bytes: number,
   { mode, payload }: { mode: SendMode; payload: "manifest" | "css" },
 ): Promise<Array<{ type?: string }>> => {
-  const dir = await mkdtemp(path.join(os.tmpdir(), "builder-channel-"));
-  tempDirs.push(dir);
+  const dir = await tempDir();
   const entry = path.join(dir, "child.ts");
   const modulePath = JSON.stringify(path.join(import.meta.dir, "builderChannel"));
   const build =
@@ -63,44 +51,42 @@ const sendThenExit = async (
   return received;
 };
 
+const withDeferredFlushes = async (fn: (flushes: Array<() => void>) => Promise<void>) => {
+  const send = process.send;
+  const flushes: Array<() => void> = [];
+  try {
+    (process as { send?: unknown }).send = (_msg: unknown, _h: unknown, _o: unknown, cb: () => void) => {
+      flushes.push(cb);
+      return true;
+    };
+    await fn(flushes);
+  } finally {
+    (process as { send?: unknown }).send = send;
+  }
+};
+
 describe("BuilderChannel", () => {
   test("delivers a reply too large for the pipe buffer before the process exits", async () => {
     expect(await sendThenExit(1_000_000, { mode: "await", payload: "manifest" })).toMatchObject([{ id: 7 }]);
-    // A manifest delta is usually well past the buffer, but the small case must keep working too.
     expect(await sendThenExit(0, { mode: "await", payload: "manifest" })).toMatchObject([{ id: 7 }]);
   });
 
   test("a drained event survives the exit even though nobody awaited it", async () => {
-    // The event path: `css-updated` is relayed with no caller to await it, and the recycle drain exits
-    // milliseconds later. Only `drain()` stands between the two.
     expect(await sendThenExit(200_000, { mode: "drain", payload: "css" })).toMatchObject([{ type: "css-updated" }]);
   });
 
-  /**
-   * darwin only, measured: on Linux a 1MB message sent immediately before `process.exit` **arrives in
-   * full**, so the loss this control demonstrates does not reproduce there and the assertion would fail
-   * for the right reason on the wrong platform. `BuilderChannel` itself stays correct and costs nothing
-   * on Linux — the bug it prevents is one macOS developers hit and a Linux fleet does not.
-   */
+  // darwin only: on Linux a message sent right before `process.exit` arrives in full, so the loss does not reproduce.
   test.skipIf(process.platform !== "darwin")(
     "without the flush wait the same messages are lost, which is why this class exists",
     async () => {
       // Controls, not requirements: if a future bun flushes ipc writes on exit, these fail and say so.
       expect(await sendThenExit(1_000_000, { mode: "bare", payload: "manifest" })).toEqual([]);
-      // 20KB of css, far below the 64KB the manifest shape survives — one long string dies much earlier,
-      // so no size threshold would have been safe to special-case.
       expect(await sendThenExit(20_000, { mode: "bare", payload: "css" })).toEqual([]);
     },
   );
 
   test("drain resolves only once every tracked send has flushed", async () => {
-    const send = process.send;
-    const flushes: Array<() => void> = [];
-    try {
-      (process as { send?: unknown }).send = (_msg: unknown, _h: unknown, _o: unknown, cb: () => void) => {
-        flushes.push(cb);
-        return true;
-      };
+    await withDeferredFlushes(async (flushes) => {
       BuilderChannel.emit({ type: "builder-ready" });
       BuilderChannel.emit({ type: "builder-ready" });
       let drained = false;
@@ -113,31 +99,20 @@ describe("BuilderChannel", () => {
       expect(drained).toBe(false);
       flushes[1]?.();
       expect(await draining).toBe(2);
-    } finally {
-      (process as { send?: unknown }).send = send;
-    }
+    });
   });
 
   test("a send started while draining is drained too", async () => {
-    const send = process.send;
-    const flushes: Array<() => void> = [];
-    try {
-      (process as { send?: unknown }).send = (_msg: unknown, _h: unknown, _o: unknown, cb: () => void) => {
-        flushes.push(cb);
-        return true;
-      };
+    await withDeferredFlushes(async (flushes) => {
       BuilderChannel.emit({ type: "builder-ready" });
       const draining = BuilderChannel.drain();
-      // What `#reportMetrics` does from a work item's `finally`, after the drain has begun.
       BuilderChannel.emit({ type: "builder-metrics", data: { rssBytes: 1, generation: 1, workCount: 1 } });
       for (let i = 0; i < 4 && flushes.length; i++) {
         flushes.shift()?.();
         await Bun.sleep(1);
       }
       expect(await draining).toBe(2);
-    } finally {
-      (process as { send?: unknown }).send = send;
-    }
+    });
   });
 
   test("resolves instead of hanging when there is no ipc channel", async () => {

package/incrementalBuilder/builderChannel.ts

@@ -1,42 +1,18 @@
 import type { BuilderMessage } from "akanjs/server";
 
-/**
- * Every message the builder sends its host, and the record of which of those writes have actually left
- * the process.
- *
- * `process.exit` discards an ipc write that has not flushed, and this process exits routinely — the
- * recycle that keeps its RSS under the ceiling ends in `process.exit(0)`. Whether a given message
- * survives that depends on its *shape*, not only its size. Measured on bun 1.3.14 (darwin,
- * `serialization: "advanced"`), send-then-exit-immediately, 20 rounds each:
- *
- * - one long string: 8KB delivered 20/20, 16KB delivered **0/20**
- * - many short strings: 60KB delivered 20/20, 100KB delivered **0/20**
- *
- * `css-updated` is the first shape (a base64 stylesheet per url) and `build-route-res` the second (a
- * manifest delta), so neither sits safely under a threshold worth relying on. Nothing here assumes one:
- * every send reports when it flushed, and `drain` is what `shutdown` awaits before exiting.
- *
- * A natural exit does *not* have this problem — a process that simply returns from `main` flushes 1MB
- * 20/20 — which is why the disposable build worker needs none of this. Only an explicit `process.exit`
- * cuts a write short.
- */
+// `process.exit` drops an ipc write that has not flushed (a natural exit does not), and whether one survives
+// depends on the message's shape as well as its size — so every send reports its flush and `shutdown` drains.
 export class BuilderChannel {
-  /**
-   * Bound so a runtime that ever stops invoking the flush callback costs one late message instead of
-   * wedging the shutdown drain until the host's kill watchdog fires.
-   */
+  // Bounded so a runtime that never calls the flush callback costs one late message, not a wedged drain.
   static readonly #flushTimeoutMs = 5_000;
-  /** Sends that have not flushed yet; `drain` only ever needs to await them all. */
   static readonly #flushing = new Set<Promise<void>>();
 
-  /** Send, and resolve once the write has left this process. */
   static send(message: BuilderMessage): Promise<void> {
     const send = process.send;
     if (!send) return Promise.resolve();
     const flushed = new Promise<void>((resolve) => {
       const timer = setTimeout(resolve, BuilderChannel.#flushTimeoutMs);
-      // A failed send has nothing to retry: the host answers an unanswered request id itself when this
-      // process exits, and a lost event is superseded by the next generation's.
+      // No retry: the host answers an orphaned request id on exit, and a lost event is superseded next generation.
       send.call(process, message, undefined, undefined, () => {
         clearTimeout(timer);
         resolve();
@@ -47,19 +23,12 @@ export class BuilderChannel {
     return flushed;
   }
 
-  /**
-   * Send an event no caller awaits. Tracked exactly like `send`, which is the whole point: a relayed
-   * `css-updated` has nobody to await it, so `drain` is the only thing standing between it and the exit.
-   */
+  // Tracked like `send`: for an event nobody awaits, `drain` is all that stands between it and the exit.
   static emit(message: BuilderMessage): void {
     void BuilderChannel.send(message);
   }
 
-  /**
-   * Resolve once every send handed over so far has flushed, and report how many were still in flight.
-   * Sends started *while* draining are covered too — `#reportMetrics` can fire from a work item's
-   * `finally`, after the drain has already begun.
-   */
+  // Loops because `#reportMetrics` can send from a work item's `finally` after the drain has begun.
   static async drain(): Promise<number> {
     let flushed = 0;
     while (BuilderChannel.#flushing.size) {

package/incrementalBuilder/builderRequestRouter.test.ts

@@ -10,7 +10,6 @@ const routeReq = (id: number, routeId: string): BuilderReq => ({
   knownEntries: [],
 });
 
-/** `routeId` is what tells one generation's answer from the other's; the rest is an empty delta. */
 const routeRes = (id: number, routeId: string): Extract<BuilderRes, { ok: true }> => ({
   type: "build-route-res",
   id,
@@ -23,7 +22,6 @@ describe("BuilderRequestRouter", () => {
     const router = new BuilderRequestRouter();
     router.startGeneration();
 
-    // Everything but the id travels untouched; the builder never learns it was renumbered.
     const first = router.issue(routeReq(1, "/home"));
     const second = router.issue(routeReq(2, "/about"));
     expect(first.routeId).toBe("/home");
@@ -35,11 +33,6 @@ describe("BuilderRequestRouter", () => {
     expect(router.inFlightCount).toBe(0);
   });
 
-  /**
-   * The defect this class exists for. `BuilderRpc` numbers from 1 in every backend process, so without
-   * renumbering the second generation's `id: 1` request is settled by the first generation's answer —
-   * a page rendered against another route's client manifest — and its own answer is then dropped.
-   */
   test("does not deliver a dead generation's answer to the backend that replaced it", () => {
     const router = new BuilderRequestRouter();
     router.startGeneration();
@@ -70,7 +63,6 @@ describe("BuilderRequestRouter", () => {
     router.startGeneration();
     const outgoing = router.issue(routeReq(4, "/home"));
 
-    // The caller answers the backend itself in this case, so a late builder answer must not answer it again.
     router.withdraw(outgoing.id);
     expect(router.inFlightCount).toBe(0);
     expect(router.settle(routeRes(outgoing.id, "/home"))).toBeNull();

package/incrementalBuilder/builderRequestRouter.ts

@@ -3,19 +3,8 @@ import type { BuilderCsrReq, BuilderCsrRes, BuilderReq, BuilderRes } from "akanj
 type BuilderRequest = BuilderReq | BuilderCsrReq;
 type BuilderResponse = BuilderRes | BuilderCsrRes;
 
-/**
- * Correlation ids for builder requests, renumbered by the dev host so they survive a backend restart.
- *
- * `BuilderRpc` numbers its requests from 1 in each backend *process*, and the host relays them to a
- * builder that outlives the backend. So after a restart the two generations collide on id 1: the builder
- * answers the request the *previous* backend made, the host relays it, and the new backend settles its own
- * request of that number with another route's manifest delta — a page rendered against client modules that
- * were never built for it. The answer it was actually waiting for then arrives to an empty pending map and
- * is dropped, so the correct build is discarded too.
- *
- * A host-owned id fixes it without touching the protocol: neither the backend nor the builder learns that
- * anything was renumbered, and a response whose generation is gone is discarded instead of misdelivered.
- */
+// `BuilderRpc` numbers from 1 per backend process while the builder outlives backends, so ids collide across a
+// restart; host-owned ids keep a dead generation's answer from settling the new backend's request.
 export class BuilderRequestRouter {
   #generation = 0;
   #nextId = 1;
@@ -29,33 +18,25 @@ export class BuilderRequestRouter {
     return this.#inFlight.size;
   }
 
-  /**
-   * Begin a new backend generation, abandoning every request the previous one owned.
-   *
-   * Nothing is answered on the way out: the process that asked is gone, and its `BuilderRpc` went with it.
-   */
+  // Abandons the previous generation's requests unanswered: the backend that asked is gone.
   startGeneration(): number {
     this.#generation += 1;
     this.#inFlight.clear();
     return this.#generation;
   }
 
-  /** The request to forward to the builder, carrying this host's id in place of the backend's. */
   issue<T extends BuilderRequest>(message: T): T {
     const id = this.#nextId++;
     this.#inFlight.set(id, { backendId: message.id, generation: this.#generation });
     return { ...message, id };
   }
 
-  /** Give an id back when the send failed, so the caller answers the backend itself. */
+  // For a failed send, after which the caller answers the backend itself.
   withdraw(id: number): void {
     this.#inFlight.delete(id);
   }
 
-  /**
-   * The response to forward to the backend with its own id restored, or `null` when no live backend is
-   * waiting for it — either it was never issued or the generation that issued it has been replaced.
-   */
+  // null when no live backend is waiting: never issued, or its generation was replaced.
   settle<T extends BuilderResponse>(message: T): T | null {
     const request = this.#inFlight.get(message.id);
     if (!request) return null;

package/incrementalBuilder/devWatchBatch.test.ts

@@ -1,19 +1,22 @@
 import { describe, expect, test } from "bun:test";
 import path from "node:path";
-import { DevChangePlanner } from "../frontendBuild";
+import { DevChangePlanner, type GeneratedIndexSyncResult } from "../frontendBuild";
 import { prepareDevWatchBatch } from "./devWatchBatch";
 
+const prepare = (root: string, generation: number, file: string, indexSync: GeneratedIndexSyncResult) =>
+  prepareDevWatchBatch({
+    generation,
+    batch: { files: [file], kinds: new Set(["code"]) },
+    indexSync,
+    changePlanner: new DevChangePlanner({ workspaceRoot: root }),
+  });
+
 describe("prepareDevWatchBatch", () => {
   test("includes generated indexes in the same invalidate generation", () => {
     const root = path.resolve("/repo");
     const changedFile = path.join(root, "libs/shared/common/foo.ts");
     const generatedIndex = path.join(root, "libs/shared/common/index.ts");
-    const prepared = prepareDevWatchBatch({
-      generation: 12,
-      batch: { files: [changedFile], kinds: new Set(["code"]) },
-      indexSync: { changedFiles: [generatedIndex], errors: [] },
-      changePlanner: new DevChangePlanner({ workspaceRoot: root }),
-    });
+    const prepared = prepare(root, 12, changedFile, { changedFiles: [generatedIndex], errors: [] });
 
     expect(prepared.hasSyncErrors).toBe(false);
     expect(prepared.files).toEqual([changedFile, generatedIndex]);
@@ -29,12 +32,7 @@ describe("prepareDevWatchBatch", () => {
       const root = path.resolve("/repo");
       const changedFile = path.join(root, "libs/shared", facet, "tmpExample.ts");
       const generatedIndex = path.join(root, "libs/shared", facet, "index.ts");
-      const prepared = prepareDevWatchBatch({
-        generation: 20,
-        batch: { files: [changedFile], kinds: new Set(["code"]) },
-        indexSync: { changedFiles: [generatedIndex], errors: [] },
-        changePlanner: new DevChangePlanner({ workspaceRoot: root }),
-      });
+      const prepared = prepare(root, 20, changedFile, { changedFiles: [generatedIndex], errors: [] });
 
       expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
       expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
@@ -45,11 +43,9 @@ describe("prepareDevWatchBatch", () => {
 
   test("marks failed generated index sync as an error generation", () => {
     const root = "/repo";
-    const prepared = prepareDevWatchBatch({
-      generation: 13,
-      batch: { files: [`${root}/libs/shared/common/foo.ts`], kinds: new Set(["code"]) },
-      indexSync: { changedFiles: [], errors: ["sync failed"] },
-      changePlanner: new DevChangePlanner({ workspaceRoot: root }),
+    const prepared = prepare(root, 13, `${root}/libs/shared/common/foo.ts`, {
+      changedFiles: [],
+      errors: ["sync failed"],
     });
 
     expect(prepared.hasSyncErrors).toBe(true);