plgg-bundle 0.0.1

package/src/domain/usecase/resolveSpecifier.ts

@@ -0,0 +1,127 @@
+import { existsSync, statSync } from "node:fs";
+import {
+  dirname,
+  resolve,
+  join,
+} from "node:path";
+
+/**
+ * Resolve a bare import specifier to an absolute source
+ * file path, given the importing file and the
+ * package-self-alias mapping. Pure resolution logic —
+ * it only consults the filesystem to pick between
+ * `X.ts` and `X/index.ts`, mirroring how the alias +
+ * relative imports across the plgg packages resolve
+ * under `tsc`.
+ *
+ * Returns `undefined` when the specifier is external
+ * (not the self-alias and not relative) or cannot be
+ * found on disk — the caller decides whether that means
+ * "external, leave it" or "broken import, fail".
+ */
+export const resolveSpecifier = (args: {
+  specifier: string;
+  fromFile: string;
+  aliasPrefix: string;
+  aliasSrcRoot: string;
+}): string | undefined => {
+  if (isRelative(args.specifier)) {
+    return pickExisting(
+      resolve(
+        dirname(args.fromFile),
+        args.specifier,
+      ),
+    );
+  }
+  const base = aliasTarget(args);
+  return base === undefined
+    ? undefined
+    : pickExisting(base);
+};
+
+/**
+ * Whether the specifier is a relative path (`./` or
+ * `../`). Exported for the app-mode workspace resolver,
+ * which shares this relative-import handling.
+ */
+export const isRelative = (
+  specifier: string,
+): boolean =>
+  specifier.startsWith("./") ||
+  specifier.startsWith("../");
+
+/**
+ * Map a self-alias specifier (`<prefix>` or
+ * `<prefix>/sub/path`) to its base path under the
+ * source root. A non-alias specifier yields `undefined`
+ * (it is external).
+ */
+const aliasTarget = (args: {
+  specifier: string;
+  aliasPrefix: string;
+  aliasSrcRoot: string;
+}): string | undefined =>
+  args.specifier === args.aliasPrefix
+    ? args.aliasSrcRoot
+    : args.specifier.startsWith(
+          `${args.aliasPrefix}/`,
+        )
+      ? join(
+          args.aliasSrcRoot,
+          args.specifier.slice(
+            args.aliasPrefix.length + 1,
+          ),
+        )
+      : undefined;
+
+/**
+ * Given a base path with no extension, pick the
+ * existing source file: the path as-is, then `base.ts`,
+ * then `base/index.ts`. Exported so the app-mode
+ * workspace resolver picks sibling source files the same
+ * way.
+ */
+export const pickExisting = (
+  base: string,
+): string | undefined =>
+  candidates(base).find(isFile);
+
+/**
+ * Whether a path exists and is a regular file (not a
+ * directory). A bare `plgg/Abstracts` base resolves to
+ * the `Abstracts/` directory, which must be skipped in
+ * favor of `Abstracts/index.ts`.
+ */
+const isFile = (p: string): boolean =>
+  existsSync(p) && statSync(p).isFile();
+
+/**
+ * The ordered candidate file paths for a base path. A
+ * `.js`/`.mjs`/`.jsx` specifier is the NodeNext/ESM way
+ * to reference a TypeScript sibling (`./X.js` → `X.ts`),
+ * so its `.ts`/`.mts`/`.tsx` form is tried first.
+ */
+const candidates = (
+  base: string,
+): ReadonlyArray<string> => [
+  ...tsForJs(base),
+  base,
+  `${base}.ts`,
+  join(base, "index.ts"),
+];
+
+/**
+ * The TypeScript-source path implied by a JS-extension
+ * specifier, or nothing if `base` carries no such
+ * extension.
+ */
+const tsForJs = (
+  base: string,
+): ReadonlyArray<string> =>
+  base.endsWith(".js")
+    ? [`${base.slice(0, -3)}.ts`]
+    : base.endsWith(".mjs")
+      ? [`${base.slice(0, -4)}.mts`]
+      : base.endsWith(".jsx")
+        ? [`${base.slice(0, -4)}.tsx`]
+        : [];

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

