plgg-bundle 0.0.1

package/src/domain/usecase/collectModules.ts

@@ -0,0 +1,226 @@
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { type External } from "plgg-bundle/domain/model/BundleConfig";
+import { resolveSpecifier } from "plgg-bundle/domain/usecase/resolveSpecifier";
+import { isExternal } from "plgg-bundle/domain/usecase/isExternal";
+import { transpileToCjs } from "plgg-bundle/vendors/transpiler";
+
+/**
+ * One bundled module: its stable id (path relative to
+ * the package root, the same string the runtime keys
+ * on), its transpiled-and-rewritten CJS body, and the
+ * external specifiers it still requires at runtime.
+ */
+export type Module = Readonly<{
+  id: string;
+  code: string;
+  externals: ReadonlyArray<string>;
+}>;
+
+/**
+ * The module graph reachable from an entry — the set of
+ * reachable modules plus the entry's own id. Dependency
+ * order is not required: the registry runtime links
+ * lazily by id.
+ */
+export type Graph = Readonly<{
+  entryId: string;
+  modules: ReadonlyArray<Module>;
+}>;
+
+/**
+ * Walk the import graph from `entryFile`, transpiling
+ * each `.ts` to CJS, resolving every `require(...)`
+ * specifier to either an intra-bundle module id (to
+ * inline) or an external (to keep as a runtime
+ * require), and rewriting the inlined `require("spec")`
+ * calls to `require("<id>")`. Pure in-house graph logic;
+ * only the per-file TS→JS step is vendored. Throws on an
+ * unresolvable import or a read failure.
+ */
+export const collectModules = (args: {
+  entryFile: string;
+  root: string;
+  aliasPrefix: string;
+  aliasSrcRoot: string;
+  external: External;
+  /**
+   * App-mode override: resolve a specifier to a source
+   * file (inlining workspace siblings). When absent, the
+   * library default resolves only relative imports and
+   * the package's own self-alias.
+   */
+  resolve?: Resolve;
+}): Graph => {
+  const ctx: Ctx = {
+    root: args.root,
+    external: args.external,
+    resolve:
+      args.resolve ??
+      ((specifier, fromFile) =>
+        resolveSpecifier({
+          specifier,
+          fromFile,
+          aliasPrefix: args.aliasPrefix,
+          aliasSrcRoot: args.aliasSrcRoot,
+        })),
+  };
+  const acc = new Map<string, Module>();
+  walk(ctx, args.entryFile, acc);
+  return {
+    entryId: idOf(args.root, args.entryFile),
+    modules: [...acc.values()],
+  };
+};
+
+/**
+ * Resolve an import specifier (from `fromFile`) to an
+ * absolute source file, or `undefined` if it is not a
+ * bundled module (external / unresolvable).
+ */
+export type Resolve = (
+  specifier: string,
+  fromFile: string,
+) => string | undefined;
+
+/**
+ * The threaded walk context: the package root (for ids),
+ * the external predicate, and the resolver.
+ */
+type Ctx = Readonly<{
+  root: string;
+  external: External;
+  resolve: Resolve;
+}>;
+
+/**
+ * Depth-first accumulation into a Map keyed by id, so a
+ * diamond import is transpiled once. Mutates `acc`.
+ */
+const walk = (
+  ctx: Ctx,
+  file: string,
+  acc: Map<string, Module>,
+): void => {
+  const id = idOf(ctx.root, file);
+  if (acc.has(id)) {
+    return;
+  }
+  const cjs = transpileToCjs(
+    file,
+    readSource(file),
+  );
+  const deps = linkModule(
+    ctx,
+    file,
+    id,
+    cjs,
+    acc,
+  );
+  for (const depFile of deps) {
+    walk(ctx, depFile, acc);
+  }
+};
+
+/**
+ * Resolve and rewrite every `require(...)` in a
+ * transpiled module, register it in `acc`, and return
+ * the resolved file paths of its intra-bundle deps.
+ * Throws on an unresolvable (non-external) specifier.
+ */
+const linkModule = (
+  ctx: Ctx,
+  file: string,
+  id: string,
+  cjs: string,
+  acc: Map<string, Module>,
+): ReadonlyArray<string> => {
+  const specifiers = requireSpecifiers(cjs);
+  const externals: string[] = [];
+  const deps: string[] = [];
+  let rewritten = cjs;
+  for (const spec of specifiers) {
+    if (isExternal(ctx.external, spec)) {
+      externals.push(spec);
+      continue;
+    }
+    const resolved = ctx.resolve(spec, file);
+    if (resolved === undefined) {
+      throw new Error(
+        `ResolveError: cannot resolve "${spec}" from ${id}`,
+      );
+    }
+    deps.push(resolved);
+    rewritten = replaceRequire(
+      rewritten,
+      spec,
+      idOf(ctx.root, resolved),
+    );
+  }
+  acc.set(id, {
+    id,
+    code: rewritten,
+    externals,
+  });
+  return deps;
+};
+
+/**
+ * Read a source file, re-throwing with context.
+ */
+const readSource = (file: string): string => {
+  try {
+    return readFileSync(file, "utf8");
+  } catch (cause) {
+    throw new Error(
+      `IoError: cannot read ${file}: ${
+        cause instanceof Error
+          ? cause.message
+          : String(cause)
+      }`,
+    );
+  }
+};
+
+/**
+ * A module's stable id: its path relative to the
+ * package root, POSIX-normalized. The runtime keys on
+ * exactly this string.
+ */
+const idOf = (
+  root: string,
+  file: string,
+): string =>
+  relative(root, file).split("\\").join("/");
+
+/**
+ * Extract the literal string specifiers of all
+ * top-level `require("...")` / `require('...')` calls
+ * a transpiled CJS module makes.
+ */
+const requireSpecifiers = (
+  cjs: string,
+): ReadonlyArray<string> =>
+  [
+    ...cjs.matchAll(
+      /require\(\s*["']([^"']+)["']\s*\)/g,
+    ),
+  ].flatMap((m) =>
+    m[1] === undefined ? [] : [m[1]],
+  );
+
+/**
+ * Rewrite every `require("spec")` occurrence to
+ * `require("id")`. Operates on the exact specifier
+ * string so distinct specifiers do not interfere.
+ */
+const replaceRequire = (
+  cjs: string,
+  spec: string,
+  id: string,
+): string =>
+  cjs
+    .split(`require("${spec}")`)
+    .join(`require("${id}")`)
+    .split(`require('${spec}')`)
+    .join(`require("${id}")`);

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

