plgg-bundle 0.0.1

package/src/Dev/usecase/parseImports.ts

@@ -0,0 +1,50 @@
+/**
+ * Extract the import specifiers from a TypeScript/ESM
+ * source string. Pure string analysis — no fs, no
+ * `typescript` AST — matching the three import forms the
+ * monorepo actually uses:
+ *
+ *  - static `import ... from "spec"`,
+ *  - re-export `export ... from "spec"`,
+ *  - dynamic `import("spec")`.
+ *
+ * The node adapter feeds each watched file's contents
+ * through this to build the local module graph. Returns
+ * specifiers in source order (duplicates preserved);
+ * resolution + local-only filtering is the adapter's job.
+ *
+ * This is intentionally a lightweight lexical scan, not a
+ * full parser: the specifiers it yields drive only the
+ * dev server's *reload decision* (which files are part of
+ * the served graph), never the production build, so an
+ * exotic un-matched form costs at most one conservative
+ * extra reload — never a wrong bundle.
+ */
+export const parseImports = (
+  source: string,
+): ReadonlyArray<string> =>
+  // Each pattern's first capture group is the quoted
+  // specifier's inner text. `Array.from(..., mapFn)` +
+  // a type-guard `filter` extracts it without an
+  // `if`/`??` branch on the (unreachable) `undefined` a
+  // capture group would only take if it were optional.
+  PATTERNS.flatMap((pattern) =>
+    Array.from(
+      source.matchAll(pattern),
+      (m) => m[1],
+    ).filter(
+      (spec): spec is string =>
+        spec !== undefined,
+    ),
+  );
+
+/**
+ * The specifier-bearing forms. A `from "…"` clause covers
+ * both `import` and `export`; a bare `import("…")` covers
+ * dynamic import. `["']` matches either quote style; the
+ * inner `[^"']+` is the specifier.
+ */
+const PATTERNS: ReadonlyArray<RegExp> = [
+  /\bfrom\s*["']([^"']+)["']/g,
+  /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g,
+];

package/src/Dev/usecase/reloadDecision.spec.ts

@@ -0,0 +1,50 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { buildGraph } from "plgg-bundle/Dev/usecase/buildGraph";
+import { shouldReload } from "plgg-bundle/Dev/usecase/reloadDecision";
+
+const graph = buildGraph([
+  { from: "/a.ts", to: "/b.ts" },
+]);
+
+test("shouldReload is true for a file that imports (graph key)", () =>
+  check(
+    shouldReload(graph, "/a.ts"),
+    toBe(true),
+  ));
+
+test("shouldReload is true for an imported file (graph value)", () =>
+  check(
+    shouldReload(graph, "/b.ts"),
+    toBe(true),
+  ));
+
+test("shouldReload is false for a source file outside the served graph", () =>
+  check(
+    shouldReload(graph, "/unrelated.ts"),
+    toBe(false),
+  ));
+
+test("shouldReload is true for a content (non-code) file edit", () =>
+  all([
+    check(
+      shouldReload(graph, "/docs/guide.md"),
+      toBe(true),
+    ),
+    check(
+      shouldReload(graph, "/assets/x.css"),
+      toBe(true),
+    ),
+  ]));
+
+test("shouldReload falls back to true for an empty graph", () =>
+  all([
+    check(
+      shouldReload(buildGraph([]), "/x.ts"),
+      toBe(true),
+    ),
+  ]));

package/src/Dev/usecase/reloadDecision.ts

@@ -0,0 +1,65 @@
+import { type ModuleGraph } from "plgg-bundle/Dev/model/ModuleGraph";
+
+/**
+ * Source-code extensions — the files the module graph
+ * tracks. A changed file with any OTHER extension is
+ * content (Markdown, an asset) whose edit the app re-reads
+ * at render time, so it always warrants a reload.
+ */
+const SOURCE_EXT: ReadonlyArray<string> = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".js",
+  ".mjs",
+];
+
+/**
+ * Whether a changed file warrants a hot-reload:
+ *
+ *  - content (non-source-code, e.g. `.md`) → always, since
+ *    the render re-reads it;
+ *  - source code that participates in the app's served
+ *    {@link ModuleGraph} (a graph key it imports from, or a
+ *    graph value something imports) → yes;
+ *  - source code the app never imports (a stray scratch
+ *    `.ts`) → ignored, so the browser only reloads on edits
+ *    that can change the output.
+ *
+ * Conservative fallback: an EMPTY graph means the scan
+ * could not map the app, so every change reloads rather
+ * than silently going stale. Pure decision over the graph —
+ * the adapter owns the fs.
+ */
+export const shouldReload = (
+  graph: ModuleGraph,
+  changed: string,
+): boolean =>
+  !isSourceCode(changed) ||
+  graph.size === 0 ||
+  graph.has(changed) ||
+  importsSomewhere(graph, changed);
+
+/** Whether a path is a tracked source-code file (by extension). */
+const isSourceCode = (
+  changed: string,
+): boolean =>
+  SOURCE_EXT.some((e) => changed.endsWith(e));
+
+/**
+ * Whether any node in the graph imports `changed` (i.e. it
+ * appears as an edge target). Local scan over the forward
+ * edges — the reverse lookup is only needed once per
+ * decision, so it is not memoised.
+ */
+const importsSomewhere = (
+  graph: ModuleGraph,
+  changed: string,
+): boolean => {
+  for (const tos of graph.values()) {
+    if (tos.includes(changed)) {
+      return true;
+    }
+  }
+  return false;
+};

