plgg-bundle 0.0.1

package/src/domain/usecase/asBundleConfig.ts

@@ -0,0 +1,257 @@
+import {
+  type BundleConfig,
+  type DevConfig,
+  type SourceAlias,
+  type Entry,
+  type Format,
+  type Target,
+} from "plgg-bundle/domain/model/BundleConfig";
+
+/**
+ * Validate an `unknown` value (a dynamically-imported
+ * config module's default export) into a typed
+ * {@link BundleConfig}. The config is the bundler's
+ * `unknown` boundary, so every field is narrowed with a
+ * real guard (`typeof`, `Array.isArray`) — no `as`, no
+ * `any`. Throws a `ConfigError` on the first invalid
+ * field.
+ *
+ * Externals are NOT a config field: the bundler derives
+ * them from the package's `package.json` dependency
+ * graph (see `deriveExternal`), so they cannot drift
+ * from the manifest.
+ */
+export const asBundleConfig = (
+  value: unknown,
+): BundleConfig => {
+  if (!isRecord(value)) {
+    return fail("config is not an object");
+  }
+  const devSection = dev(value);
+  return {
+    target: target(value),
+    root: str(value, "root"),
+    rootDir: str(value, "rootDir"),
+    outDir: str(value, "outDir"),
+    fileNamePattern: str(
+      value,
+      "fileNamePattern",
+    ),
+    entries: entries(value),
+    formats: formats(value),
+    alias: alias(value),
+    // `exactOptionalPropertyTypes`: only attach `dev` when
+    // the config actually declared it (never `dev:
+    // undefined`).
+    ...(devSection === undefined
+      ? {}
+      : { dev: devSection }),
+  };
+};
+
+/**
+ * The optional `dev` section (see {@link DevConfig}).
+ * Absent → `undefined` (a build-only library). Present →
+ * every field narrowed at the boundary.
+ */
+const dev = (
+  o: Record<string, unknown>,
+): DevConfig | undefined => {
+  const raw = o["dev"];
+  if (raw === undefined) {
+    return undefined;
+  }
+  if (!isRecord(raw)) {
+    return fail(`"dev" must be an object`);
+  }
+  return {
+    entry: str(raw, "entry"),
+    port: num(raw, "port"),
+    watch: strArray(raw, "watch"),
+    allowedHosts: strArray(
+      raw,
+      "allowedHosts",
+    ),
+    sourceAliases: sourceAliases(raw),
+  };
+};
+
+/**
+ * The optional `sourceAliases` array (defaults to `[]`):
+ * each element `{ prefix, srcDir }` — both strings.
+ */
+const sourceAliases = (
+  o: Record<string, unknown>,
+): ReadonlyArray<SourceAlias> => {
+  const raw = o["sourceAliases"];
+  return raw === undefined
+    ? []
+    : Array.isArray(raw)
+      ? raw.map(sourceAlias)
+      : fail(
+          `"sourceAliases" must be an array`,
+        );
+};
+
+const sourceAlias = (
+  raw: unknown,
+): SourceAlias =>
+  isRecord(raw) &&
+  typeof raw["prefix"] === "string" &&
+  typeof raw["srcDir"] === "string"
+    ? {
+        prefix: raw["prefix"],
+        srcDir: raw["srcDir"],
+      }
+    : fail(
+        `each sourceAlias needs string "prefix" and "srcDir"`,
+      );
+
+/**
+ * A required finite-number field.
+ */
+const num = (
+  o: Record<string, unknown>,
+  key: string,
+): number => {
+  const v = o[key];
+  return typeof v === "number" &&
+    Number.isFinite(v)
+    ? v
+    : fail(`"${key}" must be a number`);
+};
+
+/**
+ * A required array-of-strings field. Maps each element
+ * through a string guard (mirroring `entries`/`formats`)
+ * so the result is a real `string[]` — never a leaked
+ * `any[]` from `Array.isArray`.
+ */
+const strArray = (
+  o: Record<string, unknown>,
+  key: string,
+): ReadonlyArray<string> => {
+  const v = o[key];
+  return Array.isArray(v)
+    ? v.map((e) => strElem(e, key))
+    : fail(`"${key}" must be an array`);
+};
+
+const strElem = (
+  e: unknown,
+  key: string,
+): string =>
+  typeof e === "string"
+    ? e
+    : fail(
+        `each "${key}" entry must be a string`,
+      );
+
+/**
+ * The optional `target` field — `"library"` (default) or
+ * `"app"`. Absent means a library, so the existing
+ * library configs need no change.
+ */
+const target = (
+  o: Record<string, unknown>,
+): Target => {
+  const v = o["target"];
+  return v === undefined || v === "library"
+    ? "library"
+    : v === "app"
+      ? "app"
+      : fail(
+          `"target" must be "library" or "app"`,
+        );
+};
+
+/**
+ * Throw a config validation error. Return type `never`
+ * so a failed check is a dead end at the call site.
+ */
+const fail = (message: string): never => {
+  throw new Error(`ConfigError: ${message}`);
+};
+
+/**
+ * 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;
+
+/**
+ * A required string field.
+ */
+const str = (
+  o: Record<string, unknown>,
+  key: string,
+): string => {
+  const v = o[key];
+  return typeof v === "string"
+    ? v
+    : fail(`"${key}" must be a string`);
+};
+
+/**
+ * The `entries` array: each element an object with
+ * string `name` and `input`.
+ */
+const entries = (
+  o: Record<string, unknown>,
+): ReadonlyArray<Entry> => {
+  const raw = o["entries"];
+  return Array.isArray(raw)
+    ? raw.map(entry)
+    : fail(`"entries" must be an array`);
+};
+
+const entry = (raw: unknown): Entry =>
+  isRecord(raw) &&
+  typeof raw["name"] === "string" &&
+  typeof raw["input"] === "string"
+    ? { name: raw["name"], input: raw["input"] }
+    : fail(
+        `each entry needs string "name" and "input"`,
+      );
+
+/**
+ * The `formats` array: each `"es"` or `"cjs"`.
+ */
+const formats = (
+  o: Record<string, unknown>,
+): ReadonlyArray<Format> => {
+  const raw = o["formats"];
+  return Array.isArray(raw)
+    ? raw.map(format)
+    : fail(`"formats" must be an array`);
+};
+
+const format = (raw: unknown): Format =>
+  raw === "es" || raw === "cjs"
+    ? raw
+    : fail(`each format must be "es" or "cjs"`);
+
+/**
+ * The `alias` object: string `prefix` and `srcRoot`.
+ */
+const alias = (
+  o: Record<string, unknown>,
+): Readonly<{
+  prefix: string;
+  srcRoot: string;
+}> => {
+  const raw = o["alias"];
+  return isRecord(raw) &&
+    typeof raw["prefix"] === "string" &&
+    typeof raw["srcRoot"] === "string"
+    ? {
+        prefix: raw["prefix"],
+        srcRoot: raw["srcRoot"],
+      }
+    : fail(
+        `"alias" needs string "prefix" and "srcRoot"`,
+      );
+};