@@ -0,0 +1,125 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { join } from "node:path";
+import {
+  mkdtempSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { deriveExternal } from "plgg-bundle/domain/usecase/deriveExternal";
+import { isExternal } from "plgg-bundle/domain/usecase/isExternal";
+
+/** True when `deriveExternal(root)` throws an Error. */
+const rejects = (root: string): boolean => {
+  try {
+    deriveExternal(root);
+    return false;
+  } catch (e) {
+    return e instanceof Error;
+  }
+};
+
+/** A temp dir carrying a specific package.json body. */
+const withManifest = (body: string): string => {
+  const dir = mkdtempSync(
+    join(tmpdir(), "plgg-derive-"),
+  );
+  writeFileSync(
+    join(dir, "package.json"),
+    body,
+  );
+  return dir;
+};
+
+// plgg-bundle's own root: its package.json declares
+// `typescript` as the sole dependency.
+const root = join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "..",
+);
+const external = deriveExternal(root);
+
+test("deriveExternal externalizes declared deps and node builtins", () =>
+  all([
+    check(
+      isExternal(external, "typescript"),
+      toBe(true),
+    ),
+    check(
+      isExternal(external, "node:fs"),
+      toBe(true),
+    ),
+    check(
+      isExternal(external, "node:child_process"),
+      toBe(true),
+    ),
+  ]));
+
+test("deriveExternal externalizes a PUBLIC SUBPATH of a declared dep", () =>
+  // `typescript/lib/...` is a subpath of the declared
+  // `typescript` dep → external (resolved at runtime via
+  // the dep's own exports), mirroring `plgg-server/ssg`.
+  check(
+    isExternal(external, "typescript/lib/typescript"),
+    toBe(true),
+  ));
+
+test("deriveExternal does NOT externalize undeclared / own-source specifiers", () =>
+  all([
+    // plgg is not a dependency of plgg-bundle → not
+    // external (an import of it would fail loudly).
+    check(
+      isExternal(external, "plgg"),
+      toBe(false),
+    ),
+    check(
+      isExternal(external, "./resolveSpecifier"),
+      toBe(false),
+    ),
+    check(
+      isExternal(
+        external,
+        "plgg-bundle/domain/model/BundleConfig",
+      ),
+      toBe(false),
+    ),
+  ]));
+
+test("deriveExternal throws when package.json is missing", () =>
+  check(
+    rejects(
+      join(tmpdir(), "plgg-derive-missing-xyz"),
+    ),
+    toBe(true),
+  ));
+
+test("deriveExternal throws on an unparseable package.json", () =>
+  check(
+    rejects(withManifest("{ not valid json")),
+    toBe(true),
+  ));
+
+test("deriveExternal treats a non-object manifest as zero declared deps", () => {
+  const ext = deriveExternal(
+    withManifest(`"just a string"`),
+  );
+  return all([
+    // node:* is still external by prefix …
+    check(
+      isExternal(ext, "node:fs"),
+      toBe(true),
+    ),
+    // … but nothing is declared, so any package specifier
+    // is undeclared (not external).
+    check(
+      isExternal(ext, "whatever"),
+      toBe(false),
+    ),
+  ]);
+});