package/src/domain/model/BundleConfig.spec.ts

@@ -0,0 +1,35 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { applyFileName } from "plgg-bundle/domain/model/BundleConfig";
+
+test("applyFileName substitutes name and format", () =>
+  all([
+    check(
+      applyFileName(
+        "[name].[format].js",
+        "index",
+        "es",
+      ),
+      toBe("index.es.js"),
+    ),
+    check(
+      applyFileName(
+        "[name].[format].js",
+        "index",
+        "cjs",
+      ),
+      toBe("index.cjs.js"),
+    ),
+    check(
+      applyFileName(
+        "[name].[format].js",
+        "styleEntry",
+        "es",
+      ),
+      toBe("styleEntry.es.js"),
+    ),
+  ]));

package/src/domain/model/BundleConfig.ts

@@ -0,0 +1,162 @@
+// Plain-TS build tool: a foundation bundler must not
+// depend on the library it builds (plgg), so this
+// package is written in plain TypeScript — native
+// control flow, throw-on-failure caught at the bin
+// boundary — rather than plgg's Result/Option idiom.
+// See README. The CLAUDE.md no-`as`/`any`/`ts-ignore`
+// rule still holds.
+
+/**
+ * The output module formats. `"es"` → ESM, `"cjs"` →
+ * CommonJS — both emitted today by every library
+ * package.
+ */
+export type Format = "es" | "cjs";
+
+/**
+ * What kind of artifact a config builds.
+ * - `"library"` (default): a consumed package — dual
+ *   `es`/`cjs` per entry, a per-file `.d.ts` tree, and
+ *   sibling/`node:*` deps left EXTERNAL (ruling B), so the
+ *   bundle stays faithful to its declared dependencies.
+ * - `"app"`: the leaf application (the `example` client) —
+ *   a single self-contained `es` bundle with every
+ *   workspace sibling INLINED from source (the mirror of
+ *   the library decision: the app is where bundling deps
+ *   is correct, since a browser cannot resolve a bare
+ *   `import "plgg"`). No `.d.ts` (nothing consumes it) and
+ *   only `node:*` stays external.
+ */
+export type Target = "library" | "app";
+
+/**
+ * A way to decide whether an imported specifier is
+ * *external* (left as a runtime `import`/`require`,
+ * not inlined into the bundle). Mirrors the three
+ * shapes used across the vite configs:
+ * - a string array of exact specifiers,
+ * - a `RegExp` (e.g. `/^node:/`),
+ * - a predicate function (plgg-fetch's
+ *   `isFrameworkDep`).
+ */
+export type External =
+  | ReadonlyArray<string>
+  | RegExp
+  | ((specifier: string) => boolean);
+
+/**
+ * One build entry. `name` is the output key — for most
+ * packages it equals the file stem, but `plgg-view`'s
+ * `styleEntry` / `plgg-server`'s `ssgEntry` use a
+ * distinct output key so `dist/styleEntry.*` does not
+ * case-collide with the `dist/Style/` declaration tree
+ * on case-insensitive filesystems (the U0 fix). The
+ * emitted JS file is `name` run through the config's
+ * `fileNamePattern`.
+ */
+export type Entry = {
+  name: string;
+  input: string;
+};
+
+/**
+ * The optional `dev` section: everything `plgg-bundle dev`
+ * needs to serve + hot-reload an app. Absent for a plain
+ * library config (build-only), so existing configs need no
+ * change.
+ *
+ * - `entry` — the app's dev-entry module (absolute or
+ *   `root`-relative), default-exporting a `FetchFactory`.
+ * - `port` — the port the node:http server binds.
+ * - `watch` — source roots (absolute or `root`-relative)
+ *   watched for code/content edits.
+ * - `allowedHosts` — extra `Host` headers accepted beyond
+ *   loopback (e.g. a tunnel domain).
+ * - `sourceAliases` — cross-package self-aliases to resolve
+ *   to SOURCE during dev, so a dependency's `<prefix>/*`
+ *   imports (e.g. a theme package's) load from its `.ts`
+ *   and hot-reload, instead of its built dist. Empty for a
+ *   self-contained app.
+ */
+export type DevConfig = Readonly<{
+  entry: string;
+  port: number;
+  watch: ReadonlyArray<string>;
+  allowedHosts: ReadonlyArray<string>;
+  sourceAliases: ReadonlyArray<SourceAlias>;
+}>;
+
+/**
+ * A dev-time source resolution rule: resolve `<prefix>`
+ * and `<prefix>/<sub>` specifiers to `<srcDir>` /
+ * `<srcDir>/<sub>` (`.ts`/`/index.ts`), so a dependency
+ * package's source participates in hot-reload.
+ */
+export type SourceAlias = Readonly<{
+  prefix: string;
+  srcDir: string;
+}>;
+
+/**
+ * The bundler's typed configuration, replacing
+ * vite.config's `lib` + `rollupOptions`. Parsed and
+ * validated at the `unknown` boundary by
+ * `asBundleConfig` before any build runs.
+ */
+export type BundleConfig = Readonly<{
+  /**
+   * The artifact kind (see {@link Target}). Optional in
+   * the config file; defaults to `"library"`.
+   */
+  target: Target;
+  /** Package root (absolute). */
+  root: string;
+  /** Source root under `root` (e.g. "src"). */
+  rootDir: string;
+  /** Output dir under `root` (e.g. "dist"). */
+  outDir: string;
+  /** One entry (single-entry) or several (multi). */
+  entries: ReadonlyArray<Entry>;
+  /** Formats to emit (es and/or cjs). */
+  formats: ReadonlyArray<Format>;
+  /**
+   * Output file-name template with `[name]` and
+   * `[format]` placeholders, e.g.
+   * `"[name].[format].js"` → `index.es.js` /
+   * `index.cjs.js` for the `index` entry,
+   * `styleEntry.es.js` for `styleEntry`. Reproduces
+   * vite's `index.${format}.js` / `${name}.${format}.js`.
+   */
+  fileNamePattern: string;
+  /**
+   * The package self-alias prefix and its source root,
+   * e.g. `{ prefix: "plgg", srcRoot: "src" }` so
+   * `plgg/Atomics/Num` resolves to `src/Atomics/Num`.
+   */
+  alias: Readonly<{
+    prefix: string;
+    srcRoot: string;
+  }>;
+  /**
+   * The dev-server section. Present only for a config that
+   * `plgg-bundle dev` serves; a build-only library omits
+   * it. See {@link DevConfig}.
+   */
+  dev?: DevConfig;
+}>;
+
+/**
+ * Apply a {@link BundleConfig#fileNamePattern} to an
+ * entry name and format, substituting `[name]` and
+ * `[format]`. Pure string templating.
+ */
+export const applyFileName = (
+  pattern: string,
+  name: string,
+  format: Format,
+): string =>
+  pattern
+    .split("[name]")
+    .join(name)
+    .split("[format]")
+    .join(format);

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