@@ -0,0 +1,79 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { join } from "node:path";
+import { discoverWorkspace } from "plgg-bundle/domain/usecase/discoverWorkspace";
+import { resolveWorkspaceSpecifier } from "plgg-bundle/domain/usecase/resolveWorkspaceSpecifier";
+
+const bundleRoot = join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "..",
+);
+const packagesDir = join(bundleRoot, "..");
+const packages = discoverWorkspace(bundleRoot);
+
+// Any file standing in for the importer.
+const fromFile = join(
+  packagesDir,
+  "example",
+  "src",
+  "app.ts",
+);
+const resolve = (specifier: string) =>
+  resolveWorkspaceSpecifier({
+    specifier,
+    fromFile,
+    packages,
+  });
+const pkgSrc = (
+  name: string,
+  ...rest: ReadonlyArray<string>
+) => join(packagesDir, name, "src", ...rest);
+
+test("resolves a bare workspace package to its src index", () =>
+  check(
+    resolve("plgg"),
+    toBe(pkgSrc("plgg", "index.ts")),
+  ));
+
+test("resolves a public export subpath, honouring the styleEntry rename", () =>
+  all([
+    check(
+      resolve("plgg-view/client"),
+      toBe(pkgSrc("plgg-view", "client.ts")),
+    ),
+    check(
+      resolve("plgg-view/style"),
+      toBe(pkgSrc("plgg-view", "styleEntry.ts")),
+    ),
+  ]));
+
+test("resolves an internal self-alias path (not a declared export)", () =>
+  check(
+    resolve("plgg/Atomics/Num"),
+    toBe(pkgSrc("plgg", "Atomics", "Num.ts")),
+  ));
+
+test("resolves a relative import against the importer", () =>
+  check(
+    resolve("./Todo.ts"),
+    toBe(
+      join(
+        packagesDir,
+        "example",
+        "src",
+        "Todo.ts",
+      ),
+    ),
+  ));
+
+test("returns undefined for a non-workspace specifier", () =>
+  all([
+    check(resolve("react"), toBe(undefined)),
+    check(resolve("node:fs"), toBe(undefined)),
+  ]));

package/src/domain/usecase/resolveWorkspaceSpecifier.ts