package/src/domain/usecase/deriveExternal.ts

@@ -0,0 +1,108 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type External } from "plgg-bundle/domain/model/BundleConfig";
+
+/**
+ * Derive a package's externals from its `package.json`
+ * (the declared dependency graph) plus Node builtins —
+ * the ruling-B rule, so externals cannot drift from what
+ * the manifest says the package depends on. Anything a
+ * module imports that is neither the package's own
+ * source (self-alias / relative) nor a declared
+ * dependency nor `node:*` is an *undeclared* dependency
+ * and the graph walk fails loudly rather than silently
+ * inlining or externalizing it.
+ *
+ * Declared = keys of `dependencies` + `peerDependencies`
+ * + `optionalDependencies`. A specifier is external when
+ * it is a declared dep exactly (`plgg-view`) OR a PUBLIC
+ * SUBPATH export of one (`plgg-view/style`,
+ * `plgg-server/ssg`) — the consumer resolves the subpath
+ * at runtime via the dep's own `exports` map, so a library
+ * bundle must never inline it. `node:*` is matched by
+ * prefix. An undeclared specifier (neither a dep nor a
+ * dep subpath nor `node:*`) still fails the graph walk
+ * loudly.
+ */
+export const deriveExternal = (
+  root: string,
+): External => {
+  const declared = declaredDeps(root);
+  return (specifier: string): boolean =>
+    declared.has(specifier) ||
+    [...declared].some((dep: string): boolean =>
+      specifier.startsWith(`${dep}/`),
+    ) ||
+    specifier.startsWith("node:");
+};
+
+/**
+ * The set of declared dependency names from a package's
+ * `package.json`. Throws (re-thrown with context) if the
+ * manifest is missing or unparseable.
+ */
+const declaredDeps = (
+  root: string,
+): ReadonlySet<string> => {
+  const path = join(root, "package.json");
+  const parsed = parse(path, read(path));
+  return new Set([
+    ...keysOf(parsed, "dependencies"),
+    ...keysOf(parsed, "peerDependencies"),
+    ...keysOf(parsed, "optionalDependencies"),
+  ]);
+};
+
+const read = (path: string): string => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (cause) {
+    throw new Error(
+      `IoError: cannot read ${path}: ${messageOf(
+        cause,
+      )}`,
+    );
+  }
+};
+
+const parse = (
+  path: string,
+  text: string,
+): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new Error(
+      `ConfigError: ${path} is not valid JSON: ${messageOf(
+        cause,
+      )}`,
+    );
+  }
+};
+
+/**
+ * The keys of one dependency map on a parsed
+ * package.json, narrowing at the `unknown` boundary.
+ */
+const keysOf = (
+  pkg: unknown,
+  field: string,
+): ReadonlyArray<string> => {
+  if (!isRecord(pkg)) {
+    return [];
+  }
+  const map = pkg[field];
+  return isRecord(map) ? Object.keys(map) : [];
+};
+
+/**
+ * Whether a value is a non-null object (records the
+ * narrowing for property reads).
+ */
+const isRecord = (
+  v: unknown,
+): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null;
+
+const messageOf = (e: unknown): string =>
+  e instanceof Error ? e.message : String(e);

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

