plgg-bundle 0.0.1

package/src/Dev/node/scanGraph.ts

@@ -0,0 +1,203 @@
+import {
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import {
+  resolve,
+  dirname,
+  join,
+} from "node:path";
+import { parseImports } from "plgg-bundle/Dev/usecase/parseImports";
+import { buildGraph } from "plgg-bundle/Dev/usecase/buildGraph";
+import { type ModuleGraph } from "plgg-bundle/Dev/model/ModuleGraph";
+
+// The effectful graph scan: walk the watch roots, read
+// each source file, and resolve its LOCAL import edges
+// (relative specifiers + the app's own self-alias) to
+// absolute paths. Feeds the pure `buildGraph` /
+// reload-decision. In `Dev/node/` (fs seam), excluded from
+// the coverage threshold and exercised by the fixture PoC.
+
+/** Source extensions whose imports are scanned. */
+const SOURCE_EXT: ReadonlyArray<string> = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".js",
+  ".mjs",
+];
+
+/**
+ * A self-alias resolution rule: `<prefix>`/`<prefix>/<sub>`
+ * → `<srcDir>`/`<srcDir>/<sub>`. One per package whose
+ * source participates in dev (the app's own, plus any
+ * cross-package `sourceAliases`).
+ */
+export type Alias = Readonly<{
+  prefix: string;
+  srcDir: string;
+}>;
+
+/**
+ * Scan the watch roots and build the local
+ * {@link ModuleGraph}, resolving relative AND aliased
+ * imports (every rule in `aliases`) so cross-package source
+ * edges are captured. Unreadable roots/files are skipped (a
+ * scan is best-effort — the reload decision falls back to
+ * reloading when the graph is empty).
+ */
+export const scanGraph = (
+  roots: ReadonlyArray<string>,
+  aliases: ReadonlyArray<Alias>,
+): ModuleGraph =>
+  buildGraph(
+    sourceFiles(roots).flatMap((file) =>
+      edgesOf(file, aliases),
+    ),
+  );
+
+/** Every source file under the roots (recursive, de-duped). */
+const sourceFiles = (
+  roots: ReadonlyArray<string>,
+): ReadonlyArray<string> => {
+  const seen = new Set<string>();
+  for (const root of roots) {
+    for (const abs of walk(root)) {
+      seen.add(abs);
+    }
+  }
+  return [...seen];
+};
+
+/**
+ * Directories never descended into during the graph scan —
+ * dependency trees, build output, VCS. A watch root of `.`
+ * (a package dir) would otherwise pull thousands of
+ * `node_modules` files into the graph.
+ */
+const SKIP_DIRS: ReadonlyArray<string> = [
+  "node_modules",
+  "dist",
+  ".git",
+];
+
+/**
+ * Recursively list source files under a directory, pruning
+ * {@link SKIP_DIRS}. A manual walk (not `readdirSync`'s
+ * `recursive`) so a huge `node_modules` is never read.
+ */
+const walk = (
+  root: string,
+): ReadonlyArray<string> => {
+  let entries;
+  try {
+    entries = readdirSync(root, {
+      withFileTypes: true,
+    });
+  } catch {
+    return [];
+  }
+  return entries.flatMap((entry) => {
+    const abs = join(root, entry.name);
+    if (entry.isDirectory()) {
+      return SKIP_DIRS.includes(entry.name)
+        ? []
+        : walk(abs);
+    }
+    return entry.isFile() &&
+      SOURCE_EXT.some((e) =>
+        entry.name.endsWith(e),
+      )
+      ? [abs]
+      : [];
+  });
+};
+
+/** The resolved local edges a single file imports. */
+const edgesOf = (
+  file: string,
+  aliases: ReadonlyArray<Alias>,
+): ReadonlyArray<{ from: string; to: string }> => {
+  const source = read(file);
+  if (source === null) {
+    return [];
+  }
+  return parseImports(source).flatMap((spec) => {
+    const to = resolveLocal(file, spec, aliases);
+    return to === null
+      ? []
+      : [{ from: file, to }];
+  });
+};
+
+/** Read a file, or null when it cannot be read. */
+const read = (file: string): string | null => {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Resolve a specifier to an absolute local file, or null
+ * for a package / `node:` specifier. Handles relative
+ * paths and every alias rule (`prefix` / `prefix/…`); tries
+ * the path itself, `.ts`, and `/index.ts`.
+ */
+const resolveLocal = (
+  from: string,
+  spec: string,
+  aliases: ReadonlyArray<Alias>,
+): string | null => {
+  const base = baseOf(from, spec, aliases);
+  if (base === null) {
+    return null;
+  }
+  const candidates = [
+    base,
+    `${base}.ts`,
+    join(base, "index.ts"),
+  ];
+  // A FILE, never a directory: a bare `<prefix>` base is
+  // the src dir (which exists) — prefer its `index.ts`.
+  return (
+    candidates.find(isFile) ?? null
+  );
+};
+
+/** Whether a path exists and is a regular file. */
+const isFile = (path: string): boolean => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/** The pre-extension base path a specifier points at. */
+const baseOf = (
+  from: string,
+  spec: string,
+  aliases: ReadonlyArray<Alias>,
+): string | null => {
+  if (
+    spec.startsWith("./") ||
+    spec.startsWith("../")
+  ) {
+    return resolve(dirname(from), spec);
+  }
+  for (const alias of aliases) {
+    if (spec === alias.prefix) {
+      return alias.srcDir;
+    }
+    if (spec.startsWith(`${alias.prefix}/`)) {
+      return join(
+        alias.srcDir,
+        spec.slice(alias.prefix.length + 1),
+      );
+    }
+  }
+  return null;
+};

package/src/Dev/node/watch.ts

@@ -0,0 +1,54 @@
+import { watch, type FSWatcher } from "node:fs";
+
+// The fs.watch seam: a debounced, recursive watcher over
+// several source roots. One save can emit multiple events,
+// so an imperative timer coalesces them onto a single
+// `onChange(path)`. Kept in `Dev/node/` (effectful,
+// excluded from the coverage threshold) — the pure reload
+// decision it feeds is unit-tested separately.
+
+/** fs.watch debounce window in ms. */
+const DEBOUNCE_MS = 80;
+
+/**
+ * Watch each root recursively; coalesce bursts onto a
+ * single `onChange` carrying the last changed filename.
+ * Returns the watchers so the caller owns their lifecycle.
+ * A root that cannot be watched is skipped rather than
+ * crashing the dev loop.
+ */
+export const watchRoots = (
+  roots: ReadonlyArray<string>,
+  onChange: (filename: string) => void,
+): ReadonlyArray<FSWatcher> => {
+  // Debounce seam: one shared timer + the latest filename
+  // across all roots.
+  let pending:
+    | ReturnType<typeof setTimeout>
+    | undefined;
+  let latest = "";
+  const fire = (filename: string): void => {
+    latest = filename;
+    clearTimeout(pending);
+    pending = setTimeout((): void => {
+      onChange(latest);
+    }, DEBOUNCE_MS);
+  };
+  return roots.flatMap((root) => {
+    try {
+      return [
+        watch(
+          root,
+          { recursive: true },
+          (_event, filename): void => {
+            if (filename !== null) {
+              fire(filename);
+            }
+          },
+        ),
+      ];
+    } catch {
+      return [];
+    }
+  });
+};

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

@@ -0,0 +1,50 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import {
+  hostName,
+  isAllowedHost,
+} from "plgg-bundle/Dev/usecase/allowedHost";
+
+test("hostName strips a :port suffix", () =>
+  all([
+    check(
+      hostName("localhost:5181"),
+      toBe("localhost"),
+    ),
+    check(
+      hostName("plgg-guide.qmu.dev"),
+      toBe("plgg-guide.qmu.dev"),
+    ),
+  ]));
+
+test("isAllowedHost accepts loopback by default", () =>
+  all([
+    check(
+      isAllowedHost([])("localhost:5181"),
+      toBe(true),
+    ),
+    check(
+      isAllowedHost([])("127.0.0.1:5181"),
+      toBe(true),
+    ),
+  ]));
+
+test("isAllowedHost accepts a config-supplied tunnel host", () =>
+  check(
+    isAllowedHost(["plgg-guide.qmu.dev"])(
+      "plgg-guide.qmu.dev",
+    ),
+    toBe(true),
+  ));
+
+test("isAllowedHost refuses an unlisted host", () =>
+  check(
+    isAllowedHost(["plgg-guide.qmu.dev"])(
+      "evil.example.com",
+    ),
+    toBe(false),
+  ));

package/src/Dev/usecase/allowedHost.ts

@@ -0,0 +1,39 @@
+/**
+ * Hosts the dev server always accepts, on top of the
+ * config-supplied allowlist. Loopback is implicit so local
+ * development needs no configuration.
+ */
+const DEFAULT_HOSTS: ReadonlyArray<string> = [
+  "localhost",
+  "127.0.0.1",
+];
+
+/**
+ * The bare host name (any `:port` suffix stripped) of a
+ * `Host`-header value. A value with no colon is returned
+ * unchanged. `indexOf`/`slice` (not `split(":")[0]`) so
+ * there is no unreachable `undefined` case to branch on.
+ */
+export const hostName = (
+  host: string,
+): string => {
+  const colon = host.indexOf(":");
+  return colon === -1
+    ? host
+    : host.slice(0, colon);
+};
+
+/**
+ * The Host allowlist check (data-last): loopback plus the
+ * config-supplied `allowedHosts`. Reproduces the tunnel
+ * safety plggpress's dev server gave — the guide adds its
+ * `*.qmu.dev` tunnel host so the Cloudflare tunnel is
+ * accepted while arbitrary Host headers are refused.
+ */
+export const isAllowedHost =
+  (allowedHosts: ReadonlyArray<string>) =>
+  (host: string): boolean =>
+    [
+      ...DEFAULT_HOSTS,
+      ...allowedHosts,
+    ].includes(hostName(host));

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

@@ -0,0 +1,30 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+  toEqual,
+} from "plgg-test";
+import { buildGraph } from "plgg-bundle/Dev/usecase/buildGraph";
+
+test("buildGraph folds edges into a file → imports map", () => {
+  const graph = buildGraph([
+    { from: "/a.ts", to: "/b.ts" },
+    { from: "/a.ts", to: "/c.ts" },
+    { from: "/b.ts", to: "/c.ts" },
+  ]);
+  return all([
+    check(graph.size, toBe(2)),
+    check(
+      graph.get("/a.ts"),
+      toEqual(["/b.ts", "/c.ts"]),
+    ),
+    check(
+      graph.get("/b.ts"),
+      toEqual(["/c.ts"]),
+    ),
+  ]);
+});
+
+test("buildGraph yields an empty graph for no edges", () =>
+  check(buildGraph([]).size, toBe(0)));

