@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.21

package/transforms/externalizeFrameworkPlugin.ts

@@ -2,64 +2,19 @@ import path from "node:path";
 import type { BunPlugin } from "bun";
 import type { App } from "../commandDecorators";
 
-/**
- * Keep framework/runtime singletons external while bundling authored
- * workspace sources and ordinary npm dependencies into the pages bundle.
- *
- * Why a plugin instead of `Bun.build({ external })` or
- * `Bun.build({ packages: "external" })`:
- *   - `packages: "external"` externalizes every bare specifier, including
- *     `@apps/*` / `@libs/*` — workspace packages that must stay bundled
- *     so the `"use client"` plugin can rewrite their exports — and ordinary
- *     npm dependencies like `dayjs` / `tailwind-merge`, which the production runtime
- *     package.json does not install for the SSR pages artifact.
- *   - Top-level `external: [...]` applies to macro-time module resolution
- *     too; any `with { type: "macro" }` import chain that transitively
- *     resolves `react` during build then fails with `ENOENT "react"`.
- *
- * An `onResolve` plugin only participates in the output-graph walk, so
- * macros evaluate against the real modules in node_modules while the
- * emitted bundle keeps bare specifiers only for runtime singletons that
- * are installed in the generated production package.json.
- *
- * Externalization rules (applied in order):
- *   1. Relative specifiers (`./`, `../`) are NEVER externalized — they
- *      always resolve to the current package's source tree and must be
- *      inlined so transitive `"use client"` stubs work.
- *   2. Specifiers listed in `include` (workspace aliases like
- *      `@apps/*`, `@libs/*`) are NEVER externalized.
- *   3. React / RSC runtime packages and build-time tooling packages are
- *      externalized so the runtime supplies a single shared instance.
- *   4. Other bare npm packages are bundled so the Docker runtime does not
- *      need to install every transitive page dependency separately.
- */
 export interface ExternalizeFrameworkOptions {
   app: App;
-  /**
-   * Prefixes that should be BUNDLED (kept internal). Defaults to
-   * `@apps/` and `@libs/` which are the workspace aliases used by the
-   * framework's app template.
-   */
+  /** Prefixes to bundle rather than externalize; defaults to `akanjs/`, `@apps/`, `@libs/`. */
   include?: string[];
-  /**
-   * Extra bare specifiers to force-externalize beyond the allowlist
-   * defaults. Not commonly needed since the default rule already
-   * externalizes every non-workspace specifier.
-   */
+  /** Bare specifiers to force-externalize, overriding `include`. */
   extra?: string[];
 }
 
-// Workspace package prefixes that must be BUNDLED so their sources go
-// through the barrel-imports + `"use client"` transforms. Without this
-// the RSC worker would resolve them at runtime — skipping the
-// transforms entirely, which re-introduces the react-dom/client
-// side-effects we wanted to strip from the server graph.
+// Bundled so they pass the barrel and `"use client"` transforms; resolved at runtime they would drag
+// react-dom/client side effects into the server graph.
 const DEFAULT_INCLUDE = ["akanjs/", "@apps/", "@libs/"];
 
