@mongez/pkgist 1.0.0

package/src/compile/tsdown-compiler.ts

@@ -0,0 +1,344 @@
+import path from "path";
+import fs from "fs";
+import { build } from "tsdown";
+import type { InputOptions } from "rolldown";
+import type { PackageBase } from "../types/index.js";
+import { joinPath, toForwardSlash, resolvePath } from "../utils/paths.js";
+import { ensureDir, moveFile, listFiles, pathExists } from "../files/file-manager.js";
+import { wrapError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Collect all dependency names that should be treated as external.
+ * Both `dependencies` and `peerDependencies` must never be bundled.
+ */
+function collectExternals(sourceJson: Record<string, unknown>): string[] {
+  const deps = Object.keys((sourceJson["dependencies"] as Record<string, string> | undefined) ?? {});
+  const peers = Object.keys((sourceJson["peerDependencies"] as Record<string, string> | undefined) ?? {});
+  return [...new Set([...deps, ...peers])];
+}
+
+/**
+ * Resolve entry file paths to absolute forward-slash paths.
+ */
+function resolveEntries(pkg: PackageBase, packageRoot: string): string[] {
+  const srcDir = pkg.srcDir ?? "src";
+  const rawEntries = pkg.entries ?? ["index.ts"];
+  const entryList = Array.isArray(rawEntries) ? rawEntries : [rawEntries];
+  return entryList.map((e) => toForwardSlash(resolvePath(packageRoot, srcDir, e)));
+}
+
+/**
+ * Return the path to the tsconfig.json inside the package root, if it exists.
+ */
+function findTsconfig(packageRoot: string): string | undefined {
+  const local = joinPath(packageRoot, "tsconfig.json");
+  return pathExists(local) ? local : undefined;
+}
+
+// ─── Main compiler ──────────────────────────────────────────────────────────
+
+/**
+ * Compile a single package using tsdown.
+ *
+ * When `preserveModules` is on (the default), we run two separate tsdown builds
+ * in parallel so that each format's output options are fully independent:
+ *
+ *   ESM build  — preserveModules: true, dts: true  → _tmp_esm/  → esm/*.mjs + *.d.mts
+ *   CJS build  — preserveModules: false, dts: false → _tmp_cjs/  → cjs/*.cjs
+ *
+ * CJS skips DTS because rolldown has a bug in CJS preserveModules mode where
+ * `export { default as X }` assigns the whole module object to exports.X instead
+ * of unwrapping .default.  Bundled CJS has no such issue.  Types are shared from
+ * the ESM declarations (TypeScript resolves them correctly via the exports map).
+ *
+ * When `preserveModules` is false, a single combined build is used.
+ */
+export async function compilePackage(
+  pkg: PackageBase,
+  packageRoot: string,
+  buildPath: string,
+  sourceJson: Record<string, unknown>,
+  dryRun: boolean,
+): Promise<void> {
+  if (dryRun) {
+    logger.info(`[dry-run] compile ${pkg.name} → ${buildPath}`);
+    return;
+  }
+
+  const entries = resolveEntries(pkg, packageRoot);
+  const formats = pkg.formats ?? ["esm", "cjs"];
+  const externals = collectExternals(sourceJson);
+  const tsconfig = findTsconfig(packageRoot);
+  const shouldPreserveModules = pkg.preserveModules !== false;
+  const srcDir = toForwardSlash(resolvePath(packageRoot, pkg.srcDir ?? "src"));
+
+  logger.step(`Compiling ${pkg.name} (${formats.join(", ")}) → ${buildPath}`);
+  logger.debug(`  entries:   ${entries.join(", ")}`);
+  logger.debug(`  externals: ${externals.slice(0, 8).join(", ")}${externals.length > 8 ? "…" : ""}`);
+
+  // Wipe any previous esm/ and cjs/ output so re-runs of the same version don't
+  // leave stale files from a different build mode.
+  for (const subDir of ["esm", "cjs"]) {
+    const dir = resolvePath(buildPath, subDir);
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  // Build inputOptions for rolldown — used to set the JSX transform for React packages.
+  const rolldownInputOptions: InputOptions | undefined =
+    pkg.type === "react"
+      ? {
+          transform: {
+            jsx: "react-jsx", // automatic runtime — works with React 17+
+          },
+        }
+      : undefined;
+
+  // Common options shared across all tsdown invocations.
+  const sharedOptions = {
+    entry: entries,
+    deps: { neverBundle: externals },
+    sourcemap: pkg.sourcemap !== false,
+    clean: true,
+    minify: pkg.minify ?? false,
+    tsconfig: tsconfig ?? true,
+    ...(rolldownInputOptions ? { inputOptions: rolldownInputOptions } : {}),
+  } as const;
+
+  try {
+    if (shouldPreserveModules && formats.includes("esm") && formats.includes("cjs")) {
+      // Two parallel builds: ESM with preserveModules + DTS, CJS bundled without DTS.
+      const tmpEsm = toForwardSlash(resolvePath(buildPath, "_tmp_esm"));
+      const tmpCjs = toForwardSlash(resolvePath(buildPath, "_tmp_cjs"));
+      ensureDir(tmpEsm);
+      ensureDir(tmpCjs);
+
+      await Promise.all([
+        build({
+          ...sharedOptions,
+          format: ["esm"],
+          dts: pkg.dts !== false,
+          outDir: tmpEsm,
+          outputOptions: {
+            preserveModules: true,
+            preserveModulesRoot: srcDir,
+          },
+        }),
+        build({
+          ...sharedOptions,
+          format: ["cjs"],
+          // CJS skips DTS — types are served from ESM declarations (see package-json.ts).
+          dts: false,
+          outDir: tmpCjs,
+        }),
+      ]);
+
+      reorganiseOutput(tmpEsm, buildPath, ["esm"], pkg, true);
+      // keepNativeExtension=true: CJS files come out as .cjs from tsdown; we keep that
+      // extension so the exports map (./cjs/index.cjs) resolves correctly.
+      reorganiseOutput(tmpCjs, buildPath, ["cjs"], pkg, false, true);
+      rmTmp(tmpEsm);
+      rmTmp(tmpCjs);
+    } else {
+      // Single build: either one format only, or preserveModules disabled.
+      const tmpDir = toForwardSlash(resolvePath(buildPath, "_tmp"));
+      ensureDir(tmpDir);
+
+      await build({
+        ...sharedOptions,
+        format: formats as ("esm" | "cjs")[],
+        dts: pkg.dts !== false,
+        outDir: tmpDir,
+        ...(shouldPreserveModules && formats.includes("esm")
+          ? { outputOptions: { preserveModules: true, preserveModulesRoot: srcDir } }
+          : {}),
+      });
+
+      reorganiseOutput(tmpDir, buildPath, formats as ("esm" | "cjs")[], pkg, shouldPreserveModules);
+      rmTmp(tmpDir);
+    }
+  } catch (err) {
+    throw wrapError("tsdown-build", pkg.name, err);
+  }
+
+  logger.success(`Compiled ${pkg.name}`);
+}
+
+function rmTmp(dir: string): void {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // non-fatal — stale tmp is harmless
+  }
+}
+
+// ─── Output reorganisation ──────────────────────────────────────────────────
+
+/**
+ * Move the flat tsdown output (in tmpDir) into `esm/` and `cjs/` subdirectories
+ * under buildPath.  Renames .mjs → .js and .cjs → .js so that relative imports
+ * inside each format directory resolve correctly.
+ */
+function reorganiseOutput(
+  tmpDir: string,
+  buildPath: string,
+  formats: ("esm" | "cjs")[],
+  pkg: PackageBase,
+  preserveModules: boolean,
+  keepNativeExtension = false,
+): void {
+  const esmDir = joinPath(buildPath, "esm");
+  const cjsDir = joinPath(buildPath, "cjs");
+
+  if (formats.includes("esm")) ensureDir(esmDir);
+  if (formats.includes("cjs")) ensureDir(cjsDir);
+
+  const mainType = pkg.mainType ?? (formats.includes("cjs") ? "cjs" : "esm");
+
+  processDirectory(tmpDir, { esmDir, cjsDir, formats, mainType, pkg, tmpDir, preserveModules, keepNativeExtension });
+}
+
+interface ReorgContext {
+  esmDir: string;
+  cjsDir: string;
+  formats: ("esm" | "cjs")[];
+  mainType: "esm" | "cjs";
+  pkg: PackageBase;
+  /** Absolute path to the flat _tmp/ directory — used to compute relative paths when preserveModules is on. */
+  tmpDir: string;
+  preserveModules: boolean;
+  /**
+   * When true, keep the native .mjs/.cjs extensions instead of normalising to .js.
+   * Used in the CJS-only leg of the two-build path so the final file stays .cjs.
+   */
+  keepNativeExtension: boolean;
+}
+
+function processDirectory(dir: string, ctx: ReorgContext): void {
+  if (!fs.existsSync(dir)) return;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = joinPath(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Recursively handle subdirectories (chunk splits, etc.)
+      processDirectory(fullPath, ctx);
+    } else {
+      processFile(fullPath, entry.name, ctx);
+    }
+  }
+}
+
+function processFile(filePath: string, name: string, ctx: ReorgContext): void {
+  const { esmDir, cjsDir, formats, mainType, pkg, tmpDir, preserveModules } = ctx;
+
+  // Relative subdirectory from the tmp root — preserves folder structure for both
+  // preserveModules output and multi-entry single-bundle output (where each entry
+  // lands in its own subdirectory, e.g. cli/index.cjs).
+  // path.relative may return backslashes on Windows — normalise to forward slashes.
+  const relDir = toForwardSlash(path.relative(tmpDir, path.dirname(filePath)));
+
+  if (preserveModules) {
+    if (isEsmFile(name)) {
+      if (formats.includes("esm")) {
+        moveFile(filePath, joinPath(esmDir, relDir, name), pkg.name);
+      }
+    } else if (isCjsFile(name)) {
+      if (formats.includes("cjs")) {
+        moveFile(filePath, joinPath(cjsDir, relDir, name), pkg.name);
+      }
+    } else if (isDtsFile(name)) {
+      const targetDir = formats.includes("esm") ? esmDir : cjsDir;
+      moveFile(filePath, joinPath(targetDir, relDir, name), pkg.name);
+    }
+    // Unknown extensions silently ignored.
+    return;
+  }
+
+  // ── Single-bundle mode ──────────────────────────────────────────────────────
+  const { keepNativeExtension } = ctx;
+
+  if (isEsmFile(name)) {
+    if (formats.includes("esm")) {
+      const destName = keepNativeExtension ? name : normaliseEsmName(name);
+      moveFile(filePath, joinPath(esmDir, relDir, destName), pkg.name);
+    }
+  } else if (isCjsFile(name)) {
+    if (formats.includes("cjs")) {
+      const destName = keepNativeExtension ? name : normaliseCjsName(name);
+      moveFile(filePath, joinPath(cjsDir, relDir, destName), pkg.name);
+    }
+  } else if (isDtsFile(name)) {
+    const targetDir = formats.includes("esm") ? esmDir : cjsDir;
+    moveFile(filePath, joinPath(targetDir, relDir, name), pkg.name);
+  } else if (isJsFile(name)) {
+    // Plain .js / .js.map — emitted when the format array contains only one format
+    // (tsdown uses .js instead of .mjs/.cjs when there's no other format to differentiate from).
+    const targetDir = mainType === "esm" ? esmDir : cjsDir;
+    if (formats.includes(mainType)) {
+      // Files landing in cjsDir should use the .cjs extension for consistency.
+      const destName =
+        targetDir === cjsDir
+          ? name.replace(/\.js\.map$/, ".cjs.map").replace(/\.js$/, ".cjs")
+          : name;
+      moveFile(filePath, joinPath(targetDir, relDir, destName), pkg.name);
+    }
+  }
+  // Unknown extensions are silently ignored.
+}
+
+// ─── Extension predicates ───────────────────────────────────────────────────
+
+function isEsmFile(name: string): boolean {
+  return (
+    name.endsWith(".mjs") ||
+    name.endsWith(".mjs.map") ||
+    name.endsWith(".d.mts") ||
+    name.endsWith(".d.mts.map")
+  );
+}
+
+function isCjsFile(name: string): boolean {
+  return (
+    name.endsWith(".cjs") ||
+    name.endsWith(".cjs.map") ||
+    name.endsWith(".d.cts") ||
+    name.endsWith(".d.cts.map")
+  );
+}
+
+function isDtsFile(name: string): boolean {
+  return name.endsWith(".d.ts") || name.endsWith(".d.ts.map");
+}
+
+function isJsFile(name: string): boolean {
+  return (
+    (name.endsWith(".js") || name.endsWith(".js.map")) &&
+    !name.endsWith(".d.ts") &&
+    !name.endsWith(".d.ts.map")
+  );
+}
+
+// ─── Name normalisation ─────────────────────────────────────────────────────
+
+/** Rename .mjs / .d.mts → .js / .d.ts for the esm/ directory. */
+function normaliseEsmName(name: string): string {
+  return name
+    .replace(/\.mjs\.map$/, ".js.map")
+    .replace(/\.mjs$/, ".js")
+    .replace(/\.d\.mts\.map$/, ".d.ts.map")
+    .replace(/\.d\.mts$/, ".d.ts");
+}
+
+/** Rename .cjs / .d.cts → .js / .d.ts for the cjs/ directory. */
+function normaliseCjsName(name: string): string {
+  return name
+    .replace(/\.cjs\.map$/, ".js.map")
+    .replace(/\.cjs$/, ".js")
+    .replace(/\.d\.cts\.map$/, ".d.ts.map")
+    .replace(/\.d\.cts$/, ".d.ts");
+}