@@ -0,0 +1,230 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { asBundleConfig } from "plgg-bundle/domain/usecase/asBundleConfig";
+
+const valid = {
+  root: "/pkg",
+  rootDir: "src",
+  outDir: "dist",
+  fileNamePattern: "[name].[format].js",
+  entries: [{ name: "index", input: "index.ts" }],
+  formats: ["es", "cjs"],
+  alias: { prefix: "plgg", srcRoot: "src" },
+};
+
+/**
+ * True when `asBundleConfig(input)` throws a ConfigError
+ * (plain-TS validators throw rather than return a
+ * `Result`, so the spec catches at the boundary).
+ */
+const rejects = (input: unknown): boolean => {
+  try {
+    asBundleConfig(input);
+    return false;
+  } catch (e) {
+    return (
+      e instanceof Error &&
+      e.message.startsWith("ConfigError")
+    );
+  }
+};
+
+test("asBundleConfig accepts a well-formed config", () => {
+  const c = asBundleConfig(valid);
+  return all([
+    check(c.root, toBe("/pkg")),
+    check(
+      c.fileNamePattern,
+      toBe("[name].[format].js"),
+    ),
+    check(c.formats.length, toBe(2)),
+    check(c.entries.length, toBe(1)),
+    check(c.alias.prefix, toBe("plgg")),
+  ]);
+});
+
+test("asBundleConfig rejects a non-object", () =>
+  check(rejects(42), toBe(true)));
+
+test("asBundleConfig rejects a missing field", () =>
+  check(
+    rejects({ ...valid, formats: undefined }),
+    toBe(true),
+  ));
+
+test("asBundleConfig rejects an invalid format", () =>
+  check(
+    rejects({ ...valid, formats: ["es", "umd"] }),
+    toBe(true),
+  ));
+
+const validDev = {
+  entry: "devEntry.ts",
+  port: 5181,
+  watch: ["src", "docs"],
+  allowedHosts: ["plgg-guide.qmu.dev"],
+};
+
+test("asBundleConfig leaves dev absent for a build-only config", () =>
+  check(
+    asBundleConfig(valid).dev,
+    toBe(undefined),
+  ));
+
+test("asBundleConfig accepts and narrows a dev section", () => {
+  const c = asBundleConfig({
+    ...valid,
+    dev: validDev,
+  });
+  return all([
+    check(c.dev?.entry, toBe("devEntry.ts")),
+    check(c.dev?.port, toBe(5181)),
+    check(c.dev?.watch.length, toBe(2)),
+    check(
+      c.dev?.allowedHosts[0],
+      toBe("plgg-guide.qmu.dev"),
+    ),
+  ]);
+});
+
+test("asBundleConfig rejects a non-object dev section", () =>
+  check(
+    rejects({ ...valid, dev: 42 }),
+    toBe(true),
+  ));
+
+test("asBundleConfig rejects a dev section with a bad port", () =>
+  check(
+    rejects({
+      ...valid,
+      dev: { ...validDev, port: "5181" },
+    }),
+    toBe(true),
+  ));
+
+test("asBundleConfig rejects a dev section with a non-string watch entry", () =>
+  check(
+    rejects({
+      ...valid,
+      dev: { ...validDev, watch: ["src", 7] },
+    }),
+    toBe(true),
+  ));
+
+test("asBundleConfig rejects a dev section with non-array allowedHosts", () =>
+  check(
+    rejects({
+      ...valid,
+      dev: {
+        ...validDev,
+        allowedHosts: "nope",
+      },
+    }),
+    toBe(true),
+  ));
+
+test("asBundleConfig accepts target \"app\"", () =>
+  check(
+    asBundleConfig({ ...valid, target: "app" })
+      .target,
+    toBe("app"),
+  ));
+
+test("asBundleConfig rejects an invalid target", () =>
+  check(
+    rejects({ ...valid, target: "umd" }),
+    toBe(true),
+  ));
+
+test("asBundleConfig rejects a non-string required field", () =>
+  check(
+    rejects({ ...valid, root: 7 }),
+    toBe(true),
+  ));
+
+test("asBundleConfig rejects a malformed entry", () =>
+  all([
+    check(
+      rejects({
+        ...valid,
+        entries: [{ name: "x" }],
+      }),
+      toBe(true),
+    ),
+    check(
+      rejects({ ...valid, entries: [42] }),
+      toBe(true),
+    ),
+  ]));
+
+test("asBundleConfig rejects a malformed alias", () =>
+  all([
+    check(
+      rejects({ ...valid, alias: { prefix: "p" } }),
+      toBe(true),
+    ),
+    check(
+      rejects({ ...valid, alias: "nope" }),
+      toBe(true),
+    ),
+  ]));
+
+test("asBundleConfig rejects a non-string format element", () =>
+  check(
+    rejects({ ...valid, formats: [7] }),
+    toBe(true),
+  ));
+
+test("asBundleConfig defaults dev.sourceAliases to [] when absent", () =>
+  check(
+    asBundleConfig({ ...valid, dev: validDev })
+      .dev?.sourceAliases.length,
+    toBe(0),
+  ));
+
+test("asBundleConfig accepts dev.sourceAliases", () => {
+  const c = asBundleConfig({
+    ...valid,
+    dev: {
+      ...validDev,
+      sourceAliases: [
+        { prefix: "plggpress", srcDir: "../plggpress/src" },
+      ],
+    },
+  });
+  return all([
+    check(
+      c.dev?.sourceAliases[0]?.prefix,
+      toBe("plggpress"),
+    ),
+    check(
+      c.dev?.sourceAliases[0]?.srcDir,
+      toBe("../plggpress/src"),
+    ),
+  ]);
+});
+
+test("asBundleConfig rejects a non-array sourceAliases", () =>
+  check(
+    rejects({
+      ...valid,
+      dev: { ...validDev, sourceAliases: "nope" },
+    }),
+    toBe(true),
+  ));
+
+test("asBundleConfig rejects a malformed sourceAlias element", () =>
+  check(
+    rejects({
+      ...valid,
+      dev: {
+        ...validDev,
+        sourceAliases: [{ prefix: "x" }],
+      },
+    }),
+    toBe(true),
+  ));