package/src/Dev/usecase/buildGraph.ts

@@ -0,0 +1,31 @@
+import {
+  type Edge,
+  type ModuleGraph,
+} from "plgg-bundle/Dev/model/ModuleGraph";
+
+/**
+ * Fold a flat list of resolved import {@link Edge}s into a
+ * {@link ModuleGraph} (file → the local files it imports).
+ * Pure: the adapter does the effectful scan+resolve and
+ * hands the edges here. A file that imports nothing local
+ * still appears as a node (empty array) as soon as it is
+ * an edge's `from`, so the reload decision can tell "known
+ * module" from "unrelated file".
+ */
+export const buildGraph = (
+  edges: ReadonlyArray<Edge>,
+): ModuleGraph => {
+  const graph = new Map<
+    string,
+    Array<string>
+  >();
+  for (const { from, to } of edges) {
+    const existing = graph.get(from);
+    if (existing === undefined) {
+      graph.set(from, [to]);
+    } else {
+      existing.push(to);
+    }
+  }
+  return graph;
+};

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

@@ -0,0 +1,39 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { decorateDevHtml } from "plgg-bundle/Dev/usecase/decorateDevHtml";
+import { LIVE_RELOAD_SCRIPT } from "plgg-bundle/Dev/model/Protocol";
+
+test("decorateDevHtml injects the reload script before </body>", () => {
+  const out = decorateDevHtml(
+    "<html><body><h1>hi</h1></body></html>",
+  );
+  return all([
+    check(
+      out.includes(LIVE_RELOAD_SCRIPT),
+      toBe(true),
+    ),
+    check(
+      out.indexOf(LIVE_RELOAD_SCRIPT) <
+        out.indexOf("</body>"),
+      toBe(true),
+    ),
+  ]);
+});
+
+test("decorateDevHtml appends to a document with no </body>", () => {
+  const out = decorateDevHtml("<h1>bare</h1>");
+  return all([
+    check(
+      out.startsWith("<h1>bare</h1>"),
+      toBe(true),
+    ),
+    check(
+      out.endsWith(LIVE_RELOAD_SCRIPT),
+      toBe(true),
+    ),
+  ]);
+});