@@ -0,0 +1,120 @@
+import { basename, join } from "node:path";
+import {
+  resolveSpecifier,
+  isRelative,
+  pickExisting,
+} from "plgg-bundle/domain/usecase/resolveSpecifier";
+import { type WorkspacePackage } from "plgg-bundle/domain/usecase/discoverWorkspace";
+
+/**
+ * App-mode resolver: resolve an import specifier to an
+ * absolute SOURCE file, inlining workspace siblings
+ * (`plgg`, `plgg-view/client`, …) by walking their `src`
+ * instead of leaving them external. This is the mirror of
+ * the library externalization — the leaf app is where
+ * bundling deps is correct.
+ *
+ * Order:
+ * 1. relative (`./x`) → resolve against the importer,
+ * 2. a workspace package's PUBLIC export subpath
+ *    (`plgg-view/style`) → reverse its declared
+ *    `exports` dist path to the entry source (honours the
+ *    `styleEntry` rename),
+ * 3. a workspace package's INTERNAL self-alias path
+ *    (`plgg-view/Html/x`, and `plgg` → its `src/index`)
+ *    → `src/<path>`.
+ *
+ * Returns `undefined` when the specifier is neither
+ * relative nor a known workspace package (the caller
+ * treats that as external or a hard error).
+ */
+export const resolveWorkspaceSpecifier = (args: {
+  specifier: string;
+  fromFile: string;
+  packages: ReadonlyArray<WorkspacePackage>;
+}): string | undefined => {
+  if (isRelative(args.specifier)) {
+    return resolveSpecifier({
+      specifier: args.specifier,
+      fromFile: args.fromFile,
+      aliasPrefix: NO_ALIAS,
+      aliasSrcRoot: "",
+    });
+  }
+  const pkg = matchPackage(
+    args.packages,
+    args.specifier,
+  );
+  return pkg === undefined
+    ? undefined
+    : resolveInPackage(pkg, args.specifier);
+};
+
+/**
+ * A sentinel alias prefix no specifier equals, so the
+ * shared `resolveSpecifier` handles only the relative
+ * branch when reused for relative imports.
+ */
+const NO_ALIAS = "\0";
+
+/**
+ * The workspace package whose name is the specifier or a
+ * leading `name/` segment. The package list is sorted
+ * longest-name-first, so the first match is the most
+ * specific (`plgg-view` before `plgg`).
+ */
+const matchPackage = (
+  packages: ReadonlyArray<WorkspacePackage>,
+  specifier: string,
+): WorkspacePackage | undefined =>
+  packages.find(
+    (p) =>
+      specifier === p.name ||
+      specifier.startsWith(`${p.name}/`),
+  );
+
+/**
+ * Resolve a specifier already known to belong to `pkg`:
+ * a declared export subpath via the exports reversal,
+ * else the internal self-alias path.
+ */
+const resolveInPackage = (
+  pkg: WorkspacePackage,
+  specifier: string,
+): string | undefined => {
+  const subpath =
+    specifier === pkg.name
+      ? "."
+      : `./${specifier.slice(
+          pkg.name.length + 1,
+        )}`;
+  const dist = pkg.exports.get(subpath);
+  return dist === undefined
+    ? resolveSpecifier({
+        specifier,
+        fromFile: pkg.dir,
+        aliasPrefix: pkg.name,
+        aliasSrcRoot: join(pkg.dir, "src"),
+      })
+    : pickExisting(
+        join(pkg.dir, "src", srcStem(dist)),
+      );
+};
+
+/**
+ * The source stem implied by an export's dist default —
+ * `"./dist/styleEntry.es.js"` → `"styleEntry"`. The entry
+ * output basename equals the entry name, which equals the
+ * source file stem under `src/`, so stripping the dual
+ * `.es.js`/`.cjs.js` (or bare `.js`) suffix recovers it.
+ *
+ * ASSUMES top-level entry stems: `basename` drops any
+ * directory, so an export pointing at a NESTED dist path
+ * (`./dist/sub/foo.es.js`) would reverse to `src/foo` and
+ * lose `sub/`. No package nests an export entry today, so
+ * this is correct now; revisit if one ever does.
+ */
+const srcStem = (distDefault: string): string =>
+  basename(distDefault)
+    .replace(/\.(es|cjs)\.js$/, "")
+    .replace(/\.js$/, "");

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

@@ -0,0 +1,123 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import { join } from "node:path";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import {
+  rewriteDtsAliases,
+  rewriteDtsContent,
+} from "plgg-bundle/domain/usecase/rewriteDtsAliases";
+
+const distDir = "/pkg/dist";
+// A declaration two levels deep, so a rewrite to a
+// top-level sibling is a `../../` path.
+const file = join(
+  distDir,
+  "Disjunctives",
+  "Result.d.ts",
+);
+
+test("rewriteDtsContent relativizes an alias in `from` position", () =>
+  check(
+    rewriteDtsContent(
+      file,
+      `import { Ok } from "plgg/index";`,
+      distDir,
+      "plgg",
+    ),
+    toBe(`import { Ok } from "../index";`),
+  ));
+
+test("rewriteDtsContent relativizes a re-export and an inline import()", () =>
+  all([
+    check(
+      rewriteDtsContent(
+        join(distDir, "index.d.ts"),
+        `export * from "plgg/Atomics";`,
+        distDir,
+        "plgg",
+      ),
+      toBe(`export * from "./Atomics";`),
+    ),
+    check(
+      rewriteDtsContent(
+        join(distDir, "index.d.ts"),
+        `export type T = import("plgg/Atomics/Num").Num;`,
+        distDir,
+        "plgg",
+      ),
+      toBe(
+        `export type T = import("./Atomics/Num").Num;`,
+      ),
+    ),
+  ]));
+
+test("rewriteDtsContent leaves a literal-type string untouched (gap #7)", () =>
+  // A string-literal type that merely looks like an
+  // alias must NOT be rewritten — it is not an
+  // import/export specifier position.
+  check(
+    rewriteDtsContent(
+      join(distDir, "index.d.ts"),
+      `export type Tag = "plgg/not-a-module";`,
+      distDir,
+      "plgg",
+    ),
+    toBe(
+      `export type Tag = "plgg/not-a-module";`,
+    ),
+  ));
+
+test("rewriteDtsAliases rewrites aliases across a nested dist tree in place", () => {
+  const dist = mkdtempSync(
+    join(tmpdir(), "plgg-dts-"),
+  );
+  mkdirSync(join(dist, "Sub"));
+  writeFileSync(
+    join(dist, "index.d.ts"),
+    `export * from "plgg/Sub/x";`,
+  );
+  writeFileSync(
+    join(dist, "Sub", "x.d.ts"),
+    `import { Y } from "plgg/index";`,
+  );
+  // A non-.d.ts sibling must be skipped by the walk.
+  writeFileSync(
+    join(dist, "notes.txt"),
+    `plgg/index (not a declaration)`,
+  );
+  rewriteDtsAliases(dist, "plgg");
+  return all([
+    check(
+      readFileSync(
+        join(dist, "index.d.ts"),
+        "utf8",
+      ),
+      toBe(`export * from "./Sub/x";`),
+    ),
+    check(
+      readFileSync(
+        join(dist, "Sub", "x.d.ts"),
+        "utf8",
+      ),
+      toBe(`import { Y } from "../index";`),
+    ),
+    // Untouched: not a declaration file.
+    check(
+      readFileSync(
+        join(dist, "notes.txt"),
+        "utf8",
+      ),
+      toBe(`plgg/index (not a declaration)`),
+    ),
+  ]);
+});