package/src/config/define-config.ts

@@ -0,0 +1,9 @@
+import type { BundlerConfig } from "../types/index.js";
+
+/**
+ * Type-safe config factory.
+ * Simply returns the config object unchanged — used purely for IDE autocomplete and type checking.
+ */
+export function defineConfig(config: BundlerConfig): BundlerConfig {
+  return config;
+}

package/src/config/index.ts

@@ -0,0 +1,3 @@
+export { defineConfig } from "./define-config.js";
+export { loadConfig, findDefaultConfigPath } from "./load-config.js";
+export type { LoadedConfig } from "./load-config.js";

package/src/config/load-config.ts

@@ -0,0 +1,103 @@
+import path from "path";
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
+import fs from "fs";
+import type { BundlerConfig } from "../types/index.js";
+import { resolvePath } from "../utils/paths.js";
+import { wrapError } from "../utils/errors.js";
+
+export interface LoadedConfig {
+  config: BundlerConfig;
+  /** Absolute, forward-slash normalised path to the config file */
+  configPath: string;
+  /** Directory containing the config file — used to resolve relative roots */
+  configDir: string;
+}
+
+/**
+ * Load and validate a builder config file.
+ *
+ * The file must be a TypeScript or JavaScript module with a default export
+ * produced by `defineConfig(...)`.
+ *
+ * When the file is TypeScript (`.ts`), we use `tsx` via Node's `--import` flag
+ * (which is already set up when the CLI is invoked via the compiled entry), or
+ * we fall back to requiring `tsx/esm` at runtime if available.
+ */
+export async function loadConfig(configFilePath: string): Promise<LoadedConfig> {
+  const absolute = resolvePath(configFilePath);
+
+  if (!fs.existsSync(absolute)) {
+    throw new Error(`Config file not found: ${absolute}`);
+  }
+
+  let mod: { default?: BundlerConfig };
+
+  try {
+    // Convert to a file:// URL so dynamic import works correctly on Windows.
+    const fileUrl = pathToFileURL(absolute).href;
+    mod = await import(fileUrl);
+  } catch (err) {
+    throw wrapError("load-config", absolute, err);
+  }
+
+  const config = mod.default;
+
+  if (!config || typeof config !== "object") {
+    throw new Error(
+      `Config file ${absolute} must export a default object from defineConfig(). Got: ${typeof config}`,
+    );
+  }
+
+  validateConfig(config, absolute);
+
+  return {
+    config,
+    configPath: absolute,
+    configDir: resolvePath(path.dirname(absolute)),
+  };
+}
+
+function validateConfig(config: BundlerConfig, filePath: string): void {
+  if (!config.settings) {
+    throw new Error(`Config "${filePath}" must have a "settings" object.`);
+  }
+  if (!config.settings.buildDir) {
+    throw new Error(`Config "${filePath}" settings.buildDir is required.`);
+  }
+
+  const names = new Set<string>();
+
+  for (const pkg of config.standalone ?? []) {
+    if (!pkg.name) throw new Error(`Standalone package is missing "name" in ${filePath}`);
+    if (!pkg.root) throw new Error(`Standalone package "${pkg.name}" is missing "root"`);
+    if (names.has(pkg.name)) throw new Error(`Duplicate package name: "${pkg.name}"`);
+    names.add(pkg.name);
+  }
+
+  for (const family of config.families ?? []) {
+    if (!family.name) throw new Error(`A family is missing "name" in ${filePath}`);
+    for (const pkg of family.packages) {
+      if (!pkg.name) throw new Error(`Package inside family "${family.name}" is missing "name"`);
+      if (!pkg.root) throw new Error(`Package "${pkg.name}" in family "${family.name}" is missing "root"`);
+      if (names.has(pkg.name)) throw new Error(`Duplicate package name: "${pkg.name}"`);
+      names.add(pkg.name);
+    }
+  }
+}
+
+/**
+ * Attempt to find the default config file in the working directory.
+ * Tries: builder.ts, builder.js, mongez.ts, mongez.js
+ */
+export function findDefaultConfigPath(cwd: string): string {
+  const candidates = ["builder.ts", "builder.js", "mongez.ts", "mongez.js"];
+  for (const candidate of candidates) {
+    const full = path.join(cwd, candidate);
+    if (fs.existsSync(full)) return full;
+  }
+  throw new Error(
+    `No config file found in ${cwd}. Tried: ${candidates.join(", ")}. ` +
+      `Use --config <path> to specify a custom location.`,
+  );
+}