package/src/Dev/usecase/decorateDevHtml.ts

@@ -0,0 +1,21 @@
+import { LIVE_RELOAD_SCRIPT } from "plgg-bundle/Dev/model/Protocol";
+
+/**
+ * The DEV-ONLY HTML decoration: string-append the
+ * {@link LIVE_RELOAD_SCRIPT} just before `</body>` (or at
+ * the very end when the document has none). Pure string
+ * surgery on rendered HTML OUTPUT — never inside a typed
+ * render tree (which would escape the `<script>`), and
+ * never in a production build path. This is the plgg-free
+ * toolchain counterpart to plggpress's old
+ * `decorateDevHtml`.
+ */
+export const decorateDevHtml = (
+  html: string,
+): string =>
+  html.includes("</body>")
+    ? html.replace(
+        "</body>",
+        `${LIVE_RELOAD_SCRIPT}</body>`,
+      )
+    : html + LIVE_RELOAD_SCRIPT;

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

@@ -0,0 +1,88 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { buildGraph } from "plgg-bundle/Dev/usecase/buildGraph";
+import { transitiveImporters } from "plgg-bundle/Dev/usecase/invalidate";
+
+/** A imports B; editing B must re-evaluate A (and B). */
+test("transitiveImporters: A imports B ⇒ invalidate(B) = {A, B}", () => {
+  const graph = buildGraph([
+    { from: "/a.ts", to: "/b.ts" },
+  ]);
+  const set = transitiveImporters(
+    graph,
+    "/b.ts",
+  );
+  return all([
+    check(set.has("/a.ts"), toBe(true)),
+    check(set.has("/b.ts"), toBe(true)),
+    check(set.size, toBe(2)),
+  ]);
+});
+
+/** Deep chain A→B→C: editing C invalidates the whole chain. */
+test("transitiveImporters walks a transitive chain A→B→C", () => {
+  const graph = buildGraph([
+    { from: "/a.ts", to: "/b.ts" },
+    { from: "/b.ts", to: "/c.ts" },
+  ]);
+  const set = transitiveImporters(
+    graph,
+    "/c.ts",
+  );
+  return all([
+    check(set.has("/a.ts"), toBe(true)),
+    check(set.has("/b.ts"), toBe(true)),
+    check(set.has("/c.ts"), toBe(true)),
+    check(set.size, toBe(3)),
+  ]);
+});
+
+/** A leaf's editor invalidates only itself. */
+test("transitiveImporters of a root importer is just itself", () => {
+  const graph = buildGraph([
+    { from: "/a.ts", to: "/b.ts" },
+  ]);
+  const set = transitiveImporters(
+    graph,
+    "/a.ts",
+  );
+  return all([
+    check(set.has("/a.ts"), toBe(true)),
+    check(set.size, toBe(1)),
+  ]);
+});
+
+/** Two importers of one leaf: editing C invalidates both A and B. */
+test("transitiveImporters collects multiple importers of one file", () => {
+  const graph = buildGraph([
+    { from: "/a.ts", to: "/c.ts" },
+    { from: "/b.ts", to: "/c.ts" },
+  ]);
+  const set = transitiveImporters(
+    graph,
+    "/c.ts",
+  );
+  return all([
+    check(set.has("/a.ts"), toBe(true)),
+    check(set.has("/b.ts"), toBe(true)),
+    check(set.has("/c.ts"), toBe(true)),
+    check(set.size, toBe(3)),
+  ]);
+});
+
+/** A cycle (A↔B) terminates and includes both. */
+test("transitiveImporters is cycle-safe", () => {
+  const graph = buildGraph([
+    { from: "/a.ts", to: "/b.ts" },
+    { from: "/b.ts", to: "/a.ts" },
+  ]);
+  const set = transitiveImporters(
+    graph,
+    "/a.ts",
+  );
+  return check(set.size, toBe(2));
+});