-// Packages that must stay external even when a broad allowlist would
-// otherwise bundle them. These are runtime hosts or shared singleton
-// framework packages; ordinary npm dependencies intentionally fall through
-// to Bun's resolver and get bundled.
+// Runtime hosts and singleton framework packages stay external; ordinary npm dependencies are bundled.
 const DEFAULT_EXCLUDE_EXACT = new Set<string>(["akanjs/webkit", "@akanjs/cli", "@akanjs/devkit"]);
 const DEFAULT_EXCLUDE_PREFIX = ["@akanjs/cli/", "@akanjs/devkit/"];
 const OPTIONAL_BACKEND_EXTERNAL_EXACT = new Set<string>([
@@ -81,19 +36,17 @@ const RUNTIME_EXTERNAL_EXACT = new Set<string>([
 ]);
 const RUNTIME_EXTERNAL_PREFIX = ["react-dom/", "react-server-dom-webpack/"];
 
-// File extensions Bun can load when a bare subpath points at an
-// extensionless path. Ordered to prefer TS over JS, since workspace
-// sources are authored in TypeScript.
+// TS before JS: workspace sources are authored in TypeScript.
 const CANDIDATE_EXTS = [".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs"];
 
+// Rejected `Bun.build` options: `external` also applies at macro time (ENOENT "react"), and `packages: "external"`
+// externalizes workspace and npm packages the runtime does not install. onResolve shapes only the output graph.
 export async function createExternalizeFrameworkPlugin(options: ExternalizeFrameworkOptions): Promise<BunPlugin> {
   const tsconfig = await options.app.getTsConfig();
   const includePrefixes = options.include ?? DEFAULT_INCLUDE;
   const extraExact = new Set(options.extra ?? []);
   const workspaceRoot = options.app.workspace.workspaceRoot;
   const tsconfigPaths = tsconfig.compilerOptions.paths ?? {};
-  // Pre-compute the tsconfig root-only entries (`akanjs/client` → …)
-  // so we can resolve their subpaths by concatenating the remainder.
   const rootEntries = Object.entries(tsconfigPaths)
     .filter(([k]) => !k.endsWith("/*"))
     .map(([k, v]) => ({ pkg: k, entryFile: v[0] ?? null }))
@@ -105,7 +58,6 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
 
   async function resolveWorkspaceSubpath(spec: string): Promise<string | null> {
     if (!workspaceRoot) return null;
-    // Wildcard `@apps/*` / `@libs/*` → direct filesystem path.
     for (const { prefix, replacements } of wildcardEntries) {
       if (!spec.startsWith(prefix)) continue;
       const suffix = spec.slice(prefix.length);
@@ -117,12 +69,8 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
         if (hit) return hit;
       }
     }
-    // Root-only tsconfig entries — resolve the subpath against the
-    // package directory. E.g. `akanjs/client` → `pkgs/akanjs/client/index.ts`
-    // so `akanjs/client/cookie` → `pkgs/akanjs/client/cookie`.
     for (const { pkg, entryFile } of rootEntries) {
-      if (spec !== pkg && !spec.startsWith(`${pkg}/`)) continue;
-      if (spec === pkg) continue; // the package root itself — let Bun's tsconfig resolver handle it
+      if (!spec.startsWith(`${pkg}/`)) continue;
       const suffix = spec.slice(pkg.length + 1);
       const pkgDir = path.dirname(path.resolve(workspaceRoot, entryFile));
       const candidate = path.join(pkgDir, suffix);
@@ -137,13 +85,8 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
     setup(build) {
       build.onResolve({ filter: /.*/ }, async (args) => {
         const spec = args.path;
-        // Relative imports always stay inlined — they anchor to the
-        // current package's source tree and cannot leak cross-package.
-        // `.` and `..` (without trailing slash) are valid relative
-        // specifiers too (equivalent to `./index` / `../index`).
         if (spec === "." || spec === ".." || spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/"))
           return undefined;
-        // Force-external first (overrides the include allowlist).
         if (extraExact.has(spec) || DEFAULT_EXCLUDE_EXACT.has(spec)) return { path: spec, external: true };
         for (const prefix of DEFAULT_EXCLUDE_PREFIX) {
           if (spec.startsWith(prefix)) return { path: spec, external: true };
@@ -153,38 +96,21 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
         for (const prefix of RUNTIME_EXTERNAL_PREFIX) {
           if (spec.startsWith(prefix)) return { path: spec, external: true };
         }
-        // Workspace allowlist — resolve the subpath to an absolute
-        // on-disk file so Bun.build can read it. Without this, bare
-        // specifiers like `akanjs/client/cookie` (produced by the
-        // barrel rewriter) fail Bun's default resolution (only root
-        // tsconfig-paths entry exists for `akanjs/client`) and get
-        // silently left as externals.
-        for (const prefix of includePrefixes) {
-          if (!spec.startsWith(prefix)) continue;
-          const resolved = await resolveWorkspaceSubpath(spec);
-          if (resolved) return { path: resolved };
-          // Fall through to let Bun attempt its own resolution for the
-          // package root (`akanjs/client`) — tsconfig `paths` handles
-          // that case directly.
-          return undefined;
-        }
-        // Everything else (ordinary npm dependencies like dayjs / tailwind-merge /
-        // immer) is bundled into the pages artifact.
-        return undefined;
+        // Bun resolves only root tsconfig `paths`, so a rewritten `akanjs/client/cookie` would silently stay external.
+        if (!includePrefixes.some((prefix) => spec.startsWith(prefix))) return undefined;
+        const resolved = await resolveWorkspaceSubpath(spec);
+        return resolved ? { path: resolved } : undefined;
       });
     },
   };
 }
 
 async function firstExisting(basePath: string): Promise<string | null> {
-  // Direct file with its own extension.
   if (await Bun.file(basePath).exists()) return basePath;
-  // Try each candidate extension.
   for (const ext of CANDIDATE_EXTS) {
     const candidate = `${basePath}${ext}`;
     if (await Bun.file(candidate).exists()) return candidate;
   }
-  // Directory with `index.<ext>` inside.
   for (const ext of CANDIDATE_EXTS) {
     const candidate = path.join(basePath, `index${ext}`);
     if (await Bun.file(candidate).exists()) return candidate;

package/transforms/moduleSyntax.ts

@@ -0,0 +1,32 @@
+export interface NamedItem {
+  imported: string;
+  local: string;
+  isType: boolean;
+}
+
+export const loaderFor = (absPath: string): "ts" | "tsx" | "js" | "jsx" => {
+  if (absPath.endsWith(".tsx")) return "tsx";
+  if (absPath.endsWith(".jsx")) return "jsx";
+  if (absPath.endsWith(".ts")) return "ts";
+  return "js";
+};
+
+export const parseNamedList = (listBody: string): NamedItem[] => {
+  const out: NamedItem[] = [];
+  for (const raw of listBody.split(",")) {
+    let rest = raw.trim();
+    if (!rest) continue;
+    let isType = false;
+    if (rest.startsWith("type ")) {
+      isType = true;
+      rest = rest.slice(5).trim();
+    }
+    const asMatch = /^(\w+)\s+as\s+(\w+)$/.exec(rest);
+    if (asMatch) {
+      out.push({ imported: asMatch[1] ?? "", local: asMatch[2] ?? "", isType });
+      continue;
+    }
+    if (/^\w+$/.test(rest)) out.push({ imported: rest, local: rest, isType });
+  }
+  return out;
+};

package/transforms/rscUseClientTransform.ts

@@ -1,15 +1,11 @@
 import path from "node:path";
+import ts from "typescript";
+import { loaderFor } from "./moduleSyntax";
 
-// Pure "use client" transform: when `source` starts with the `"use client"`
-// directive, replace its exports with `registerClientReference` stubs so the
-// RSC renderer can serialize them as client component references instead of
-// trying to run them on the server.
-
-// Matches `"use client"` or `'use client'` at the start of a file,
-// optionally after leading whitespace and JS comments.
 const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
 const IMPLICIT_ROOT_LAYOUT_RE =
   /[/\\]\.akan[/\\]generated[/\\](?:implicit-root-layout|root-layouts[/\\].*__root_layout)\.(tsx|ts|jsx|js)$/;
+const STAR_REEXPORT_HINT_RE = /\bexport\s*\*\s*from\b/;
 
 export interface UseClientTransformArgs {
   path: string;
@@ -20,15 +16,41 @@ export function toClientReferencePath(absPath: string, workspaceRoot: string): s
   return path.relative(path.resolve(workspaceRoot), path.resolve(absPath)).split(path.sep).join("/");
 }
 
-/**
- * Returns the stubbed module source if `source` is a client module, else null.
- * The returned source is TypeScript-compatible (loader "ts" is safe).
- */
+const starReexportSpecifiers = (source: string, filePath: string) =>
+  ts
+    .createSourceFile(filePath, source, ts.ScriptTarget.Latest)
+    .statements.filter(
+      (statement): statement is ts.ExportDeclaration & { moduleSpecifier: ts.StringLiteral } =>
+        ts.isExportDeclaration(statement) &&
+        !statement.exportClause &&
+        !statement.isTypeOnly &&
+        !!statement.moduleSpecifier &&
+        ts.isStringLiteral(statement.moduleSpecifier),
+    )
+    .map((statement) => statement.moduleSpecifier.text);
+
+// `Bun.Transpiler.scan` reports no name through `export *`, so the server could register none of a star's names as
+// client references; they would be undefined in a server component. Refused as Next.js refuses it.
+export const scanUseClientExports = (source: string, filePath: string, workspaceRoot?: string): string[] => {
+  const stars =
+    USE_CLIENT_RE.test(source) && STAR_REEXPORT_HINT_RE.test(source) ? starReexportSpecifiers(source, filePath) : [];
+  if (stars.length) {
+    const file = workspaceRoot ? toClientReferencePath(filePath, workspaceRoot) : filePath;
+    const listed = stars.slice(0, 3).map((specifier) => `\`export * from ${JSON.stringify(specifier)}\``);
+    const written = stars.length > 3 ? `${listed.join(", ")} (and ${stars.length - 3} more)` : listed.join(", ");
+    throw new Error(
+      `${file} is a "use client" module, so it cannot ${written}: the server sees only the names a client module ` +
+        `declares, and a star re-export declares none. Re-export them by name — \`export { … } from ${JSON.stringify(stars[0])}\`.`,
+    );
+  }
+  return new Bun.Transpiler({ loader: loaderFor(filePath) }).scan(source).exports;
+};
+
+/** `null` unless `source` is a `"use client"` module; the stub source is valid under loader `"ts"`. */
 export function transformUseClient(source: string, args: UseClientTransformArgs): string | null {
   if (!USE_CLIENT_RE.test(source)) return null;
   if (IMPLICIT_ROOT_LAYOUT_RE.test(args.path)) return null;
-  const transpiler = new Bun.Transpiler({ loader: loaderFor(args.path) });
-  const { exports } = transpiler.scan(source);
+  const exports = scanUseClientExports(source, args.path, args.workspaceRoot);
   if (exports.length === 0) return null;
 
   const referencePath = args.workspaceRoot ? toClientReferencePath(args.path, args.workspaceRoot) : args.path;
@@ -50,10 +72,3 @@ export function transformUseClient(source: string, args: UseClientTransformArgs)
 
   return lines.join("\n");
 }
-
-function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-  if (absPath.endsWith(".tsx")) return "tsx";
-  if (absPath.endsWith(".jsx")) return "jsx";
-  if (absPath.endsWith(".ts")) return "ts";
-  return "js";
-}

package/transforms/transforms.test.ts

@@ -1,27 +1,16 @@
-import { afterEach, 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 path from "node:path";
-import { BarrelAnalyzer } from "./barrelAnalyzer";
+import { ApplicationBuildReporter } from "../applicationBuildReporter";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { BarrelAnalyzer, type BarrelExportTarget } from "./barrelAnalyzer";
 import { rewriteBarrelImports } from "./barrelImportsPlugin";
-import { toClientReferencePath, transformUseClient } from "./rscUseClientTransform";
+import { scanUseClientExports, toClientReferencePath, transformUseClient } from "./rscUseClientTransform";
+import { createUseClientBundlePlugin } from "./useClientBundlePlugin";
 
-const tempRoots: string[] = [];
+const makeTempRoot = tempDirs("akan-devkit-transform-");
 
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-transform-"));
-  tempRoots.push(root);
-  return root;
-};
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const fakeAnalyzer = (entries: [string, BarrelExportTarget][]) =>
+  ({ analyze: async () => new Map(entries) }) as unknown as BarrelAnalyzer;
 
 describe("transformUseClient", () => {
   test("returns null for non-client modules and generated root layouts", () => {
@@ -62,6 +51,65 @@ describe("transformUseClient", () => {
   });
 });
 
+describe('export * in a "use client" module', () => {
+  test("is refused with the file, the specifier and the fix, since the server would see none of its names", () => {
+    const source = [
+      '"use client";',
+      'export * from "../../ui/UserLeave";',
+      "export const General = () => null;",
+      "",
+    ].join("\n");
+    expect(() =>
+      transformUseClient(source, { path: "/repo/libs/shared/lib/user/User.Template.tsx", workspaceRoot: "/repo" }),
+    ).toThrow(
+      'libs/shared/lib/user/User.Template.tsx is a "use client" module, so it cannot `export * from "../../ui/UserLeave"`',
+    );
+    expect(() => scanUseClientExports('"use client";\nexport * from "./a";\n', "/repo/ui/Barrel.ts")).toThrow(
+      "Re-export them by name",
+    );
+  });
+
+  test("leaves every other export shape alone, and a module that is not a client boundary", () => {
+    const file = "/repo/ui/Barrel.tsx";
+    const shapes = [
+      '"use client";',
+      'export type * from "./types";',
+      'export * as ns from "./namespace";',
+      'export { LeaveInfo, Voc } from "./leave";',
+      "// export * from './commented';",
+      "export const text = \"export * from './a string'\";",
+      "",
+    ].join("\n");
+    expect(scanUseClientExports(shapes, file).sort()).toEqual(["LeaveInfo", "Voc", "ns", "text"]);
+    expect(scanUseClientExports('export * from "./a";\nexport const X = 1;\n', file)).toEqual(["X"]);
+    const stub = transformUseClient(shapes, { path: file, workspaceRoot: "/repo" });
+    expect(stub).toContain("export const LeaveInfo = registerClientReference");
+    expect(stub).toContain("export const Voc = registerClientReference");
+  });
+
+  test("fails the server bundle, and the build report carries the reason out of the bundler's error", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "Leave.tsx"), '"use client";\nexport const LeaveInfo = () => null;\n');
+    await write(
+      path.join(root, "Template.tsx"),
+      '"use client";\nexport * from "./Leave";\nexport const General = () => null;\n',
+    );
+    await write(path.join(root, "page.tsx"), 'import * as Template from "./Template";\nexport const T = Template;\n');
+    const failure = await Bun.build({
+      entrypoints: [path.join(root, "page.tsx")],
+      target: "bun",
+      external: ["react-server-dom-webpack/server.node"],
+      plugins: [createUseClientBundlePlugin({ workspaceRoot: root })],
+    }).then(
+      () => null,
+      (error: unknown) => error,
+    );
+    expect(ApplicationBuildReporter.formatError(failure)).toContain(
+      'Template.tsx is a "use client" module, so it cannot `export * from "./Leave"`',
+    );
+  });
+});
+
 describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   test("analyzes local, named, aliased, and star re-exports while skipping type and namespace exports", async () => {
     const root = await makeTempRoot();
@@ -97,14 +145,83 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(map?.has("ns")).toBe(false);
   });
 
+  test("a name a module exports itself wins over the same name its star re-exports bring, as ES decides", async () => {
+    const root = await makeTempRoot();
+    const pkgDir = path.join(root, "pkg");
+    await write(
+      path.join(pkgDir, "index.ts"),
+      [
+        'export * from "./a";',
+        'export { X } from "./c";',
+        'export * from "./nested";',
+        "export const Local = 1;",
+        "",
+      ].join("\n"),
+    );
+    await write(path.join(pkgDir, "a.ts"), "export const X = 2;\nexport const Local = 2;\nexport const OnlyA = 2;\n");
+    await write(path.join(pkgDir, "c.ts"), "export const X = 1;\n");
+    await write(path.join(pkgDir, "nested", "index.ts"), 'export * from "./deep";\nexport { Y } from "./y";\n');
+    await write(path.join(pkgDir, "nested", "deep.ts"), "export const Y = 2;\n");
+    await write(path.join(pkgDir, "nested", "y.ts"), "export const Y = 1;\n");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@scope/pkg", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+
+    const runtime = (await import(path.join(pkgDir, "index.ts"))) as Record<string, number>;
+    expect([runtime.X, runtime.Local, runtime.Y, runtime.OnlyA]).toEqual([1, 1, 1, 2]);
+    const map = await analyzer.analyze("@scope/pkg");
+    expect(map?.get("X")).toEqual({ subpath: "@scope/pkg/c", originalName: "X" });
+    expect(map?.get("Local")).toEqual({ subpath: "@scope/pkg", originalName: "Local" });
+    expect(map?.get("Y")).toEqual({ subpath: "@scope/pkg/nested/y", originalName: "Y" });
+    expect(map?.get("OnlyA")).toEqual({ subpath: "@scope/pkg/a", originalName: "OnlyA" });
+  });
+
+  test("two analyses that interleave each keep their own place in their barrel", async () => {
+    const root = await makeTempRoot();
+    const barrels = { first: ["a1", "a2", "a3"], second: ["b1", "b2"] } as const;
+    for (const [pkgName, names] of Object.entries(barrels)) {
+      const lines = names.map((name) => `export { ${name} } from "./${name}";`);
+      // Parks the second walk past the end of the first barrel, so a shared regex position would end the first early.
+      const padding = pkgName === "second" ? [`// ${"-".repeat(200)}`] : [];
+      await write(path.join(root, pkgName, "index.ts"), [...padding, ...lines, ""].join("\n"));
+      for (const name of names) await write(path.join(root, pkgName, `${name}.ts`), `export const ${name} = 1;\n`);
+    }
+    const parked = { first: Promise.withResolvers<void>(), second: Promise.withResolvers<void>() };
+    const released = { first: Promise.withResolvers<void>(), second: Promise.withResolvers<void>() };
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async (pkgName) => ({
+        pkgName,
+        entryFile: path.join(root, pkgName, "index.ts"),
+        pkgDir: path.join(root, pkgName),
+      }),
+      resolveRelative: async (fromFile, relSpec) => {
+        const pkgName = path.basename(path.dirname(fromFile)) as keyof typeof barrels;
+        if (relSpec === `./${barrels[pkgName][0]}`) {
+          parked[pkgName].resolve();
+          await released[pkgName].promise;
+        }
+        return path.join(path.dirname(fromFile), `${relSpec.slice(2)}.ts`);
+      },
+    });
+
+    const first = analyzer.analyze("first");
+    await parked.first.promise;
+    const second = analyzer.analyze("second");
+    await parked.second.promise;
+    released.first.resolve();
+    const firstMap = await first;
+    released.second.resolve();
+    const secondMap = await second;
+
+    expect(firstMap?.get("a3")).toEqual({ subpath: "first/a3", originalName: "a3" });
+    expect(secondMap?.get("b2")).toEqual({ subpath: "second/b2", originalName: "b2" });
+  });
+
   test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
-    const analyzer = {
-      analyze: async () =>
-        new Map([
-          ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
-          ["Bee", { subpath: "@scope/pkg/leaf", originalName: "B" }],
-        ]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["Bee", { subpath: "@scope/pkg/leaf", originalName: "B" }],
+    ]);
 
     const rewritten = await rewriteBarrelImports(
       'import DefaultExport, { A, Bee as LocalBee, type Shape, Missing } from "@scope/pkg";\nconsole.log(A);',
@@ -126,9 +243,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   });
 
   test("preserves generated client barrel side effects when flattening app client imports", async () => {
-    const analyzer = {
-      analyze: async () => new Map([["st", { subpath: "@apps/demo/lib/st", originalName: "st" }]]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([["st", { subpath: "@apps/demo/lib/st", originalName: "st" }]]);
 
     const rewritten = await rewriteBarrelImports(
       'import { st } from "@apps/demo/client";\nvoid st;\n',
@@ -142,9 +257,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   });
 
   test("does not rewrite import-looking code inside template literals", async () => {
-    const analyzer = {
-      analyze: async () => new Map([["AkanApp", { subpath: "akanjs/server/akanApp", originalName: "AkanApp" }]]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([["AkanApp", { subpath: "akanjs/server/akanApp", originalName: "AkanApp" }]]);
 
     const source = [
       'import { Code } from "@apps/docs/ui";',
@@ -164,13 +277,10 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   });
 
   test("rewrites akanjs/server value imports to leaf subpaths", async () => {
-    const analyzer = {
-      analyze: async () =>
-        new Map([
-          ["AkanOption", { subpath: "akanjs/server/akanOption", originalName: "AkanOption" }],
-          ["Try", { subpath: "akanjs/server/decorators", originalName: "Try" }],
-        ]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([
+      ["AkanOption", { subpath: "akanjs/server/akanOption", originalName: "AkanOption" }],
+      ["Try", { subpath: "akanjs/server/decorators", originalName: "Try" }],
+    ]);
 
     const rewritten = await rewriteBarrelImports(
       'import { AkanOption, Try } from "akanjs/server";\nexport const option = new AkanOption();\n',
@@ -188,10 +298,9 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   });
 
   test("rewrites single-package Akan facet barrels to leaf subpaths", async () => {
-    const analyzer = {
-      analyze: async () =>
-        new Map([["BottomInset", { subpath: "akanjs/ui/Layout/BottomInset", originalName: "BottomInset" }]]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([
+      ["BottomInset", { subpath: "akanjs/ui/Layout/BottomInset", originalName: "BottomInset" }],
+    ]);
 
     const rewritten = await rewriteBarrelImports('import { BottomInset } from "akanjs/ui";\n', ["akanjs/ui"], analyzer);
 

package/transforms/tsconfigPackageResolver.test.ts

@@ -1,16 +1,10 @@
-import { afterEach, 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, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { tempDirs } from "../testHelpers";
 import { createTsconfigPackageResolver } from "./barrelImportsPlugin";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-resolver-"));
-  tempRoots.push(root);
-  return root;
-};
+const makeTempRoot = tempDirs("akan-devkit-resolver-");
 
 const write = async (root: string, relPath: string, content = "export const value = 1;\n") => {
   const filePath = path.join(root, relPath);
@@ -25,10 +19,6 @@ const resolverFor = async (root: string, paths: Record<string, string[]>) =>
     getTsConfig: async () => ({ compilerOptions: { paths } }),
   } as never);
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("createTsconfigPackageResolver — exact tsconfig mapping", () => {
   test("resolves a package barrel and keeps the specifier", async () => {
     const root = await makeTempRoot();
@@ -43,9 +33,6 @@ describe("createTsconfigPackageResolver — exact tsconfig mapping", () => {
   });
 
   test("collapses a facet specifier to its parent package", async () => {
-    // `@libs/util/server` maps to the sibling file `libs/util/server.ts`, not to a package directory, so a
-    // leaf rewritten under the raw specifier would become `@libs/util/server/lib/sig` — a path that does
-    // not exist. The parent specifier is what the `@libs/*` wildcard can actually resolve.
     const root = await makeTempRoot();
     const entryFile = await write(root, "libs/util/server.ts");
     const resolve = await resolverFor(root, { "@libs/util/server": ["./libs/util/server.ts"] });
@@ -134,8 +121,6 @@ describe("createTsconfigPackageResolver — wildcard tsconfig mapping", () => {
   });
 
   test("stops at the matched prefix instead of falling through to a shorter one", async () => {
-    // Falling through would resolve `@libs/util/ui` against `./libs/*`, silently loading an unrelated
-    // directory that happens to sit at the same subpath under a different root.
     const root = await makeTempRoot();
     await write(root, "libs/util/ui/index.ts");
     const resolve = await resolverFor(root, {
@@ -183,9 +168,7 @@ describe("createTsconfigPackageResolver — node_modules fallback", () => {
   });
 
   test("resolves a scoped package subpath", async () => {
-    // A scoped name is two path segments, so the package boundary cannot be found by splitting on the
-    // first slash. Kept vendor-neutral on purpose: `packageExports.test.ts` reads every
-    // `"@akanjs/devkit/<x>"` literal under this package as a subpath the monorepo imports.
+    // Vendor-neutral on purpose: `packageExports.test.ts` reads every `"@akanjs/devkit/<x>"` literal here as an import.
     const root = await makeTempRoot();
     await writePackageJson(root, "@vendor/kit", { exports: { "./lint": "./lint/index.ts" } });
     const entryFile = await write(root, "node_modules/@vendor/kit/lint/index.ts");
@@ -195,8 +178,7 @@ describe("createTsconfigPackageResolver — node_modules fallback", () => {
   });
 
   test("falls back to module/main when exports resolution declines the specifier", async () => {
-    // `main: "index.js"` has no leading `./`, which the exports resolver rejects — the last fallback
-    // resolves it against the package directory, and it is the one path that does not preserve the file.
+    // `main` without a leading `./` is declined by the exports resolver, so only the last fallback resolves it.
     const root = await makeTempRoot();
     await writePackageJson(root, "plainpkg", { main: "index.js" });
     const entryFile = await write(root, "node_modules/plainpkg/index.js");

package/transforms/useClientBundlePlugin.ts

@@ -1,21 +1,8 @@
 import type { BunPlugin } from "bun";
+import { loaderFor } from "./moduleSyntax";
 import { transformUseClient } from "./rscUseClientTransform";
 
-/**
- * BunPlugin that stubs `"use client"` modules so the server bundle sees
- * `registerClientReference(proxy, absPath, name)` stubs instead of the
- * original client code.
- *
- * The bundle produced by `PagesBundleBuilder` is loaded in the RSC worker
- * with `--conditions react-server`; client components are never supposed
- * to execute there. The resulting stub references keep the client
- * component manifest lookups working at render time while ensuring the
- * server bundle never drags the real client source graph in.
- *
- * Important: the second argument to `registerClientReference` must match the
- * key the client manifest uses. When `workspaceRoot` is provided, both sides
- * use workspace-relative keys so production artifacts are portable.
- */
+/** `workspaceRoot` makes reference keys workspace-relative; they must match the client manifest's keys. */
 export function createUseClientBundlePlugin(options: { workspaceRoot?: string } = {}): BunPlugin {
   return {
     name: "akan-use-client-bundle",
@@ -38,10 +25,3 @@ export function createUseClientBundlePlugin(options: { workspaceRoot?: string }
     },
   };
 }
-
-function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-  if (absPath.endsWith(".tsx")) return "tsx";
-  if (absPath.endsWith(".jsx")) return "jsx";
-  if (absPath.endsWith(".ts")) return "ts";
-  return "js";
-}