@@ -0,0 +1,63 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { join } from "node:path";
+import { discoverWorkspace } from "plgg-bundle/domain/usecase/discoverWorkspace";
+
+// Run against the real monorepo: this package's root is
+// `packages/plgg-bundle`, so discovery scans `packages/*`.
+const bundleRoot = join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "..",
+);
+
+const packages = discoverWorkspace(bundleRoot);
+const byName = (name: string) =>
+  packages.find((p) => p.name === name);
+
+test("discoverWorkspace finds sibling packages", () =>
+  all([
+    check(
+      byName("plgg") !== undefined,
+      toBe(true),
+    ),
+    check(
+      byName("plgg-view") !== undefined,
+      toBe(true),
+    ),
+  ]));
+
+test("discoverWorkspace reads the conditions-only '.' export (plgg)", () =>
+  check(
+    byName("plgg")?.exports.get("."),
+    toBe("./dist/index.es.js"),
+  ));
+
+test("discoverWorkspace reads a subpath export incl. the styleEntry rename", () =>
+  all([
+    check(
+      byName("plgg-view")?.exports.get(
+        "./client",
+      ),
+      toBe("./dist/client.es.js"),
+    ),
+    check(
+      byName("plgg-view")?.exports.get("./style"),
+      toBe("./dist/styleEntry.es.js"),
+    ),
+  ]));
+
+test("discoverWorkspace sorts longest-name first (so plgg-view beats plgg)", () => {
+  const iView = packages.findIndex(
+    (p) => p.name === "plgg-view",
+  );
+  const iCore = packages.findIndex(
+    (p) => p.name === "plgg",
+  );
+  return check(iView < iCore, toBe(true));
+});

package/src/domain/usecase/discoverWorkspace.ts

