@akanjs/devkit 3.1.0-rc.22 → 3.1.0-rc.24

package/README.ko.md

@@ -70,7 +70,7 @@ await runner.build();
 
 ## 요구사항
 
-- [Bun](https://bun.sh) `>=1.4.0`
+- [Bun](https://bun.sh) `>=1.4.4`
 - TypeScript
 - `react`는 optional peer이며, 렌더링하는 기능에서만 필요합니다.
 

package/README.md

@@ -69,7 +69,7 @@ defaults, the shares they derive from `AKAN_MEMORY_LIMIT`, and what a small cont
 
 ## Requirements
 
-- [Bun](https://bun.sh) `>=1.4.0`
+- [Bun](https://bun.sh) `>=1.4.4`
 - TypeScript
 - `react` is an optional peer, needed only by the features that render.
 

package/akanConfig/akanConfig.test.ts

@@ -11,6 +11,10 @@ import type { LibConfigInput } from "./types";
 const akanPackageJson = JSON.parse(
   fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "../../../akanjs/package.json"), "utf8"),
 ) as PackageJson;
+const rootPackageJson = JSON.parse(
+  fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "../../../../package.json"), "utf8"),
+) as { engines: { bun: string } };
+const pinnedBunImage = `oven/bun:${rootPackageJson.engines.bun}-slim`;
 
 const packageJson: PackageJson = {
   name: "repo",
@@ -206,9 +210,9 @@ describe("AkanAppConfig", () => {
   });
 
   test("writes the Dockerfile instructions it wrote before its env came from getProductionEnv", () => {
-    //? 9adfb95c's output for this config; only the blank lines its empty interpolations left are gone since.
+    //? 9adfb95c's output for this config, less the blank lines its empty interpolations left and its floating tag.
     const before = [
-      "FROM oven/bun:1-slim",
+      `FROM ${pinnedBunImage}`,
       "RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*",
       "RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime",
       "ARG TARGETARCH",
@@ -266,11 +270,11 @@ describe("AkanAppConfig", () => {
     expect(config.dockerfile).toBe(dockerfile);
   });
 
-  test("resolves the image parts, defaulting the base image and the command", () => {
+  test("resolves the image parts, defaulting the command and the base image to the Bun the repo pins", () => {
     const config = new AkanAppConfig(app, [], packageJson, { docker: { preRuns: ["echo hi"] } }, baseDevEnv);
 
     expect(config.docker).toEqual({
-      image: "oven/bun:1-slim",
+      image: pinnedBunImage,
       preRuns: ["echo hi"],
       postRuns: [],
       command: ["bun", "main.js"],

package/akanConfig/akanConfig.ts

@@ -47,7 +47,8 @@ const DEFAULT_OPTIMIZE_IMPORTS = [
   "@material-ui/icons @tabler/icons-react mui-core react-icons/*",
 ].flatMap((line) => line.split(" "));
 const WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"] as const;
-const DEFAULT_DOCKER_IMAGE = "oven/bun:1-slim";
+// `1-slim` floats to whichever Bun is newest at build time, one the framework was never tested on.
+const DEFAULT_DOCKER_IMAGE = "oven/bun:1.4.4-slim";
 const SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"] as const;
 const DEFAULT_AKAN_IMAGE_CONFIG: AkanImageConfig = {
   deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],

package/executors.test.ts

@@ -1078,7 +1078,7 @@ describe("PkgExecutor package generation", () => {
     expect(distPackageJson).toMatchObject({
       name: "@sample/tool",
       type: "module",
-      engines: { bun: ">=1.4.0" },
+      engines: { bun: ">=1.4.4" },
       dependencies: { lodash: "4.0.0" },
       devDependencies: { typescript: "6.0.0" },
       peerDependencies: { react: "19.0.0" },

package/executors.ts

@@ -1640,7 +1640,7 @@ export class PkgExecutor extends Executor {
           default: "./index.ts",
         },
       },
-      engines: { bun: ">=1.4.0" },
+      engines: { bun: ">=1.4.4" },
       ...dependencyMaps,
     };
     await Promise.all([this.dist.writeJson("package.json", distPkgJson), this.writeJson("package.json", distPkgJson)]);

package/frontendBuild/csrArtifactBuilder.test.ts

@@ -61,4 +61,44 @@ console.info(await result.outputs[0].text());
     expect(firstOutput).toBe(secondOutput);
     expect(firstOutput).not.toContain(path.basename(first));
   });
+
+  //? The shape of `@lexical/code-prism` under a `lazy()` editor, which threw in every view and CSR shell carrying it.
+  test("runs a lazily imported module's CommonJS side-effect import before the imports after it", async () => {
+    const root = await makeTempRoot();
+    const app = { getPublicEnv: () => ({ AKAN_PUBLIC_ENV: "main" }) };
+    await writeText(path.join(root, "node_modules/core/package.json"), '{ "name": "core", "main": "index.js" }\n');
+    await writeText(
+      path.join(root, "node_modules/core/index.js"),
+      "var Core = { langs: [] };\nglobalThis.Core = Core;\nmodule.exports = Core;\n",
+    );
+    await writeText(path.join(root, "node_modules/core/components/a.js"), 'Core.langs.push("a");\n');
+    await writeText(
+      path.join(root, "node_modules/highlight/package.json"),
+      '{ "name": "highlight", "type": "module", "main": "index.js" }\n',
+    );
+    await writeText(
+      path.join(root, "node_modules/highlight/index.js"),
+      'import "core";\nimport "core/components/a.js";\nexport const langs = () => globalThis.Core.langs;\n',
+    );
+    await writeText(
+      path.join(root, "entry.ts"),
+      'import("highlight").then(({ langs }) => console.info(langs().join()));\n',
+    );
+    const result = await Bun.build({
+      ...CsrArtifactBuilder.bundleOptions(app as never, "build"),
+      entrypoints: [path.join(root, "entry.ts")],
+    });
+    expect(result.success).toBe(true);
+    await Bun.write(path.join(root, "out.js"), (await result.outputs[0]?.text()) ?? "");
+
+    const proc = Bun.spawn([process.execPath, "out.js"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+
+    expect(stderr).toBe("");
+    expect(stdout.trim()).toBe("a");
+  });
 });

package/frontendBuild/csrArtifactBuilder.ts

@@ -4,6 +4,7 @@ import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
 import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
+import { SideEffectImportOrder } from "../transforms/sideEffectImportOrder";
 import { bundleDefine } from "./bundleDefine";
 import { CsrEntryFiles } from "./csrEntryFiles";
 import { type McpAppView, McpAppViewBuilder } from "./mcpAppViewBuilder";
@@ -113,7 +114,7 @@ export class CsrArtifactBuilder {
       define: bundleDefine(app, command, "csr"),
       optimizeImports,
       // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
-      plugins: [PagesBundleBuilder.createCssStubPlugin(), createBrowserDirnamePlugin()],
+      plugins: [PagesBundleBuilder.createCssStubPlugin(), createBrowserDirnamePlugin(), SideEffectImportOrder.plugin()],
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.22",
+  "version": "3.1.0-rc.24",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -14,7 +14,7 @@
     "directory": "pkgs/@akanjs/devkit"
   },
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.4"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0-rc.22",
+    "akanjs": "3.1.0-rc.24",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/transforms/sideEffectImportOrder.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { SideEffectImportOrder } from "./sideEffectImportOrder";
+
+const makeTempRoot = tempDirs("akan-devkit-side-effect-order-");
+
+const writePackage = async (root: string, name: string, files: Record<string, string>, manifest = {}) => {
+  await writeText(
+    path.join(root, "node_modules", name, "package.json"),
+    `${JSON.stringify({ name, main: "index.js", ...manifest })}\n`,
+  );
+  for (const [file, source] of Object.entries(files))
+    await writeText(path.join(root, "node_modules", name, file), source);
+};
+
+//? Prism's shape: a CommonJS core that sets a global, then language files that read it, imported only by `import()`.
+const writeHighlighter = async (root: string) => {
+  await writePackage(root, "core", {
+    "index.js": "var Core = { langs: [] };\nglobalThis.Core = Core;\nmodule.exports = Core;\n",
+    "components/a.js": 'Core.langs.push("a");\n',
+  });
+  await writePackage(
+    root,
+    "highlight",
+    {
+      "index.js": 'import "core";\nimport "core/components/a.js";\nexport const langs = () => globalThis.Core.langs;\n',
+    },
+    { type: "module" },
+  );
+  const entry = path.join(root, "entry.ts");
+  await writeText(entry, 'import("highlight").then(({ langs }) => console.info(JSON.stringify(langs())));\n');
+  return entry;
+};
+
+const bundle = async (entry: string, plugins = [SideEffectImportOrder.plugin()]) => {
+  const result = await Bun.build({ entrypoints: [entry], target: "browser", splitting: false, minify: true, plugins });
+  expect(result.success).toBe(true);
+  return (await result.outputs[0]?.text()) ?? "";
+};
+
+const run = async (root: string, code: string) => {
+  const outFile = path.join(root, "out.js");
+  await Bun.write(outFile, code);
+  const proc = Bun.spawn([process.execPath, outFile], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { stdout: stdout.trim(), stderr };
+};
+
+describe("SideEffectImportOrder", () => {
+  test("runs a CommonJS side-effect import before the imports after it in a module only import() reaches", async () => {
+    const root = await makeTempRoot();
+
+    const { stdout, stderr } = await run(root, await bundle(await writeHighlighter(root)));
+
+    expect(stderr).toBe("");
+    expect(stdout).toBe('["a"]');
+  });
+
+  //? A shim would keep what the bundler drops: a bare import of a module its package declares free of side effects.
+  test("bundles bare imports of ES modules, and of modules a package calls pure, as it would without the plugin", async () => {
+    const root = await makeTempRoot();
+    await writePackage(
+      root,
+      "chunks",
+      {
+        "index.js": 'import "./a.js";\nexport const a = () => globalThis.a;\n',
+        "a.js": 'globalThis.a = "chunk";\nexport {};\n',
+      },
+      { type: "module" },
+    );
+    await writePackage(
+      root,
+      "pure",
+      {
+        "index.js": 'import "./esm.js";\nimport "./cjs.cjs";\nexport const used = () => "used";\n',
+        "esm.js": 'globalThis.esm = "PURE_ESM";\nexport {};\n',
+        "cjs.cjs": 'globalThis.cjs = "PURE_CJS";\nmodule.exports = {};\n',
+      },
+      { type: "module", sideEffects: false },
+    );
+    const entry = path.join(root, "entry.ts");
+    await writeText(
+      entry,
+      'import("chunks").then(({ a }) => console.info(a()));\nimport("pure").then(({ used }) => console.info(used()));\n',
+    );
+
+    const [plugged, plain] = [await bundle(entry), await bundle(entry, [])];
+
+    expect(plugged).toBe(plain);
+    expect(plugged).not.toContain("PURE_");
+  });
+
+  test("resolves a shimmed import as the bundler resolves the original, browser field included", async () => {
+    const root = await makeTempRoot();
+    await writePackage(
+      root,
+      "pick",
+      {
+        "index.js": 'globalThis.picked = "node";\nmodule.exports = {};\n',
+        "browser.js": 'globalThis.picked = "browser";\nmodule.exports = {};\n',
+      },
+      { browser: "browser.js" },
+    );
+    await writePackage(
+      root,
+      "picker",
+      { "index.js": 'import "pick";\nexport const picked = () => globalThis.picked;\n' },
+      {
+        type: "module",
+      },
+    );
+    const entry = path.join(root, "entry.ts");
+    await writeText(entry, 'import("picker").then(({ picked }) => console.info(picked()));\n');
+
+    const { stdout } = await run(root, await bundle(entry));
+
+    expect(stdout).toBe("browser");
+  });
+
+  //? How the CSR shell and every view build: their entry HTML lives only in the build's `files`.
+  test("leaves an entry point a build hands in files to the bundler", async () => {
+    const root = await makeTempRoot();
+    await writeHighlighter(root);
+    const html = path.join(root, "generated/index.html");
+    const result = await Bun.build({
+      entrypoints: [html],
+      files: {
+        [html]: '<!doctype html><html><body><script type="module" src="./boot.ts"></script></body></html>\n',
+        [path.join(root, "generated/boot.ts")]:
+          'import("highlight").then(({ langs }) => console.info(langs().join()));\n',
+      },
+      target: "browser",
+      splitting: false,
+      outdir: path.join(root, "out"),
+      plugins: [SideEffectImportOrder.plugin()],
+    });
+    expect(result.success).toBe(true);
+    const script = result.outputs.find((output) => output.path.endsWith(".js"));
+
+    const { stdout, stderr } = await run(root, (await script?.text()) ?? "");
+
+    expect(stderr).toBe("");
+    expect(stdout).toBe("a");
+  });
+
+  //? An OTA release is keyed on the CSR bundle's hash, and a shim is named after its importer's absolute path.
+  test("bundles a shimmed import identically from two checkout paths", async () => {
+    const [first, second] = [await makeTempRoot(), await makeTempRoot()];
+
+    const [firstOutput, secondOutput] = [
+      await bundle(await writeHighlighter(first)),
+      await bundle(await writeHighlighter(second)),
+    ];
+
+    expect(firstOutput).toBe(secondOutput);
+    expect(firstOutput).not.toContain(path.basename(first));
+  });
+
+  test("points only a module's bare imports at their shims", async () => {
+    const root = await makeTempRoot();
+    await writePackage(root, "mod", {}, { type: "module" });
+    const source = [
+      'import "a";',
+      'import"b";import { c } from "c";',
+      'export * from "d";',
+      'import "e" with { type: "json" };',
+      'const text = `import "f";`;',
+    ];
+
+    const rewritten = await SideEffectImportOrder.rewrite(source.join("\n"), path.join(root, "node_modules/mod/x.js"));
+
+    expect(rewritten).toBe(
+      ['import "akan-side-effect:a";', 'import"akan-side-effect:b";import { c } from "c";', ...source.slice(2)].join(
+        "\n",
+      ),
+    );
+  });
+});

package/transforms/sideEffectImportOrder.ts

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import ts from "typescript";
+
+//* Without splitting, Bun (1.4.4 included) wraps a module that only an `import()` reaches, and the wrapper runs its ESM
+//* imports before its CommonJS ones whatever their order: `@lexical/code-prism` imports `prismjs`, then language files
+//* that read the `Prism` global it sets, so a single-file bundle threw. A vendor module's bare import that may run late
+//* is pointed at a shim importing the same specifier instead: an ESM import, so it keeps its place.
+export class SideEffectImportOrder {
+  static readonly #prefix = "akan-side-effect:";
+  static readonly #vendorModule = /[\\/]node_modules[\\/].+\.m?js$/;
+  static readonly #shim = /\.akan-side-effect$/;
+
+  static plugin(): BunPlugin {
+    return {
+      name: "akan-side-effect-order",
+      setup(build) {
+        const specifiers = new Map<string, string>();
+        //? Listed after the `__dirname` plugin: Bun runs one onLoad per module, so a module that one rewrites stays as is.
+        build.onLoad({ filter: SideEffectImportOrder.#vendorModule }, async ({ path: modulePath }) => {
+          const source = await Bun.file(modulePath).text();
+          const rewritten = await SideEffectImportOrder.rewrite(source, modulePath);
+          return rewritten === source ? undefined : { contents: rewritten, loader: "js" };
+        });
+        //? The prefix alone: an onResolve that matches an import loses its package's `sideEffects`, even unanswered.
+        build.onResolve({ filter: /^akan-side-effect:/ }, ({ path: prefixed, importer }) => {
+          const specifier = prefixed.slice(SideEffectImportOrder.#prefix.length);
+          //? Beside its importer, so the bundler resolves the shim's import as it would have the importer's.
+          const shimPath = `${importer}.${Bun.hash(specifier).toString(36)}.akan-side-effect`;
+          specifiers.set(shimPath, specifier);
+          return { path: shimPath };
+        });
+        build.onLoad({ filter: SideEffectImportOrder.#shim }, ({ path: shimPath }) => ({
+          contents: `import ${JSON.stringify(specifiers.get(shimPath))};\n`,
+          loader: "js",
+        }));
+      },
+    };
+  }
+
+  static async rewrite(source: string, filePath: string): Promise<string> {
+    if (!/\bimport\s*["']/.test(source)) return source;
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.JS);
+    const literals = sourceFile.statements.flatMap((statement) =>
+      ts.isImportDeclaration(statement) &&
+      !statement.importClause &&
+      !statement.attributes &&
+      ts.isStringLiteral(statement.moduleSpecifier)
+        ? [statement.moduleSpecifier]
+        : [],
+    );
+    const late = await Promise.all(literals.map((literal) => SideEffectImportOrder.#runsLate(literal.text, filePath)));
+    return literals
+      .filter((_, idx) => late[idx])
+      .reverse()
+      .reduce(
+        (rewritten, literal) =>
+          `${rewritten.slice(0, literal.getStart(sourceFile))}${JSON.stringify(`${SideEffectImportOrder.#prefix}${literal.text}`)}${rewritten.slice(literal.end)}`,
+        source,
+      );
+  }
+
+  //? Judged off the specifier, never resolved: a `Bun.resolveSync` primes the bundler's resolution, browser field lost.
+  static async #runsLate(specifier: string, importer: string) {
+    const from = path.dirname(importer);
+    const target = specifier.startsWith(".") ? path.resolve(from, specifier) : null;
+    //? An ESM import already keeps its place among the others.
+    if (target && (await SideEffectImportOrder.#isEsModule(target))) return false;
+    const sideEffects = await SideEffectImportOrder.#sideEffectsOf(
+      target ? path.dirname(target) : SideEffectImportOrder.#packageDirOf(specifier, from),
+    );
+    //? The bundler drops a bare import of a module its package declares pure, which a shim would keep.
+    return sideEffects === undefined || sideEffects === true;
+  }
+
+  static async #isEsModule(filePath: string) {
+    const file = Bun.file(filePath);
+    if (!/\.m?js$/.test(filePath) || !(await file.exists())) return false;
+    const sourceFile = ts.createSourceFile(
+      filePath,
+      await file.text(),
+      ts.ScriptTarget.Latest,
+      false,
+      ts.ScriptKind.JS,
+    );
+    return ts.isExternalModule(sourceFile);
+  }
+
+  static #packageDirOf(specifier: string, from: string) {
+    const name = specifier
+      .split("/")
+      .slice(0, specifier.startsWith("@") ? 2 : 1)
+      .join("/");
+    for (let dir = from; ; dir = path.dirname(dir)) {
+      const packageDir = path.join(dir, "node_modules", name);
+      if (existsSync(packageDir)) return packageDir;
+      if (path.dirname(dir) === dir) return from;
+    }
+  }
+
+  static async #sideEffectsOf(fromDir: string): Promise<unknown> {
+    for (let dir = fromDir; ; dir = path.dirname(dir)) {
+      const manifest = Bun.file(path.join(dir, "package.json"));
+      if (await manifest.exists()) return ((await manifest.json()) as { sideEffects?: unknown }).sideEffects;
+      if (path.dirname(dir) === dir) return undefined;
+    }
+  }
+}