package/src/domain/usecase/rewriteDtsAliases.ts

@@ -0,0 +1,133 @@
+import {
+  readdirSync,
+  statSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import {
+  join,
+  dirname,
+  relative,
+} from "node:path";
+
+/**
+ * Rewrite the package self-alias (`<prefix>/<sub>`) in
+ * every emitted `.d.ts` under `distDir` to a path
+ * relative to the importing declaration file — the same
+ * transform vite-plugin-dts applied. `tsc` leaves
+ * `tsconfig` `paths` aliases verbatim in declaration
+ * output, so without this pass a consumer (who has no
+ * `plgg/*` alias) cannot resolve `from "plgg/Atomics"`.
+ *
+ * Because `dist` mirrors `src` and the alias maps
+ * `<prefix>/*` → `src/*`, `<prefix>/<sub>` from
+ * `dist/A/B.d.ts` resolves to `dist/<sub>`, i.e. the
+ * relative path from `dist/A` to `dist/<sub>`.
+ */
+export const rewriteDtsAliases = (
+  distDir: string,
+  aliasPrefix: string,
+): void => {
+  // fs walk seam: visit every emitted declaration and
+  // relativize its alias imports in place.
+  for (const file of dtsFiles(distDir)) {
+    const rewritten = rewriteDtsContent(
+      file,
+      readFileSync(file, "utf8"),
+      distDir,
+      aliasPrefix,
+    );
+    writeFileSync(file, rewritten, "utf8");
+  }
+};
+
+/**
+ * Rewrite a single declaration file's alias specifiers
+ * (pure string transform, exposed for unit testing). The
+ * match is ANCHORED to import/export specifier positions
+ * — preceded by `from ` or `import(` — so a literal
+ * string-type value like `type T = "plgg/x"` in a
+ * `.d.ts` is left untouched (gap #7).
+ */
+export const rewriteDtsContent = (
+  file: string,
+  content: string,
+  distDir: string,
+  aliasPrefix: string,
+): string =>
+  content.replace(
+    aliasPattern(aliasPrefix),
+    (
+      _match,
+      lead: string,
+      quote: string,
+      sub: string,
+    ) =>
+      `${lead}${quote}${toRelative(
+        file,
+        distDir,
+        sub,
+      )}${quote}`,
+  );
+
+/**
+ * A specifier-matching regex for `<prefix>/<sub>` only
+ * in an import/export specifier position: immediately
+ * after `from ` or `import(`. Captures the lead, the
+ * quote, and the sub-path. The prefix is escaped so a
+ * regex-special character in a package name is literal.
+ */
+const aliasPattern = (
+  aliasPrefix: string,
+): RegExp =>
+  new RegExp(
+    `(from\\s+|import\\s*\\()(["'])${escapeRegExp(
+      aliasPrefix,
+    )}\\/([^"']+)\\2`,
+    "g",
+  );
+
+/**
+ * The relative specifier from a declaration file to the
+ * aliased sub-module's location in `dist`, POSIX-style
+ * and `./`-prefixed when in the same/!-parent dir.
+ */
+const toRelative = (
+  file: string,
+  distDir: string,
+  sub: string,
+): string =>
+  dotted(
+    relative(dirname(file), join(distDir, sub))
+      .split("\\")
+      .join("/"),
+  );
+
+/**
+ * Ensure a relative path is import-specifier shaped:
+ * a same-or-child path gets a leading `./`; a `../`
+ * path already is.
+ */
+const dotted = (rel: string): string =>
+  rel.startsWith(".") ? rel : `./${rel}`;
+
+/**
+ * Escape regex metacharacters in a literal string.
+ */
+const escapeRegExp = (s: string): string =>
+  s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * All `.d.ts` files under a directory, recursively.
+ */
+const dtsFiles = (
+  dir: string,
+): ReadonlyArray<string> =>
+  readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name);
+    return statSync(p).isDirectory()
+      ? dtsFiles(p)
+      : p.endsWith(".d.ts")
+        ? [p]
+        : [];
+  });

