plgg-bundle 0.0.1

package/src/domain/usecase/emitBundle.spec.ts

@@ -0,0 +1,162 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import {
+  emitCjsBundle,
+  emitEsmBundle,
+} from "plgg-bundle/domain/usecase/emitBundle";
+import { type Graph } from "plgg-bundle/domain/usecase/collectModules";
+
+const graph: Graph = {
+  entryId: "index.ts",
+  modules: [
+    {
+      id: "index.ts",
+      code: 'exports.x = require("dep.ts").x;',
+      externals: [],
+    },
+    {
+      id: "dep.ts",
+      code: "exports.x = 1;",
+      externals: [],
+    },
+  ],
+};
+
+test("emitCjsBundle wires the registry and entry export", () =>
+  all([
+    check(
+      emitCjsBundle(graph).includes(
+        "function __require(id)",
+      ),
+      toBe(true),
+    ),
+    check(
+      emitCjsBundle(graph).includes(
+        'module.exports = __require("index.ts")',
+      ),
+      toBe(true),
+    ),
+    check(
+      emitCjsBundle(graph).includes('"dep.ts":'),
+      toBe(true),
+    ),
+  ]));
+
+test("emitEsmBundle emits static named exports", () =>
+  all([
+    check(
+      emitEsmBundle(graph, ["x"]).includes(
+        "export default __entry;",
+      ),
+      toBe(true),
+    ),
+    check(
+      emitEsmBundle(graph, ["x"]).includes(
+        "} = __entry;",
+      ),
+      toBe(true),
+    ),
+    check(
+      emitEsmBundle(graph, ["x"]).includes("  x"),
+      toBe(true),
+    ),
+  ]));
+
+test("the emitted CJS bundle actually runs", () => {
+  // Evaluate the emitted CJS in a fresh module scope
+  // and confirm the entry's export resolves through the
+  // registry runtime.
+  const code = emitCjsBundle(graph);
+  const mod: {
+    exports: Record<string, unknown>;
+  } = {
+    exports: {},
+  };
+  new Function(
+    "module",
+    "exports",
+    "require",
+    code,
+  )(mod, mod.exports, () => ({}));
+  return check(mod.exports.x, toBe(1));
+});
+
+// A graph whose entry keeps an un-bundled external
+// require (e.g. a node builtin).
+const externalGraph: Graph = {
+  entryId: "index.ts",
+  modules: [
+    {
+      id: "index.ts",
+      code: 'exports.read = require("node:fs").readFileSync;',
+      externals: ["node:fs"],
+    },
+  ],
+};
+
+test("emitEsmBundle imports externals and routes the registry to them", () =>
+  all([
+    check(
+      emitEsmBundle(externalGraph, [
+        "read",
+      ]).includes(
+        'import * as __ext0 from "node:fs";',
+      ),
+      toBe(true),
+    ),
+    check(
+      emitEsmBundle(externalGraph, [
+        "read",
+      ]).includes('"node:fs": __ext0'),
+      toBe(true),
+    ),
+    check(
+      emitEsmBundle(externalGraph, [
+        "read",
+      ]).includes(
+        "if (id in __externals) return __externals[id];",
+      ),
+      toBe(true),
+    ),
+  ]));
+
+test("emitEsmBundle falls back to native dynamic import for unresolved ids", () =>
+  all([
+    // A runtime-only id (e.g. a config file path from a
+    // transpiled dynamic import) resolves natively …
+    check(
+      emitEsmBundle(externalGraph, [
+        "read",
+      ]).includes("return import(id);"),
+      toBe(true),
+    ),
+    // … instead of throwing as a build mistake.
+    check(
+      emitEsmBundle(externalGraph, [
+        "read",
+      ]).includes("Cannot resolve external"),
+      toBe(false),
+    ),
+  ]));
+
+test("emitCjsBundle leaves externals to the host require", () =>
+  all([
+    // No external import machinery in CJS …
+    check(
+      emitCjsBundle(externalGraph).includes(
+        "__externals",
+      ),
+      toBe(false),
+    ),
+    // … the un-rewritten require falls through to host.
+    check(
+      emitCjsBundle(externalGraph).includes(
+        "return require(id);",
+      ),
+      toBe(true),
+    ),
+  ]));