package/src/Dev/usecase/invalidate.ts

@@ -0,0 +1,67 @@
+import { type ModuleGraph } from "plgg-bundle/Dev/model/ModuleGraph";
+
+/**
+ * The invalidation set for a changed file: the file itself
+ * plus every module that transitively imports it (its
+ * reverse-reachable closure in the {@link ModuleGraph}).
+ * These are exactly the modules a cache-busted re-import
+ * must re-evaluate for the edit to take effect — a change
+ * to a deep leaf `B` invalidates every `A` that imports it
+ * (directly or through a chain).
+ *
+ * Pure graph walk over reversed edges; cycle-safe via the
+ * visited set. This is the "transitive invalidation" the
+ * ticket flags as the hard part, isolated here as testable
+ * logic (A imports B; invalidate(B) ⊇ {A, B}).
+ */
+export const transitiveImporters = (
+  graph: ModuleGraph,
+  changed: string,
+): ReadonlySet<string> => {
+  const importers = reverseEdges(graph);
+  const seen = new Set<string>([changed]);
+  // Breadth-first by layers: `for...of` over each frontier
+  // yields a `string` directly (no indexed access, no
+  // `.shift()` undefined case), keeping the walk `as`-free.
+  let frontier: ReadonlyArray<string> = [changed];
+  while (frontier.length > 0) {
+    const next: Array<string> = [];
+    for (const node of frontier) {
+      for (const importer of importers.get(
+        node,
+      ) ?? []) {
+        if (!seen.has(importer)) {
+          seen.add(importer);
+          next.push(importer);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return seen;
+};
+
+/**
+ * Invert the graph: for each `from → to` forward edge,
+ * record `to → from` so a lookup answers "who imports
+ * this file". Local helper for {@link transitiveImporters}.
+ */
+const reverseEdges = (
+  graph: ModuleGraph,
+): ReadonlyMap<string, ReadonlyArray<string>> => {
+  const reversed = new Map<
+    string,
+    Array<string>
+  >();
+  for (const [from, tos] of graph) {
+    for (const to of tos) {
+      const existing = reversed.get(to);
+      if (existing === undefined) {
+        reversed.set(to, [from]);
+      } else {
+        existing.push(from);
+      }
+    }
+  }
+  return reversed;
+};

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

@@ -0,0 +1,58 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+  toEqual,
+} from "plgg-test";
+import { parseImports } from "plgg-bundle/Dev/usecase/parseImports";
+
+test("parseImports reads static import + re-export + dynamic forms", () =>
+  check(
+    parseImports(
+      [
+        `import { a } from "./a.ts";`,
+        `import b from './b';`,
+        `export { c } from "./c.ts";`,
+        `const d = await import("./d.ts");`,
+        `export * from "./e";`,
+      ].join("\n"),
+    ),
+    toEqual([
+      // `from "…"` matches (import/export/re-export) come
+      // first, then the dynamic `import("…")` pass.
+      "./a.ts",
+      "./b",
+      "./c.ts",
+      "./e",
+      "./d.ts",
+    ]),
+  ));
+
+test("parseImports returns empty for a source with no imports", () =>
+  check(
+    parseImports(
+      "export const x = 1;\n",
+    ).length,
+    toBe(0),
+  ));
+
+test("parseImports captures bare package + node specifiers too (adapter filters locality)", () =>
+  check(
+    parseImports(
+      `import { x } from "node:fs";\nimport y from "some-pkg";`,
+    ),
+    toEqual(["node:fs", "some-pkg"]),
+  ));
+
+test("parseImports handles single and double quotes", () =>
+  all([
+    check(
+      parseImports(`import("./x.ts")`),
+      toEqual(["./x.ts"]),
+    ),
+    check(
+      parseImports(`import('./y.ts')`),
+      toEqual(["./y.ts"]),
+    ),
+  ]));