package/src/files/clone-files.ts

@@ -0,0 +1,45 @@
+import fs from "fs";
+import { copyFile, copyDir, pathExists } from "./file-manager.js";
+import { joinPath } from "../utils/paths.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Clone extra files (README, license, etc.) from the package root into the build directory.
+ *
+ * Each entry in the `clone` array can be:
+ *  - a plain string: copied from `<packageRoot>/<str>` to `<buildDir>/<str>`
+ *  - a tuple [src, dest]: copied from `<packageRoot>/<src>` to `<buildDir>/<dest>`
+ */
+export function cloneFiles(
+  packageRoot: string,
+  buildDir: string,
+  cloneList: (string | [string, string])[],
+  packageName: string,
+  dryRun: boolean,
+): void {
+  for (const entry of cloneList) {
+    const [srcRel, destRel] =
+      typeof entry === "string" ? [entry, entry] : entry;
+
+    const src = joinPath(packageRoot, srcRel);
+    const dest = joinPath(buildDir, destRel);
+
+    if (!pathExists(src)) {
+      logger.warn(`[clone-files] ${packageName}: source file not found, skipping — ${src}`);
+      continue;
+    }
+
+    if (dryRun) {
+      logger.info(`[dry-run] clone ${src} → ${dest}`);
+      continue;
+    }
+
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+      copyDir(src, dest);
+    } else {
+      copyFile(src, dest);
+    }
+    logger.debug(`Cloned ${src} → ${dest}`);
+  }
+}