package/src/domain/usecase/build.ts

@@ -0,0 +1,259 @@
+import {
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  renameSync,
+  existsSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import {
+  type BundleConfig,
+  type Entry,
+  applyFileName,
+} from "plgg-bundle/domain/model/BundleConfig";
+import {
+  collectModules,
+  type Graph,
+} from "plgg-bundle/domain/usecase/collectModules";
+import {
+  emitCjsBundle,
+  emitEsmBundle,
+} from "plgg-bundle/domain/usecase/emitBundle";
+import { emitDts } from "plgg-bundle/domain/usecase/emitDts";
+import { deriveExternal } from "plgg-bundle/domain/usecase/deriveExternal";
+import { readExportNames } from "plgg-bundle/vendors/runner";
+import { discoverWorkspace } from "plgg-bundle/domain/usecase/discoverWorkspace";
+import { resolveWorkspaceSpecifier } from "plgg-bundle/domain/usecase/resolveWorkspaceSpecifier";
+
+/**
+ * Build one package's `dist` from its
+ * {@link BundleConfig}. Dispatches on the config
+ * `target`: a `"library"` (dual `es`/`cjs` per entry +
+ * per-file `.d.ts`, deps external) or the `"app"` leaf (a
+ * single self-contained `es` bundle, siblings inlined, no
+ * `.d.ts`). Both build into a private staging dir and
+ * publish with one atomic swap. Returns the relative
+ * paths written. Throws on the first failure (caught at
+ * the bin boundary). Fully synchronous.
+ */
+export const build = (
+  config: BundleConfig,
+): ReadonlyArray<string> => {
+  const outDir = join(config.root, config.outDir);
+  // Build into a PRIVATE staging dir, then swap it into
+  // place as the final step (see swapIntoPlace). The live
+  // `dist` must never be observed half-built: it is read
+  // concurrently — by a downstream package's `tsc`/runner
+  // resolving this package as a dependency, and by any
+  // overlapping build invocation. The old emptyDir-on-live
+  // pattern left a multi-second window where `dist` was
+  // missing or partial; a reader hitting it resolved the
+  // dependency to its `.js` (TS7016 implicit-any), to a
+  // not-yet-complete barrel (TS2305 "no exported member"),
+  // or found no `index.cjs.js` at all — the
+  // non-deterministic dts-emit flake. Staging shrinks that
+  // window from the whole build to a single rename.
+  const stageDir = `${outDir}.stage`;
+  emptyDir(stageDir);
+  const written =
+    config.target === "app"
+      ? buildApp(config, stageDir)
+      : buildLibrary(config, stageDir);
+  swapIntoPlace(stageDir, outDir);
+  return written;
+};
+
+/**
+ * Library build: per entry, emit the dual `es`/`cjs`
+ * bundle (CJS first so its runtime keys give ESM its
+ * export surface), then the per-file `.d.ts` tree once.
+ * Deps are external (ruling B), derived from the
+ * package's declared dependency graph (+ `node:*`) so a
+ * bundle stays faithful to its manifest and an undeclared
+ * import fails loudly.
+ */
+const buildLibrary = (
+  config: BundleConfig,
+  stageDir: string,
+): ReadonlyArray<string> => {
+  const external = deriveExternal(config.root);
+  const written: string[] = [];
+  for (const entry of config.entries) {
+    const graph = collectModules({
+      entryFile: join(
+        config.root,
+        config.rootDir,
+        entry.input,
+      ),
+      root: config.root,
+      aliasPrefix: config.alias.prefix,
+      aliasSrcRoot: join(
+        config.root,
+        config.alias.srcRoot,
+      ),
+      external,
+    });
+    written.push(
+      ...buildEntry(
+        config,
+        entry,
+        graph,
+        stageDir,
+      ),
+    );
+  }
+  emitDts({
+    root: config.root,
+    rootDir: config.rootDir,
+    outDir: stageDir,
+    aliasPrefix: config.alias.prefix,
+  });
+  return written;
+};
+
+/**
+ * App build: a single self-contained `es` bundle per
+ * entry with every workspace sibling INLINED from source
+ * (the mirror of the library externalization — a browser
+ * cannot resolve a bare `import "plgg"`). Only `node:*`
+ * stays external. No CJS, no export-surface discovery
+ * (an app entry has side effects and no exports, and the
+ * vm sandbox has no DOM to run it), and no `.d.ts`
+ * (nothing consumes the app).
+ */
+const buildApp = (
+  config: BundleConfig,
+  stageDir: string,
+): ReadonlyArray<string> => {
+  const packages = discoverWorkspace(config.root);
+  const written: string[] = [];
+  for (const entry of config.entries) {
+    const graph = collectModules({
+      entryFile: join(
+        config.root,
+        config.rootDir,
+        entry.input,
+      ),
+      root: config.root,
+      aliasPrefix: config.alias.prefix,
+      aliasSrcRoot: join(
+        config.root,
+        config.alias.srcRoot,
+      ),
+      external: NODE_EXTERNAL,
+      resolve: (specifier, fromFile) =>
+        resolveWorkspaceSpecifier({
+          specifier,
+          fromFile,
+          packages,
+        }),
+    });
+    const rel = applyFileName(
+      config.fileNamePattern,
+      entry.name,
+      "es",
+    );
+    writeOut(
+      join(stageDir, rel),
+      emitEsmBundle(graph, []),
+    );
+    written.push(rel);
+  }
+  return written;
+};
+
+/**
+ * The app's only external: Node built-ins. Everything
+ * else (plgg + siblings) is inlined.
+ */
+const NODE_EXTERNAL = /^node:/;
+
+/**
+ * Replace `outDir` with the freshly-built `stageDir` in a
+ * single rename, so a concurrent reader sees only a
+ * complete `dist` (old or new) — never a torn one. The
+ * destructive window is one `rename`, not the whole build.
+ */
+const swapIntoPlace = (
+  stageDir: string,
+  outDir: string,
+): void => {
+  const backup = `${outDir}.old`;
+  rmSync(backup, {
+    recursive: true,
+    force: true,
+  });
+  if (existsSync(outDir)) {
+    renameSync(outDir, backup);
+  }
+  renameSync(stageDir, outDir);
+  rmSync(backup, {
+    recursive: true,
+    force: true,
+  });
+};
+
+/**
+ * Build every configured format for one entry, returning
+ * the relative paths written.
+ */
+const buildEntry = (
+  config: BundleConfig,
+  entry: Entry,
+  graph: Graph,
+  destDir: string,
+): ReadonlyArray<string> => {
+  const cjs = emitCjsBundle(graph);
+  // Discover the exact export surface by running the CJS
+  // bundle and reading its keys — ESM cannot declare
+  // exports dynamically. The bundle's external requires
+  // resolve against the target package's node_modules.
+  const esm = emitEsmBundle(
+    graph,
+    readExportNames(cjs, config.root),
+  );
+  const written: string[] = [];
+  for (const format of config.formats) {
+    const code = format === "es" ? esm : cjs;
+    const rel = applyFileName(
+      config.fileNamePattern,
+      entry.name,
+      format,
+    );
+    writeOut(join(destDir, rel), code);
+    written.push(rel);
+  }
+  return written;
+};
+
+/**
+ * Empty (and recreate) the output directory. The
+ * recursive remove is the bundler's own build output —
+ * `force` tolerates a not-yet-existing dir.
+ */
+const emptyDir = (dir: string): void => {
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+};
+
+/**
+ * Write a file, creating parent dirs; re-throws with
+ * context on failure.
+ */
+const writeOut = (
+  path: string,
+  code: string,
+): void => {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, code, "utf8");
+  } catch (cause) {
+    throw new Error(
+      `IoError: cannot write ${path}: ${
+        cause instanceof Error
+          ? cause.message
+          : String(cause)
+      }`,
+    );
+  }
+};