package/src/entrypoints/cli.ts

@@ -0,0 +1,105 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+import { type BundleConfig } from "plgg-bundle/domain/model/BundleConfig";
+import { asBundleConfig } from "plgg-bundle/domain/usecase/asBundleConfig";
+import { build } from "plgg-bundle/domain/usecase/build";
+import { runDevServer } from "plgg-bundle/Dev/node/devServer";
+
+/**
+ * CLI entry with two modes:
+ *
+ *  - `plgg-bundle [config]` — the one-shot build (default):
+ *    validate the config and emit the bundle.
+ *  - `plgg-bundle dev [config]` — the dev server: serve the
+ *    config's dev entry over node:http, watch its source,
+ *    and hot-reload the browser on a code edit.
+ *
+ * The shell stays thin and is the single place a thrown
+ * error becomes a non-zero exit — the plain-TS counterpart
+ * to a `Result` edge. The `dev` server itself runs for the
+ * process lifetime (it never resolves).
+ */
+const main = async (): Promise<void> =>
+  process.argv[2] === "dev"
+    ? runDev(process.argv[3])
+    : runBuild(process.argv[2]);
+
+/** The one-shot build mode. */
+const runBuild = async (
+  arg: string | undefined,
+): Promise<void> => {
+  const config = await loadConfig(arg);
+  if (config === null) {
+    return;
+  }
+  const files = build(config);
+  process.stdout.write(
+    `plgg-bundle: wrote ${files.length} file(s) to ${config.outDir}\n`,
+  );
+};
+
+/** The dev-server mode. */
+const runDev = async (
+  arg: string | undefined,
+): Promise<void> => {
+  const config = await loadConfig(arg);
+  if (config === null) {
+    return;
+  }
+  const server = await runDevServer(config);
+  process.stdout.write(
+    `plgg-bundle: dev server at ${server.url}\n`,
+  );
+};
+
+/**
+ * Resolve, import (Node strips its types), and validate
+ * the bundle config, or set a non-zero exit and return
+ * null when it is missing. Shared by both modes.
+ */
+const loadConfig = async (
+  arg: string | undefined,
+): Promise<BundleConfig | null> => {
+  const configPath = resolve(
+    process.cwd(),
+    arg ?? "bundle.config.ts",
+  );
+  if (!existsSync(configPath)) {
+    fail(`config not found: ${configPath}`);
+    return null;
+  }
+  const mod: unknown = await import(
+    pathToFileURL(configPath).href
+  );
+  return asBundleConfig(pickDefault(mod));
+};
+
+/**
+ * Extract a module's `default` export as `unknown`,
+ * tolerating a module that is itself the config.
+ */
+const pickDefault = (mod: unknown): unknown =>
+  typeof mod === "object" &&
+  mod !== null &&
+  "default" in mod
+    ? mod.default
+    : mod;
+
+/**
+ * Print an error and set a non-zero exit code.
+ */
+const fail = (message: string): void => {
+  process.stderr.write(
+    `plgg-bundle: ${message}\n`,
+  );
+  process.exitCode = 1;
+};
+
+try {
+  await main();
+} catch (e) {
+  fail(
+    e instanceof Error ? e.message : String(e),
+  );
+}