@akanjs/devkit 3.1.0-rc.9 → 3.1.1-rc.0

package/transforms/pureLazyMarker.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { PureLazyMarker } from "./pureLazyMarker";
+
+const makeTempRoot = tempDirs("akan-pure-lazy-");
+
+describe("PureLazyMarker", () => {
+  test("marks each lazy() a declaration holds, and nothing else", () => {
+    const source = [
+      'import { lazy } from "akanjs/webkit";',
+      'export const Globe = lazy(() => import("./Globe_Dynamic"), { ssr: false });',
+      "const Editor: Component = lazy(() =>",
+      '  import("./Editor"),',
+      ");",
+      'const sample = `const Chart = lazy(() => import("./Chart"));`;',
+      'register(lazy(() => import("./Side")));',
+    ].join("\n");
+    expect(PureLazyMarker.mark(source, "ui.tsx")).toBe(
+      [
+        'import { lazy } from "akanjs/webkit";',
+        'export const Globe = /* @__PURE__ */ lazy(() => import("./Globe_Dynamic"), { ssr: false });',
+        "const Editor: Component = /* @__PURE__ */ lazy(() =>",
+        '  import("./Editor"),',
+        ");",
+        'const sample = `const Chart = lazy(() => import("./Chart"));`;',
+        'register(lazy(() => import("./Side")));',
+      ].join("\n"),
+    );
+    const plain = "export const one = 1;";
+    expect(PureLazyMarker.mark(plain, "plain.ts")).toBe(plain);
+  });
+
+  test("lets the bundler drop a barrel's lazy component that nothing renders, with what it imports", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, "lazy.ts"), "export const lazy = (load: () => Promise<unknown>) => ({ load });\n");
+    await writeText(path.join(root, "Heavy.ts"), 'export default "a heavy chunk";\n');
+    await writeText(
+      path.join(root, "ui.ts"),
+      [
+        'import { lazy } from "./lazy";',
+        'export const Heavy = lazy(() => import("./Heavy"));',
+        'export const Card = "a card";',
+      ].join("\n"),
+    );
+    await writeText(path.join(root, "entry.ts"), 'import { Card } from "./ui";\nconsole.info(Card);\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [PureLazyMarker.plugin()],
+      splitting: false,
+    });
+    const [output] = result.outputs;
+    expect(result.success).toBe(true);
+    const text = (await output?.text()) ?? "";
+    expect(text).toContain("a card");
+    expect(text).not.toContain("a heavy chunk");
+  });
+});

package/transforms/pureLazyMarker.ts

@@ -0,0 +1,42 @@
+import type { BunPlugin } from "bun";
+import ts from "typescript";
+
+//* A view inlines every module its loads reach, so a `lazy()` component that nothing renders (one of a barrel's, or
+//* of an `_overrides.tsx` manifest's) would still carry its chunk. `lazy()` only builds a component, so its call is
+//* marked pure, and the bundler drops it, chunk and all, wherever its result goes unread.
+export class PureLazyMarker {
+  static plugin(): BunPlugin {
+    return {
+      name: "akan-pure-lazy",
+      setup(build) {
+        build.onLoad({ filter: /\.tsx?$/ }, async (args) => {
+          const file = Bun.file(args.path);
+          //? A view's own entry lives only in the build's `files`, where the bundler reads it without a plugin.
+          if (!(await file.exists())) return undefined;
+          const source = await file.text();
+          const marked = PureLazyMarker.mark(source, args.path);
+          return marked === source
+            ? undefined
+            : { contents: marked, loader: args.path.endsWith(".tsx") ? "tsx" : "ts" };
+        });
+      },
+    };
+  }
+
+  static mark(source: string, filePath: string): string {
+    if (!source.includes("lazy(")) return source;
+    const kind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, kind);
+    const starts: number[] = [];
+    const visit = (node: ts.Node) => {
+      const call = ts.isVariableDeclaration(node) ? node.initializer : undefined;
+      if (call && ts.isCallExpression(call) && ts.isIdentifier(call.expression) && call.expression.text === "lazy")
+        starts.push(call.getStart(sourceFile));
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return starts
+      .sort((a, b) => b - a)
+      .reduce((marked, start) => `${marked.slice(0, start)}/* @__PURE__ */ ${marked.slice(start)}`, source);
+  }
+}

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;
+    }
+  }
+}