@@ -0,0 +1,183 @@
+import {
+  readdirSync,
+  readFileSync,
+  existsSync,
+  statSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * A workspace sibling the app bundler can INLINE from
+ * source: its package `name`, its `dir`, and the map from
+ * each public export subpath (`"."`, `"./client"`, …) to
+ * the `import.default` dist path declared in its
+ * `package.json` `exports`. The app resolver reverses
+ * that dist path to the entry's source file (so the
+ * `./style` → `dist/styleEntry.es.js` → `src/styleEntry`
+ * rename is honoured), and falls back to a self-alias
+ * `name/<path>` → `src/<path>` for non-export internal
+ * imports.
+ */
+export type WorkspacePackage = Readonly<{
+  name: string;
+  dir: string;
+  /** export subpath (`"."` | `"./x"`) → dist default. */
+  exports: ReadonlyMap<string, string>;
+}>;
+
+/**
+ * Discover every sibling package under the directory that
+ * holds `packageRoot` (the monorepo `packages/` dir) —
+ * each entry that has a `package.json` with a `name`.
+ * Sorted longest-name-first so a later prefix match picks
+ * `plgg-view` over `plgg`. Throws on a read/parse failure.
+ */
+export const discoverWorkspace = (
+  packageRoot: string,
+): ReadonlyArray<WorkspacePackage> => {
+  const siblingsDir = dirname(packageRoot);
+  return readdirSync(siblingsDir)
+    .map((name) => join(siblingsDir, name))
+    .filter(isPackageDir)
+    .map(readPackage)
+    .flatMap((p) => (p === undefined ? [] : [p]))
+    .sort(
+      (a, b) => b.name.length - a.name.length,
+    );
+};
+
+/**
+ * Whether a path is a directory holding a
+ * `package.json`.
+ */
+const isPackageDir = (dir: string): boolean =>
+  statSync(dir).isDirectory() &&
+  existsSync(join(dir, "package.json"));
+
+/**
+ * Read one package's manifest into a
+ * {@link WorkspacePackage}, or `undefined` when it
+ * declares no `name`. Throws on unreadable/invalid JSON.
+ */
+const readPackage = (
+  dir: string,
+): WorkspacePackage | undefined => {
+  const pkg = parseJson(
+    join(dir, "package.json"),
+  );
+  const name = pkg["name"];
+  return typeof name === "string"
+    ? { name, dir, exports: exportMap(pkg) }
+    : undefined;
+};
+
+/**
+ * Parse a `package.json`, re-throwing with context.
+ */
+const parseJson = (
+  path: string,
+): Record<string, unknown> => {
+  try {
+    const parsed: unknown = JSON.parse(
+      readFileSync(path, "utf8"),
+    );
+    return isRecord(parsed) ? parsed : {};
+  } catch (cause) {
+    throw new Error(
+      `WorkspaceError: cannot read ${path}: ${
+        cause instanceof Error
+          ? cause.message
+          : String(cause)
+      }`,
+    );
+  }
+};
+
+/**
+ * Build the subpath → dist-default map from an `exports`
+ * field, tolerating both shapes used in the repo:
+ * - a subpath map (`{ ".": …, "./client": … }`), and
+ * - a bare conditions object (`{ import: …, require: … }`)
+ *   which IS the `"."` export.
+ */
+const exportMap = (
+  pkg: Record<string, unknown>,
+): ReadonlyMap<string, string> => {
+  const exports = pkg["exports"];
+  const out = new Map<string, string>();
+  if (!isRecord(exports)) {
+    return out;
+  }
+  if (isSubpathMap(exports)) {
+    for (const [key, val] of Object.entries(
+      exports,
+    )) {
+      const def = conditionDefault(val);
+      if (def !== undefined) {
+        out.set(key, def);
+      }
+    }
+    return out;
+  }
+  const def = conditionDefault(exports);
+  if (def !== undefined) {
+    out.set(".", def);
+  }
+  return out;
+};
+
+/**
+ * Whether an `exports` object is a subpath map (its keys
+ * are `.`/`./…` paths) rather than a bare conditions
+ * object (keys like `import`/`require`).
+ */
+const isSubpathMap = (
+  exports: Record<string, unknown>,
+): boolean =>
+  Object.keys(exports).some((k) =>
+    k.startsWith("."),
+  );
+
+/**
+ * Extract the resolved default file from a conditions
+ * object: the `import` (or `require`) branch's `default`,
+ * or a directly-stringed condition. Returns `undefined`
+ * when none is present.
+ */
+const conditionDefault = (
+  conditions: unknown,
+): string | undefined => {
+  if (typeof conditions === "string") {
+    return conditions;
+  }
+  if (!isRecord(conditions)) {
+    return undefined;
+  }
+  return (
+    branchDefault(conditions["import"]) ??
+    branchDefault(conditions["require"]) ??
+    branchDefault(conditions["default"])
+  );
+};
+
+/**
+ * The `default` of one condition branch, where the branch
+ * is either a string or a `{ types, default }` object.
+ */
+const branchDefault = (
+  branch: unknown,
+): string | undefined =>
+  typeof branch === "string"
+    ? branch
+    : isRecord(branch) &&
+        typeof branch["default"] === "string"
+      ? branch["default"]
+      : undefined;
+
+/**
+ * Whether a value is a non-null object.
+ */
+const isRecord = (
+  v: unknown,
+): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null;