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

package/selectModel.ts

@@ -3,9 +3,8 @@ import { select } from "@inquirer/prompts";
 
 export const selectModel = async (modulePath: string) => {
   const modelNames = readdirSync(`${modulePath}/lib`).filter((dir) => !dir.includes(".") && !dir.startsWith("_"));
-  const modelName = await select({
+  return await select({
     message: "Select the model to create the unit for",
     choices: modelNames.map((name) => ({ name, value: name })),
   });
-  return modelName;
 };

package/semver.ts

@@ -1,14 +1,12 @@
-// `Bun.semver.order` compares range strings loosely — `^3.1049.0` vs `^3.721.0` answers 0 — so the
-// operator prefix has to come off before it sees the version.
+// `Bun.semver.order` compares ranges loosely (`^3.1049.0` vs `^3.721.0` answers 0), so the operator comes off first.
 const stripRangeOperator = (version: string) => version.replace(/^[\s^~>=<v]+/, "").trim();
 
-const parseVersion = (version: string): number[] => {
-  return version
+const parseVersion = (version: string): number[] =>
+  version
     .replace(/^[^\d]*/, "")
     .split(/[.-]/)
     .map((part) => Number.parseInt(part, 10))
     .map((part) => (Number.isFinite(part) ? part : 0));
-};
 
 const compareNumeric = (a: string, b: string): number => {
   const left = parseVersion(a);

package/slicePlanner.test.ts

@@ -1,30 +1,13 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { AppExecutor, Executor, WorkspaceExecutor } from "./executors";
 import { formatSlicePlan, SlicePlanner } from "./slicePlanner";
+import { isolateEnv, tempDirs, writeText as write } from "./testHelpers";
 import type { PackageJson } from "./types";
 
-const tempRoots: string[] = [];
-const originalEnv = { ...process.env };
-
-beforeEach(() => {
-  process.env = { ...originalEnv };
-  process.env.AKAN_PUBLIC_REPO_NAME = "workspace";
-  process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
-  process.env.AKAN_PUBLIC_ENV = "local";
-});
-
-afterEach(async () => {
-  process.env = { ...originalEnv };
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
+isolateEnv({ AKAN_PUBLIC_REPO_NAME: "workspace", AKAN_PUBLIC_SERVE_DOMAIN: "example.com", AKAN_PUBLIC_ENV: "local" });
+const makeTempRoot = tempDirs("akan-slice-");
 
 const gitignore = [
   "node_modules",
@@ -36,8 +19,7 @@ const gitignore = [
 
 // `AppExecutor.from` and `AppInfo.fromExecutor` both memoise by name, so each fixture needs a fresh one.
 const makeWorkspace = async (appName: string, libName: string) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-slice-"));
-  tempRoots.push(root);
+  const root = await makeTempRoot();
   const rootPackageJson: PackageJson = {
     name: "workspace",
     version: "0.0.1",

package/slicePlanner.ts

@@ -18,12 +18,6 @@ export interface SlicePlan {
   warnings: string[];
 }
 
-/**
- * The exact file set a single app needs to live in a workspace of its own: the app, its transitive lib
- * closure, the workspace shell around them, and a root manifest for the result.
- *
- * Consumed by `akan plan-slice`, and by anything that moves an app or a lib between workspaces.
- */
 export class SlicePlanner {
   /** Root entries owned by an app, a lib or an in-tree package rather than by the workspace shell. */
   static readonly memberDirs = ["apps", "libs", "pkgs"];
@@ -39,13 +33,8 @@ export class SlicePlanner {
   ];
   static readonly akanPackages = ["akanjs", "@akanjs/devkit", "@akanjs/cli"];
 
-  /**
-   * What the framework imports but does not install, so a workspace root has to declare it: `react`,
-   * `scheduler` and the RSC runtime, but also `ioredis`, `postgres` and `bullmq` the moment an app uses
-   * a database or a queue. No source file in the workspace names any of them, so no scan can find them
-   * — they are the akan packages' own `peerDependencies`, read wherever those are installed. Anything
-   * they declare as a plain dependency is installed with them and needs no root entry.
-   */
+  // The akan packages' peerDependencies (react, the RSC runtime, ioredis, postgres, bullmq): the framework imports
+  // them but no workspace source names them, so no scan can find them.
   static async #frameworkPeers(workspace: WorkspaceExecutor) {
     const peers = new Set<string>();
     let found = false;
@@ -67,14 +56,8 @@ export class SlicePlanner {
     return dependency.startsWith("@") ? `@types/${dependency.slice(1).replace("/", "__")}` : `@types/${dependency}`;
   }
 
-  /**
-   * The root manifest a workspace holding only these dependencies would carry, with the workspace's own
-   * version specs kept — that is what makes one branch resolve to one dependency tree everywhere.
-   *
-   * A `@types/x` package is kept alongside `x`: nothing imports it by name, so no scan can see it, and
-   * dropping it breaks the typecheck of every file that imports `x`. `workspaces` is dropped because it
-   * names in-tree packages, which a slice never carries — it consumes akanjs from the registry.
-   */
+  // `@types/x` is kept alongside `x` since nothing imports it by name; `workspaces` is dropped because a slice
+  // consumes akanjs from the registry.
   static async pruneDependencies(
     workspace: WorkspaceExecutor,
     rootPackageJson: PackageJson,
@@ -82,9 +65,8 @@ export class SlicePlanner {
   ) {
     const peers = await SlicePlanner.#frameworkPeers(workspace);
     const { workspaces: _workspaces, ...rest } = rootPackageJson;
-    //* Without akanjs's peer list every peer looks unused, and pruning it produces an install that
-    //* succeeds and a server that fails at its first redis or postgres call. Carry the dependencies
-    //* whole instead and say why.
+    //* Without the peer list every peer looks unused, and pruning it breaks the server at its first redis or
+    //* postgres call.
     if (!peers)
       return {
         packageJson: rest as PackageJson,
@@ -121,10 +103,6 @@ export class SlicePlanner {
     this.#app = app;
   }
 
-  async #trackedFiles(paths: string[]) {
-    return await this.#app.workspace.listGitFiles(paths);
-  }
-
   async #untrackedFiles(paths: string[]) {
     const [tracked, all] = await Promise.all([
       this.#app.workspace.listGitFiles(paths),
@@ -170,14 +148,16 @@ export class SlicePlanner {
     const slicePaths = [`apps/${this.#app.name}`, ...libs.map((lib) => `libs/${lib}`)];
 
     const [appFiles, allTracked, untracked, rootPackageJson] = await Promise.all([
-      this.#trackedFiles([`apps/${this.#app.name}`]),
-      this.#trackedFiles(["."]),
+      this.#app.workspace.listGitFiles([`apps/${this.#app.name}`]),
+      this.#app.workspace.listGitFiles(["."]),
       this.#untrackedFiles(slicePaths),
       this.#app.workspace.getPackageJson(),
     ]);
 
     const libFiles = Object.fromEntries(
-      await Promise.all(libs.map(async (lib) => [lib, await this.#trackedFiles([`libs/${lib}`])] as const)),
+      await Promise.all(
+        libs.map(async (lib) => [lib, await this.#app.workspace.listGitFiles([`libs/${lib}`])] as const),
+      ),
     );
     const rootFiles = allTracked.filter((file) => !this.#isMemberFile(file));
 
@@ -211,7 +191,6 @@ export class SlicePlanner {
   }
 }
 
-/** Top-level entry each path sits under, so a long tree (`infra/**`) reads as one line. */
 const rootEntriesOf = (rootFiles: string[]) => [...new Set(rootFiles.map((file) => file.split("/")[0] ?? file))].sort();
 
 export function formatSlicePlan(plan: SlicePlan) {

package/spinner.test.ts

@@ -6,10 +6,7 @@ interface TtyStub {
   rawModeCalls: boolean[];
 }
 
-/**
- * ora only reaches for stdin when both streams look interactive, so the stub has to fake a tty on
- * stderr (which decides `isEnabled`) as well as on stdin.
- */
+// ora only reaches for stdin when both streams look interactive, so stderr (which decides `isEnabled`) is faked too.
 const stubTty = (): TtyStub => {
   const rawModeCalls: boolean[] = [];
   const stdin = process.stdin as NodeJS.ReadStream & { setRawMode?: (mode: boolean) => unknown };
@@ -41,8 +38,7 @@ const stubTty = (): TtyStub => {
 };
 
 describe("Spinner", () => {
-  // A raw terminal at spawn time is what a Bun child snapshots and writes back when it exits, which is
-  // how `akan start` used to leave a terminal that no longer turns Ctrl+C into SIGINT.
+  // A Bun child snapshots a raw terminal at spawn and writes it back on exit, leaving Ctrl+C no longer a SIGINT.
   test("never puts the terminal into raw mode while it spins", () => {
     const tty = stubTty();
     try {
@@ -59,8 +55,7 @@ describe("Spinner", () => {
     expect(Spinner.oraOptions.discardStdin).toBe(false);
   });
 
-  // An unsized pty reports `isTTY: true` with `columns: 0`, which turns ora's clear loop into an
-  // infinite one — the process then writes cursor moves until it is SIGKILLed.
+  // An unsized pty reports `isTTY: true` with `columns: 0`, which turns ora's clear loop into an infinite one.
   test("refuses to animate against a tty that reports no width", () => {
     expect(Spinner.canAnimate({ isTTY: true, columns: 0 } as NodeJS.WriteStream)).toBe(false);
     expect(Spinner.canAnimate({ isTTY: true, columns: 120 } as NodeJS.WriteStream)).toBe(true);

package/spinner.ts

@@ -2,23 +2,11 @@ import ora, { type Ora } from "ora";
 
 export class Spinner {
   static padding = 12;
-  /**
-   * XXX: `discardStdin` must stay off. It makes ora put the terminal into raw mode for as long as the
-   * spinner runs, and a Bun child spawned in that window snapshots the raw termios and writes it back
-   * when it exits — long after the spinner restored the terminal. `akan start` spawns the builder and
-   * the backend under the "Preparing backend..." spinner, so the first builder recycle (a config or
-   * runtime-metadata change) SIGTERMs that child and silently turns the developer's terminal raw:
-   * `isig` goes off, Ctrl+C stops producing SIGINT at all, and the dev server looks unkillable.
-   */
+  // XXX: `discardStdin` must stay off: ora raw-modes the terminal while spinning, a Bun child spawned then writes that
+  // raw termios back when it exits, and Ctrl+C stops producing SIGINT.
   static oraOptions = { discardStdin: false } as const;
-  /**
-   * ora sizes its clear loop as `ceil(lineWidth / stream.columns)`, so a tty that reports **0** columns
-   * makes it `Infinity` and `clear()` never returns. An unsized pty does exactly that (`isTTY: true`,
-   * `columns: 0`) — CI runners, `expect`/`script` harnesses, some detached panes. Measured: 750MB of
-   * cursor moves and 8.7GB RSS inside a minute, in a loop that no longer reaches the point where SIGINT
-   * or SIGTERM could be handled, so only SIGKILL ends it. A terminal with no width has nothing to
-   * animate anyway; fall back to plain lines.
-   */
+  // ora's clear loop is `ceil(lineWidth / columns)`, so an unsized pty (`isTTY` with 0 columns: CI, `script`) never
+  // returns from `clear()`; such a terminal gets plain lines.
   static canAnimate(stream: NodeJS.WriteStream = process.stderr): boolean {
     return !stream.isTTY || stream.columns > 0;
   }

package/sshTunnel.ts

@@ -20,7 +20,6 @@ interface TunnelSocketData {
   closed: boolean;
 }
 
-type BunServer = { stop(): void };
 type BunSocket = Bun.Socket<TunnelSocketData>;
 
 const closeQuietly = (close: () => void) => {
@@ -126,7 +125,7 @@ export const createSshTunnel = async (options: SshTunnelOptions): Promise<SshTun
       closing = true;
       for (const socket of sockets) closeSocket(socket, error);
       closeQuietly(() => client.end());
-      closeBunServer(server);
+      server.stop();
     };
 
     client.once("error", (error) => closeTunnel(error));
@@ -146,7 +145,3 @@ const closeBunSocket = (socket: BunSocket, error?: Error) => {
   else socket.data.stream?.end();
   closeQuietly(() => socket.end());
 };
-
-const closeBunServer = (server: BunServer) => {
-  server.stop();
-};

package/ssrScanner.test.ts

@@ -3,12 +3,7 @@ import ts from "typescript";
 import type { SourceFileInfo } from "./qualityScanner";
 import { formatSsrBalance, SSR_SERVER_SHARE_TARGET, SsrScanner } from "./ssrScanner";
 
-/**
- * `SsrScanner` is a documented gate — `akan quality ssr` prints the server share and AGENTS.md names 50% as
- * the floor — so both halves matter: a rule that stops firing lets the share rot, and a rule that
- * over-reports is what makes developers stop reading the output. Every rule here gets a positive and the
- * negative that must stay quiet.
- */
+//? Each rule gets a positive and a negative: one that stops firing lets the share rot, one that over-reports is ignored
 const fileOf = (file: string, content: string): SourceFileInfo => ({
   file,
   absolutePath: `/repo/${file}`,

package/ssrScanner.ts

@@ -22,34 +22,32 @@ interface ComponentInfo {
   vendorTags: boolean;
 }
 
-// A component with no client-only touch at all never needed the client bundle, so even a small subtree is
-// worth moving. A mostly-static component keeps its interaction and hands the static part to the server, so
-// it only pays off once the static subtree is large enough to matter.
+// A component with no client-only touch is worth moving even when small; a mostly-static one only once its static
+// subtree is large enough to matter.
 const STATIC_COMPONENT_MIN_MASS = 4;
 const MIXED_COMPONENT_MIN_MASS = 10;
 const MIXED_COMPONENT_MAX_TOUCHES = 2;
 const MODULE_SERVER_VIEW_MIN_CLIENT_MASS = 12;
 
+export const fileWarning = (
+  rule: string,
+  scope: QualityWarning["scope"],
+  file: string,
+  message: string,
+  line?: number,
+): QualityWarning =>
+  line === undefined
+    ? { rule, scope, severity: "warning", file, message }
+    : { rule, scope, severity: "warning", file, line, message };
+
 export class SsrScanner {
-  // `usePage` and `getSelf` read request-scoped server context and are legal in server components, so they
-  // must not count as evidence that a file needs "use client".
+  // `usePage` and `getSelf` read request-scoped server context, which server components may do.
   static #serverSafeCalls = new Set(["usePage", "getSelf", "useServer"]);
-  static #clientGlobals = new Set([
-    "window",
-    "document",
-    "navigator",
-    "localStorage",
-    "sessionStorage",
-    "location",
-    "history",
-    "screen",
-    "matchMedia",
-    "IntersectionObserver",
-    "ResizeObserver",
-    "MutationObserver",
-    "requestAnimationFrame",
-    "WebSocket",
-  ]);
+  static #clientGlobals = new Set(
+    "window document navigator localStorage sessionStorage location history screen matchMedia IntersectionObserver"
+      .split(" ")
+      .concat("ResizeObserver MutationObserver requestAnimationFrame WebSocket".split(" ")),
+  );
   // Runtime singletons that only exist in the client bundle; importing either is what forces the directive.
   static #clientRuntimeImports = new Set(["st", "fetch"]);
 
@@ -78,27 +76,29 @@ export class SsrScanner {
       this.#getTouches(sourceFile.sourceFile, sourceFile.sourceFile).length === 0 &&
       !this.#isConventionClientFile(sourceFile.file)
     ) {
-      warnings.push({
-        rule: "akan.ssr.unnecessary-use-client",
-        scope: "ssr",
-        severity: "warning",
-        file: sourceFile.file,
-        line: 1,
-        message: `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`,
-      });
+      warnings.push(
+        fileWarning(
+          "akan.ssr.unnecessary-use-client",
+          "ssr",
+          sourceFile.file,
+          `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`,
+          1,
+        ),
+      );
     }
 
     for (const component of components) {
       if (component.vendorTags) continue;
       if (component.touches.length === 0 && component.mass >= STATIC_COMPONENT_MIN_MASS) {
-        warnings.push({
-          rule: "akan.ssr.client-static-component",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: component.line,
-          message: `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`,
-        });
+        warnings.push(
+          fileWarning(
+            "akan.ssr.client-static-component",
+            "ssr",
+            sourceFile.file,
+            `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`,
+            component.line,
+          ),
+        );
         continue;
       }
       if (
@@ -106,14 +106,15 @@ export class SsrScanner {
         component.touches.length <= MIXED_COMPONENT_MAX_TOUCHES &&
         component.mass >= MIXED_COMPONENT_MIN_MASS
       ) {
-        warnings.push({
-          rule: "akan.ssr.client-static-markup",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: component.line,
-          message: `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`,
-        });
+        warnings.push(
+          fileWarning(
+            "akan.ssr.client-static-markup",
+            "ssr",
+            sourceFile.file,
+            `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`,
+            component.line,
+          ),
+        );
       }
     }
 
@@ -122,8 +123,7 @@ export class SsrScanner {
     return warnings;
   }
 
-  // A database module whose rendering happens entirely in Template/Zone/Util has no server-rendered surface at
-  // all, so every consumer pays for hydration even when it only needs to display the model.
+  // A module rendered only from Template/Zone/Util makes every consumer pay for hydration just to display it.
   #scanModules(sourceFiles: SourceFileInfo[]): QualityWarning[] {
     const modules = new Map<string, { clientMass: number; serverFiles: number; line: string }>();
     for (const sourceFile of sourceFiles) {
@@ -136,36 +136,32 @@ export class SsrScanner {
     }
     return [...modules]
       .filter(([, entry]) => entry.serverFiles === 0 && entry.clientMass >= MODULE_SERVER_VIEW_MIN_CLIENT_MASS)
-      .map(([moduleDir, entry]) => ({
-        rule: "akan.ssr.module-missing-server-view",
-        scope: "ssr" as const,
-        severity: "warning" as const,
-        file: entry.line,
-        message: `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`,
-      }));
+      .map(([moduleDir, entry]) =>
+        fileWarning(
+          "akan.ssr.module-missing-server-view",
+          "ssr",
+          entry.line,
+          `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`,
+        ),
+      );
   }
 
-  // A load fired from a mount-only effect is data the route already could have fetched: the client renders an
-  // empty shell, hydrates, then fetches. A reactive effect (non-empty deps) responds to client state instead
-  // and has no server-side equivalent, so only the empty-dependency form is a finding.
+  // Only an empty-dependency effect is a finding: a reactive effect answers client state and has no server equivalent.
   #getMountLoadWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
     const warnings: QualityWarning[] = [];
-    const visit = (node: ts.Node) => {
-      if (this.#isMountEffect(sourceFile.sourceFile, node)) {
-        for (const load of this.#getLoadCalls(sourceFile.sourceFile, node)) {
-          warnings.push({
-            rule: "akan.ssr.client-mount-load",
-            scope: "ssr",
-            severity: "warning",
-            file: sourceFile.file,
-            line: this.#getLine(sourceFile.sourceFile, load.node),
-            message: `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`,
-          });
-        }
-      }
-      ts.forEachChild(node, visit);
-    };
-    ts.forEachChild(sourceFile.sourceFile, visit);
+    SsrScanner.#walk(sourceFile.sourceFile, (node) => {
+      if (!this.#isMountEffect(sourceFile.sourceFile, node)) return;
+      for (const load of this.#getLoadCalls(sourceFile.sourceFile, node))
+        warnings.push(
+          fileWarning(
+            "akan.ssr.client-mount-load",
+            "ssr",
+            sourceFile.file,
+            `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`,
+            this.#getLine(sourceFile.sourceFile, load.node),
+          ),
+        );
+    });
     return warnings;
   }
 
@@ -179,35 +175,30 @@ export class SsrScanner {
 
   #getLoadCalls(sourceFile: ts.SourceFile, node: ts.Node) {
     const calls: Array<{ callee: string; node: ts.Node }> = [];
-    const visit = (child: ts.Node) => {
-      if (ts.isCallExpression(child)) {
-        const callee = child.expression.getText(sourceFile);
-        if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
-          calls.push({ callee, node: child });
-      }
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    SsrScanner.#walk(node, (child) => {
+      if (!ts.isCallExpression(child)) return;
+      const callee = child.expression.getText(sourceFile);
+      if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
+        calls.push({ callee, node: child });
+    });
     return calls;
   }
 
   #getTemplateStateWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
     if (!sourceFile.file.endsWith(".Template.tsx")) return [];
     const warnings: QualityWarning[] = [];
-    const visit = (node: ts.Node) => {
-      if (ts.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState") {
-        warnings.push({
-          rule: "akan.ssr.template-client-state",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: this.#getLine(sourceFile.sourceFile, node),
-          message: "Template holds form state in useState. Templates are store-driven and carry no local state.",
-        });
-      }
-      ts.forEachChild(node, visit);
-    };
-    ts.forEachChild(sourceFile.sourceFile, visit);
+    SsrScanner.#walk(sourceFile.sourceFile, (node) => {
+      if (ts.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState")
+        warnings.push(
+          fileWarning(
+            "akan.ssr.template-client-state",
+            "ssr",
+            sourceFile.file,
+            "Template holds form state in useState. Templates are store-driven and carry no local state.",
+            this.#getLine(sourceFile.sourceFile, node),
+          ),
+        );
+    });
     return warnings;
   }
 
@@ -261,7 +252,7 @@ export class SsrScanner {
 
   #getTouches(sourceFile: ts.SourceFile, node: ts.Node): string[] {
     const touches: string[] = [];
-    const visit = (child: ts.Node) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts.isCallExpression(child)) {
         const callee = child.expression.getText(sourceFile);
         const bareName = callee.split(".").pop() ?? callee;
@@ -275,41 +266,42 @@ export class SsrScanner {
         if (root === "st") touches.push("st");
         else if (SsrScanner.#clientGlobals.has(root)) touches.push(root);
       }
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    });
     return touches;
   }
 
   #getTagNames(sourceFile: ts.SourceFile, node: ts.Node): Set<string> {
     const tags = new Set<string>();
-    const visit = (child: ts.Node) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child))
         tags.add(child.tagName.getText(sourceFile).split(".")[0]);
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    });
     return tags;
   }
 
   #getMass(node: ts.Node) {
     let mass = 0;
-    const visit = (child: ts.Node) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child)) mass += 1;
-      ts.forEachChild(child, visit);
-    };
-    ts.forEachChild(node, visit);
+    });
     return mass;
   }
 
+  static #walk(node: ts.Node, visit: (descendant: ts.Node) => void) {
+    const walk = (child: ts.Node) => {
+      visit(child);
+      ts.forEachChild(child, walk);
+    };
+    ts.forEachChild(node, walk);
+  }
+
   #hasUseClient(sourceFile: ts.SourceFile) {
     const first = sourceFile.statements[0];
     if (!first || !ts.isExpressionStatement(first) || !ts.isStringLiteral(first.expression)) return false;
     return first.expression.text === "use client";
   }
 
-  // A bare specifier is a third-party package: it may be client-only, which is a legitimate reason for the
-  // directive that no amount of AST reading can rule out.
+  // A third-party package may be client-only, a legitimate reason for the directive no AST reading can rule out.
   #hasVendorImport(sourceFile: ts.SourceFile) {
     return sourceFile.statements.some(
       (statement) => ts.isImportDeclaration(statement) && isVendorSpecifier(getSpecifier(statement)),
@@ -340,9 +332,7 @@ export class SsrScanner {
     return false;
   }
 
-  // Zone/Template/Util carry the directive mechanically by file role, and `index_.tsx` is the declared
-  // "use client" + lazy() boundary. In neither case is the directive a stray — for module UI it means markup
-  // belongs in a Unit or View instead, which the component rules already cover.
+  // Zone/Template/Util carry the directive by file role, and `index_.tsx` is the declared lazy() boundary.
   #isConventionClientFile(file: string) {
     if (file.endsWith("/index_.tsx")) return true;
     return /\.(Zone|Template|Util)\.tsx$/.test(file) && this.#getModuleDir(file) !== null;

package/subspace.test.ts

@@ -1,34 +1,17 @@
-import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
-import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, setDefaultTimeout, test } from "bun:test";
+import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Executor, WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { formatSubspaceDiff, formatSubspacePushResults, formatSubspaceStatuses, Subspace } from "./subspace";
 import { SubspaceConfig } from "./subspaceConfig";
+import { isolateEnv, tempDirs, writeText as write } from "./testHelpers";
 
 //? Each case drives several real git clones and pushes; on a 4-core Windows VM that alone lands at 2-5s.
 setDefaultTimeout(20_000);
 
-const tempRoots: string[] = [];
-const originalEnv = { ...process.env };
-
-beforeEach(() => {
-  process.env = { ...originalEnv };
-  process.env.AKAN_PUBLIC_REPO_NAME = "workspace";
-  process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
-  process.env.AKAN_PUBLIC_ENV = "local";
-});
-
-afterEach(async () => {
-  process.env = { ...originalEnv };
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
+isolateEnv({ AKAN_PUBLIC_REPO_NAME: "workspace", AKAN_PUBLIC_SERVE_DOMAIN: "example.com", AKAN_PUBLIC_ENV: "local" });
+const makeTempRoot = tempDirs("akan-subspace-");
 
 const git = async (cwd: string, args: string[]) =>
   await new Executor("fixture", cwd).spawn("git", ["-c", "user.email=t@t", "-c", "user.name=t", ...args]);
@@ -67,10 +50,8 @@ const makeSys = async (root: string, member: "apps" | "libs", name: string, extr
     await write(path.join(root, member, name, relative), content);
 };
 
-/** A workspace with two apps, one shared library, and a subspace that serves only the first app. */
 const makeMirror = async (servedApp: string, privateApp: string, libName: string) => {
-  const workRoot = await mkdtemp(path.join(os.tmpdir(), "akan-subspace-"));
-  tempRoots.push(workRoot);
+  const workRoot = await makeTempRoot();
   const wsRoot = path.join(workRoot, "workspace");
   const bareRoot = path.join(workRoot, "subspace.git");
   await mkdir(wsRoot, { recursive: true });