package/src/domain/usecase/emitBundle.ts

@@ -0,0 +1,215 @@
+import { type Format } from "plgg-bundle/domain/model/BundleConfig";
+import {
+  type Graph,
+  type Module,
+} from "plgg-bundle/domain/usecase/collectModules";
+
+/**
+ * Render a resolved {@link Graph} into one bundle's
+ * source text for the given {@link Format}, using an
+ * in-house module-registry runtime: every module body
+ * is wrapped in its own `(module, exports, require)`
+ * closure keyed by id, and a cached `__require` links
+ * them at runtime. This is collision-free by
+ * construction (each module keeps its own scope), so it
+ * needs none of rolldown's scope-hoisting/renaming and
+ * stays pure JS.
+ *
+ * Externals (specifiers left out of the bundle —
+ * `node:*`, sibling `plgg*` packages, …) are handled
+ * per format:
+ * - CJS: an un-rewritten `require("<external>")` in a
+ *   module body falls through the registry to the host
+ *   `require`.
+ * - ESM: there is no host `require`, so the bundle emits
+ *   a real top-level `import * as __extN from
+ *   "<external>"` for each distinct external and the
+ *   registry routes `__require("<external>")` to that
+ *   namespace.
+ */
+export const emitCjsBundle = (
+  graph: Graph,
+): string =>
+  [
+    `"use strict";`,
+    runtime(graph, `return require(id);`),
+    `module.exports = __require(${entryArg(
+      graph,
+    )});`,
+  ].join("\n");
+
+/**
+ * ESM bundle. `exportNames` is the exact public surface
+ * (the entry's enumerable export keys), supplied by the
+ * orchestrator from the CJS bundle's runtime keys —
+ * ESM cannot declare exports dynamically. Externals are
+ * imported as namespaces at the top and resolved by the
+ * registry; an id that is neither a bundled module nor a
+ * declared external falls back to a native dynamic
+ * `import(id)` (see {@link externalFallback}).
+ */
+export const emitEsmBundle = (
+  graph: Graph,
+  exportNames: ReadonlyArray<string>,
+): string => {
+  const externals = collectExternals(graph);
+  return [
+    externalImports(externals),
+    externalTable(externals),
+    runtime(graph, externalFallback()),
+    `const __entry = __require(${entryArg(
+      graph,
+    )});`,
+    `export default __entry;`,
+    namedExports(exportNames),
+  ].join("\n");
+};
+
+/**
+ * Dispatch on format for callers that hold the names
+ * regardless.
+ */
+export const emitBundle = (
+  graph: Graph,
+  format: Format,
+  exportNames: ReadonlyArray<string>,
+): string =>
+  format === "es"
+    ? emitEsmBundle(graph, exportNames)
+    : emitCjsBundle(graph);
+
+/**
+ * The shared registry runtime: a module table plus a
+ * caching `__require` that runs a module body once and
+ * memoizes its `exports`. An id with no bundled module
+ * runs `unknownBody` (the format-specific external
+ * fallback).
+ */
+const runtime = (
+  graph: Graph,
+  unknownBody: string,
+): string =>
+  [
+    `const __modules = {`,
+    graph.modules.map(moduleEntry).join(",\n"),
+    `};`,
+    `const __cache = {};`,
+    `function __require(id) {`,
+    `  if (id in __cache) return __cache[id].exports;`,
+    `  const fn = __modules[id];`,
+    `  if (!fn) { ${unknownBody} }`,
+    `  const module = { exports: {} };`,
+    `  __cache[id] = module;`,
+    `  fn(module, module.exports, __require);`,
+    `  return module.exports;`,
+    `}`,
+  ].join("\n");
+
+/**
+ * The ESM fallback body for an id with no bundled
+ * module: resolve it from the external namespace table
+ * (interop: a CJS consumer reads named members off the
+ * namespace; `default` carries the whole module), or
+ * fall back to a native dynamic `import(id)`. Static
+ * imports are always bundled or declared external, so
+ * only a transpiled dynamic `import(x)` — emitted as
+ * `Promise.resolve(x).then(s => __require(s))`, an
+ * async context where the returned Promise flattens —
+ * ever reaches the fallback; it lets bundled code load
+ * runtime files (e.g. a user's config) the registry
+ * cannot know. The CJS runtime keeps its host
+ * `require(id)` fall-through instead: its unknown-id
+ * branch is also reached by synchronous requires, where
+ * a returned Promise would corrupt the module value.
+ */
+const externalFallback = (): string =>
+  [
+    `if (id in __externals) return __externals[id];`,
+    `return import(id);`,
+  ].join(" ");
+
+/**
+ * Distinct external specifiers across the whole graph,
+ * sorted for deterministic output.
+ */
+const collectExternals = (
+  graph: Graph,
+): ReadonlyArray<string> =>
+  [
+    ...new Set(
+      graph.modules.flatMap((m) => m.externals),
+    ),
+  ].sort();
+
+/**
+ * Top-level namespace imports, one per external, named
+ * `__ext0`, `__ext1`, … in the externals' sorted order.
+ */
+const externalImports = (
+  externals: ReadonlyArray<string>,
+): string =>
+  externals
+    .map(
+      (spec, i) =>
+        `import * as ${extVar(i)} from ${JSON.stringify(
+          spec,
+        )};`,
+    )
+    .join("\n");
+
+/**
+ * The `__externals` lookup mapping each specifier to its
+ * imported namespace var.
+ */
+const externalTable = (
+  externals: ReadonlyArray<string>,
+): string =>
+  [
+    `const __externals = {`,
+    externals
+      .map(
+        (spec, i) =>
+          `  ${JSON.stringify(spec)}: ${extVar(i)}`,
+      )
+      .join(",\n"),
+    `};`,
+  ].join("\n");
+
+/**
+ * The namespace variable name for the i-th external.
+ */
+const extVar = (i: number): string => `__ext${i}`;
+
+/**
+ * One module's registry entry: `"id": function (module,
+ * exports, require) { <body> }`.
+ */
+const moduleEntry = (m: Module): string =>
+  [
+    `${JSON.stringify(m.id)}: `,
+    `function (module, exports, require) {\n`,
+    m.code,
+    `\n}`,
+  ].join("");
+
+/**
+ * Static named re-exports of the entry namespace. Each
+ * name is a valid identifier (a JS export name), so the
+ * `export const` list is itself valid ESM.
+ */
+const namedExports = (
+  names: ReadonlyArray<string>,
+): string =>
+  names.length === 0
+    ? ``
+    : [
+        `export const {`,
+        names.map((n) => `  ${n}`).join(",\n"),
+        `} = __entry;`,
+      ].join("\n");
+
+/**
+ * The JSON-quoted entry id used as `__require`'s arg.
+ */
+const entryArg = (graph: Graph): string =>
+  JSON.stringify(graph.entryId);