package/src/files/file-manager.ts

@@ -0,0 +1,109 @@
+import fs from "fs";
+import path from "path";
+import { resolvePath, joinPath } from "../utils/paths.js";
+import { wrapError } from "../utils/errors.js";
+
+/**
+ * Ensure a directory exists, creating all intermediate directories as needed.
+ */
+export function ensureDir(dir: string): void {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    throw wrapError("ensure-dir", dir, err);
+  }
+}
+
+/**
+ * Copy a single file from src to dest.
+ * Creates the destination directory if it does not exist.
+ */
+export function copyFile(src: string, dest: string): void {
+  ensureDir(path.dirname(dest));
+  try {
+    fs.copyFileSync(src, dest);
+  } catch (err) {
+    throw wrapError("copy-file", src, err);
+  }
+}
+
+/** Directories that are never copied in any directory tree operation. */
+const COPY_EXCLUDES = new Set([".git", "node_modules", "dist", ".turbo", ".cache"]);
+
+/**
+ * Copy an entire directory tree recursively, skipping .git and node_modules.
+ */
+export function copyDir(src: string, dest: string): void {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (COPY_EXCLUDES.has(entry.name)) continue;
+    const srcPath = joinPath(src, entry.name);
+    const destPath = joinPath(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFile(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Read a file as a UTF-8 string, or throw a BundlerError with context.
+ */
+export function readFile(filePath: string, packageName = filePath): string {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    throw wrapError("read-file", packageName, err);
+  }
+}
+
+/**
+ * Write a UTF-8 string to a file, creating intermediate directories.
+ */
+export function writeFile(filePath: string, content: string, packageName = filePath): void {
+  ensureDir(path.dirname(filePath));
+  try {
+    fs.writeFileSync(filePath, content, "utf-8");
+  } catch (err) {
+    throw wrapError("write-file", packageName, err);
+  }
+}
+
+/**
+ * Move all files matching a glob-like condition.
+ * Actually does a rename — works only within the same filesystem volume.
+ */
+export function moveFile(src: string, dest: string, packageName = src): void {
+  ensureDir(path.dirname(dest));
+  try {
+    fs.renameSync(src, dest);
+  } catch (err) {
+    // rename across devices fails — fall back to copy+unlink
+    try {
+      fs.copyFileSync(src, dest);
+      fs.unlinkSync(src);
+    } catch (fallbackErr) {
+      throw wrapError("move-file", packageName, fallbackErr);
+    }
+  }
+}
+
+/**
+ * Check whether a path exists on the filesystem.
+ */
+export function pathExists(p: string): boolean {
+  return fs.existsSync(p);
+}
+
+/**
+ * List all file paths inside a directory (non-recursive).
+ */
+export function listFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile())
+    .map((e) => joinPath(dir, e.name));
+}

package/src/files/index.ts

@@ -0,0 +1,3 @@
+export * from "./file-manager.js";
+export * from "./clone-files.js";
+export * from "./package-json.js";