plgg-bundle 0.0.1

package/src/index.ts

@@ -0,0 +1,28 @@
+// Public API of the in-house bundler. The CLI
+// (`bin/plgg-bundle.mjs` → `src/entrypoints/cli.ts`) is
+// the usual entry; these exports let other tooling
+// drive the bundler programmatically.
+export * from "plgg-bundle/domain/model/BundleConfig";
+export * from "plgg-bundle/domain/usecase/asBundleConfig";
+export * from "plgg-bundle/domain/usecase/build";
+export * from "plgg-bundle/domain/usecase/collectModules";
+export * from "plgg-bundle/domain/usecase/deriveExternal";
+export * from "plgg-bundle/domain/usecase/emitBundle";
+export * from "plgg-bundle/domain/usecase/emitDts";
+export * from "plgg-bundle/domain/usecase/isExternal";
+export * from "plgg-bundle/domain/usecase/resolveSpecifier";
+export * from "plgg-bundle/domain/usecase/rewriteDtsAliases";
+
+// Dev server (the `plgg-bundle dev` toolchain half): the
+// app⇄server contract, the pure hot-reload core, and the
+// node-adapter entry point.
+export * from "plgg-bundle/Dev/model/Fetch";
+export * from "plgg-bundle/Dev/model/ModuleGraph";
+export * from "plgg-bundle/Dev/model/Protocol";
+export * from "plgg-bundle/Dev/usecase/parseImports";
+export * from "plgg-bundle/Dev/usecase/buildGraph";
+export * from "plgg-bundle/Dev/usecase/invalidate";
+export * from "plgg-bundle/Dev/usecase/reloadDecision";
+export * from "plgg-bundle/Dev/usecase/decorateDevHtml";
+export * from "plgg-bundle/Dev/usecase/allowedHost";
+export * from "plgg-bundle/Dev/node/devServer";

package/src/vendors/runner.spec.ts

@@ -0,0 +1,50 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { join } from "node:path";
+import { readExportNames } from "plgg-bundle/vendors/runner";
+
+// Root createRequire at plgg-bundle's own package so a
+// bundle's external require resolves against real
+// node_modules / node builtins (gap #2: externals-aware
+// export-surface discovery).
+const resolveBase = join(
+  import.meta.dirname,
+  "..",
+  "..",
+);
+
+test("readExportNames reads a self-contained CJS bundle's keys", () =>
+  check(
+    readExportNames(
+      "exports.a = 1; exports.b = 2;",
+      resolveBase,
+    ).join(","),
+    toBe("a,b"),
+  ));
+
+test("readExportNames resolves an EXTERNAL require during discovery (gap #2)", () =>
+  // The bundle keeps `require("node:path")` as an
+  // external; discovery must run it via host require
+  // (rooted at the target package) without throwing,
+  // and still enumerate the entry's own exports.
+  all([
+    check(
+      readExportNames(
+        'const p = require("node:path"); exports.sep = p.sep; exports.x = 1;',
+        resolveBase,
+      ).join(","),
+      toBe("sep,x"),
+    ),
+    // __esModule is filtered out of the surface.
+    check(
+      readExportNames(
+        'Object.defineProperty(exports, "__esModule", { value: true }); exports.only = 1;',
+        resolveBase,
+      ).join(","),
+      toBe("only"),
+    ),
+  ]));

package/src/vendors/runner.ts

@@ -0,0 +1,78 @@
+import vm from "node:vm";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Run a self-contained CJS bundle in an isolated VM
+ * context and return its `module.exports` enumerable
+ * keys (minus `__esModule`), sorted. This is how the
+ * ESM emitter learns the exact public surface, since
+ * ESM cannot declare exports dynamically. Re-throws
+ * with context on failure.
+ *
+ * `resolveBase` is the TARGET package's root: the
+ * bundle's external `require("plgg")` / `require("node:*")`
+ * must resolve against the target package's own
+ * node_modules (not the bundler's), so the require is
+ * rooted there. Upstream dists exist in build order, so
+ * the externals resolve.
+ *
+ * Isolated in `src/vendors/` because executing generated
+ * code is an effectful boundary, not domain logic.
+ */
+export const readExportNames = (
+  cjsCode: string,
+  resolveBase: string,
+): ReadonlyArray<string> => {
+  try {
+    return keysOf(evalCjs(cjsCode, resolveBase));
+  } catch (cause) {
+    throw new Error(
+      `EvalError: failed to read export surface: ${
+        cause instanceof Error
+          ? cause.message
+          : String(cause)
+      }`,
+    );
+  }
+};
+
+/**
+ * Evaluate CJS source in a fresh context with a `require`
+ * rooted at the target package, an empty
+ * `module`/`exports`, and `console`, returning the
+ * populated `module.exports`.
+ */
+const evalCjs = (
+  code: string,
+  resolveBase: string,
+): object => {
+  const moduleObj: { exports: object } = {
+    exports: {},
+  };
+  const context = vm.createContext({
+    module: moduleObj,
+    exports: moduleObj.exports,
+    require: createRequire(
+      pathToFileURL(
+        join(resolveBase, "package.json"),
+      ),
+    ),
+    console,
+  });
+  vm.runInContext(code, context);
+  return moduleObj.exports;
+};
+
+/**
+ * Enumerable own keys of the exports object, dropping
+ * the `__esModule` interop marker, sorted for a stable
+ * named-export list.
+ */
+const keysOf = (
+  exportsObj: object,
+): ReadonlyArray<string> =>
+  Object.keys(exportsObj)
+    .filter((k) => k !== "__esModule")
+    .sort();

package/src/vendors/transpiler.ts

@@ -0,0 +1,48 @@
+import ts from "typescript";
+
+/**
+ * Anti-corruption layer over the TypeScript compiler's
+ * single-file transpile. Translation + delegation only:
+ * TS source in, plain CommonJS JavaScript out; a thrown
+ * compiler error is re-thrown with file context. No
+ * bundling logic lives here — the graph walk and emit
+ * are the in-house domain.
+ *
+ * CommonJS is the target because the in-house
+ * module-registry runtime (domain/usecase/emitBundle)
+ * wraps each module body as `(module, exports, require)
+ * => {...}`; TS lowers `export`/`import`/`export *` to
+ * the `exports.x = ` / `require(...)` forms the runtime
+ * rewrites and links. `removeComments` is the free size
+ * trim that stands in for a (rejected) minifier
+ * dependency.
+ */
+export const transpileToCjs = (
+  file: string,
+  source: string,
+): string => {
+  try {
+    return ts.transpileModule(source, {
+      fileName: file,
+      compilerOptions: {
+        module: ts.ModuleKind.CommonJS,
+        target: ts.ScriptTarget.ES2021,
+        esModuleInterop: false,
+        isolatedModules: true,
+        verbatimModuleSyntax: false,
+        removeComments: true,
+      },
+    }).outputText;
+  } catch (cause) {
+    throw new Error(
+      `TranspileError: ${file}: ${messageOf(cause)}`,
+    );
+  }
+};
+
+/**
+ * The message of an unknown thrown value, without
+ * assuming it is an `Error`.
+ */
+const messageOf = (e: unknown): string =>
+  e instanceof Error ? e.message : String(e);