package/src/domain/usecase/emitDts.ts

@@ -0,0 +1,156 @@
+import { spawnSync } from "node:child_process";
+import {
+  join,
+  dirname,
+  basename,
+  relative,
+} from "node:path";
+import {
+  existsSync,
+  writeFileSync,
+  rmSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { rewriteDtsAliases } from "plgg-bundle/domain/usecase/rewriteDtsAliases";
+
+/**
+ * Emit the per-file `.d.ts` tree for a package — the
+ * single declaration mode every package uses. Rides on
+ * the project's own `tsc` in declaration-only mode (no
+ * new dependency); a single rolled-up `index.d.ts` was
+ * a vite-plugin-dts stylistic choice, not a correctness
+ * requirement, so it is dropped (breaking-changes-OK)
+ * to keep the bundler at zero new dependencies. Throws
+ * on a tsc failure.
+ *
+ * `emitDeclarationOnly` guarantees no `.js`/`.js.map`
+ * leaks into `dist` (the reproduction trap). The
+ * synthesized config reuses the package's
+ * `tsconfig.build.json` when present, else
+ * `tsconfig.json`, and adds the two things the
+ * declaration build needs but the package config must
+ * not carry permanently:
+ * - `emitDeclarationOnly` (the package config drives
+ *   `tsc --noEmit` type-checking),
+ * - exclusion of `*.spec.ts` and `dist`. Spec files are
+ *   not published API and, in a clean build, would pull
+ *   the package's own not-yet-built dist types through
+ *   plgg-test; excluding them also avoids the TS5055
+ *   "overwrite input" collision with a prior `dist`.
+ */
+export const emitDts = (args: {
+  root: string;
+  rootDir: string;
+  outDir: string;
+  aliasPrefix: string;
+}): void => {
+  const project = tsconfigFor(args.root);
+  const dtsConfig = join(
+    args.root,
+    "tsconfig.dts.json",
+  );
+  // tsc must emit into the SAME staging dir the JS bundles
+  // went to (args.outDir), overriding the `outDir: "dist"`
+  // the package config carries, so the whole `dist` is
+  // published atomically by the caller's single swap.
+  writeFileSync(
+    dtsConfig,
+    dtsTsconfig(
+      basename(project),
+      relative(args.root, args.outDir),
+    ),
+    "utf8",
+  );
+  // tsc invocation seam: run the package's OWN pinned
+  // `tsc` directly via `node` — NOT `npx`. `npx` re-runs
+  // its own resolution each call and, on a loaded
+  // machine, can intermittently resolve/launch `tsc`
+  // differently (the non-deterministic dts-emit flake
+  // Planner caught). Resolving the local binary makes
+  // the compiler, its version, and its module resolution
+  // identical every run.
+  const r = spawnSync(
+    process.execPath,
+    [tscBin(args.root), "--project", dtsConfig],
+    { cwd: args.root, encoding: "utf8" },
+  );
+  rmSync(dtsConfig, { force: true });
+  if (r.status !== 0) {
+    throw new Error(
+      `DtsError: tsc declaration emit failed\n${
+        r.stdout ?? ""
+      }${r.stderr ?? ""}`,
+    );
+  }
+  // Relativize the self-alias in the declarations (tsc
+  // leaves `paths` aliases verbatim; consumers have no
+  // such alias).
+  rewriteDtsAliases(
+    args.outDir,
+    args.aliasPrefix,
+  );
+};
+
+/**
+ * The synthesized declaration-emit tsconfig, extending
+ * the package's base config.
+ */
+const dtsTsconfig = (
+  baseName: string,
+  outRel: string,
+): string =>
+  JSON.stringify(
+    {
+      extends: `./${baseName}`,
+      compilerOptions: {
+        noEmit: false,
+        declaration: true,
+        emitDeclarationOnly: true,
+        // Emit into the caller's staging dir, not the
+        // live `dist` (overrides the package config).
+        outDir: outRel,
+        // No incremental cache: a `.tsbuildinfo` could
+        // otherwise persist a stale module resolution
+        // across runs. Each emit is a clean resolution.
+        incremental: false,
+        composite: false,
+      },
+      exclude: [
+        "**/*.spec.ts",
+        "**/*.spec.tsx",
+        "dist",
+        `${outRel}`,
+        "node_modules",
+      ],
+    },
+    null,
+    2,
+  );
+
+/**
+ * Absolute path to the package's OWN pinned `tsc`
+ * launcher, resolved from its `typescript` dependency
+ * (derived from the package main so it works regardless
+ * of `typescript`'s `exports` map). Run via `node`.
+ */
+const tscBin = (root: string): string =>
+  join(
+    dirname(
+      createRequire(
+        join(root, "package.json"),
+      ).resolve("typescript"),
+    ),
+    "..",
+    "bin",
+    "tsc",
+  );
+
+/**
+ * Pick the tsconfig that drives declaration emit:
+ * `tsconfig.build.json` when the package carries one,
+ * otherwise `tsconfig.json`.
+ */
+const tsconfigFor = (root: string): string =>
+  existsSync(join(root, "tsconfig.build.json"))
+    ? join(root, "tsconfig.build.json")
+    : join(root, "tsconfig.json");

package/src/domain/usecase/isExternal.spec.ts

@@ -0,0 +1,53 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { isExternal } from "plgg-bundle/domain/usecase/isExternal";
+
+test("isExternal handles a string-array external", () =>
+  all([
+    check(
+      isExternal(["plgg", "node:fs"], "plgg"),
+      toBe(true),
+    ),
+    check(
+      isExternal(["plgg"], "plgg-server"),
+      toBe(false),
+    ),
+    check(
+      isExternal([], "anything"),
+      toBe(false),
+    ),
+  ]));
+
+test("isExternal handles a RegExp external", () =>
+  all([
+    check(
+      isExternal(/^node:/, "node:stream"),
+      toBe(true),
+    ),
+    check(
+      isExternal(/^node:/, "plgg/index"),
+      toBe(false),
+    ),
+  ]));
+
+test("isExternal handles a predicate external", () =>
+  all([
+    check(
+      isExternal(
+        (id) => id.startsWith("plgg"),
+        "plgg-server/node",
+      ),
+      toBe(true),
+    ),
+    check(
+      isExternal(
+        (id) => id.startsWith("plgg"),
+        "./relative",
+      ),
+      toBe(false),
+    ),
+  ]));

package/src/domain/usecase/isExternal.ts

@@ -0,0 +1,20 @@
+import { type External } from "plgg-bundle/domain/model/BundleConfig";
+
+/**
+ * Decide whether a specifier is external given the
+ * config's {@link External} declaration, dispatching on
+ * its three shapes: a string array (exact match), a
+ * `RegExp` (test), or a predicate function (call). This
+ * is the single place the three vite-config external
+ * forms — string[], `/^node:/`, and plgg-fetch's
+ * `isFrameworkDep` predicate — converge.
+ */
+export const isExternal = (
+  external: External,
+  specifier: string,
+): boolean =>
+  typeof external === "function"
+    ? external(specifier)
+    : external instanceof RegExp
+      ? external.test(specifier)
+      : external.includes(specifier);

package/src/domain/usecase/resolveSpecifier.spec.ts

@@ -0,0 +1,112 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { join } from "node:path";
+import { resolveSpecifier } from "plgg-bundle/domain/usecase/resolveSpecifier";
+
+// Resolve against this package's own src tree on disk.
+const srcRoot = join(
+  import.meta.dirname,
+  "..",
+  "..",
+);
+const aliasArgs = {
+  aliasPrefix: "plgg-bundle",
+  aliasSrcRoot: srcRoot,
+};
+
+test("resolveSpecifier resolves an alias to a file", () =>
+  check(
+    resolveSpecifier({
+      specifier:
+        "plgg-bundle/domain/usecase/isExternal",
+      fromFile: join(srcRoot, "index.ts"),
+      ...aliasArgs,
+    }),
+    toBe(
+      join(
+        srcRoot,
+        "domain",
+        "usecase",
+        "isExternal.ts",
+      ),
+    ),
+  ));
+
+test("resolveSpecifier returns undefined for an alias dir with no index", () =>
+  // domain/model has no index.ts → unresolvable.
+  check(
+    resolveSpecifier({
+      specifier: "plgg-bundle/domain/model",
+      fromFile: join(srcRoot, "index.ts"),
+      ...aliasArgs,
+    }),
+    toBe(undefined),
+  ));
+
+test("resolveSpecifier resolves a relative path", () =>
+  check(
+    resolveSpecifier({
+      specifier: "./isExternal",
+      fromFile: join(
+        srcRoot,
+        "domain",
+        "usecase",
+        "collectModules.ts",
+      ),
+      ...aliasArgs,
+    }),
+    toBe(
+      join(
+        srcRoot,
+        "domain",
+        "usecase",
+        "isExternal.ts",
+      ),
+    ),
+  ));
+
+test("resolveSpecifier maps a .js specifier to its .ts source (NodeNext)", () =>
+  check(
+    resolveSpecifier({
+      specifier: "./isExternal.js",
+      fromFile: join(
+        srcRoot,
+        "domain",
+        "usecase",
+        "collectModules.ts",
+      ),
+      ...aliasArgs,
+    }),
+    toBe(
+      join(
+        srcRoot,
+        "domain",
+        "usecase",
+        "isExternal.ts",
+      ),
+    ),
+  ));
+
+test("resolveSpecifier returns undefined for an external specifier", () =>
+  all([
+    check(
+      resolveSpecifier({
+        specifier: "plgg",
+        fromFile: join(srcRoot, "index.ts"),
+        ...aliasArgs,
+      }),
+      toBe(undefined),
+    ),
+    check(
+      resolveSpecifier({
+        specifier: "node:fs",
+        fromFile: join(srcRoot, "index.ts"),
+        ...aliasArgs,
+      }),
+      toBe(undefined),
+    ),
+  ]));