@mandujs/core 0.21.0 → 0.22.0

package/src/bundler/build.ts

@@ -14,15 +14,52 @@ import type {
   IslandFileEntry,
 } from "./types";
 import { HYDRATION } from "../constants";
+import { safeBuild } from "./safe-build";
+import { fastRefreshPlugin } from "./fast-refresh-plugin";
+import { mark, measure } from "../perf";
+import { HMR_PERF } from "../perf/hmr-markers";
+import {
+  readVendorCache,
+  writeVendorCache,
+  restoreVendorCache,
+  resolveVendorCacheKeys,
+  type VendorCacheKeyInput,
+  type VendorCacheWriteEntry,
+} from "./vendor-cache";
 import path from "path";
 import fs from "fs/promises";
 
-/** Scan for *.island.tsx / *.island.ts files across hydrated route directories. */
+/**
+ * Scan for *.island.tsx / *.island.ts files across hydrated route directories.
+ *
+ * Phase 7.1 R1 Agent C — per-island conditional skip defence.
+ *
+ * Callers (the two `buildClientBundles` paths at L1643 and L1817) feed us
+ * `hydratedRoutes` (from `getHydratedRoutes`), which already filters for
+ * `route.kind === "page" && route.clientModule && needsHydration(route)`.
+ * We re-assert the `needsHydration` predicate here for two reasons:
+ *
+ *   1. Defence-in-depth — if a future caller forgets the filter, we still
+ *      skip routes with `hydration.strategy === "none"`. Each skipped route
+ *      saves one `fs.readdir` + O(files) regex matches (~1-2 ms on Windows
+ *      NTFS per skipped dir, per diagnostic R0.3).
+ *
+ *   2. Cold-start regression guard — the R0 → R3 F breakdown attributes
+ *      +40-80 ms of cold start to per-island splitting (commit b503c36).
+ *      The unit test `per-island-scan-skips-non-hydrated` pins this so a
+ *      refactor cannot silently re-introduce the scan overhead for routes
+ *      that opt out of hydration.
+ */
 async function scanIslandFiles(routes: RouteSpec[], rootDir: string): Promise<IslandFileEntry[]> {
   const entries: IslandFileEntry[] = [];
   const seenDirs = new Set<string>();
 
   for (const route of routes) {
+    // Defensive guard — see the block comment above for rationale. Without
+    // this, a hypothetical caller passing `manifest.routes` directly would
+    // readdir every page route, including pure-SSR ones.
+    if (!needsHydration(route)) continue;
+
     const dir = path.dirname(path.join(rootDir, route.componentModule ?? route.module));
     if (seenDirs.has(dir)) continue;
     seenDirs.add(dir);
@@ -45,21 +82,46 @@ async function scanIslandFiles(routes: RouteSpec[], rootDir: string): Promise<Is
   return entries;
 }
 
+/**
+ * Test-only accessor for the island-file scanner. Allows the cold-start
+ * test suite (`__tests__/cold-start.test.ts`) to assert the per-island
+ * conditional skip without having to spin up a full `buildClientBundles`
+ * invocation (which would also run `safeBuild`).
+ *
+ * @internal
+ */
+export const _testOnly_scanIslandFiles = scanIslandFiles;
+
+/**
+ * Test-only accessor for the hydrated-routes filter. Mirrors the rationale
+ * above — lets tests verify that `getHydratedRoutes` really does drop
+ * `hydration.strategy: "none"` routes without rebuilding its logic.
+ *
+ * @internal
+ */
+export const _testOnly_getHydratedRoutes = getHydratedRoutes;
+
 /** Build a single per-island bundle. */
 async function buildPerIslandBundle(
   entry: IslandFileEntry, outDir: string, options: BundlerOptions
 ): Promise<{ name: string; js: string; route: string; priority: IslandFileEntry["priority"] }> {
   const entryPath = path.join(outDir, `_entry_island_${entry.name}.js`);
   const outputName = `${entry.name}.island.js`;
+  // Phase 7.1 B-1/B-4: wire Bun's native React Fast Refresh transform +
+  // Mandu's boundary injection plugin — but only in dev. Production
+  // bundles stay clean of `$RefreshReg$` / `$RefreshSig$` stubs.
+  const isDev = (options.minify ?? process.env.NODE_ENV === "production") === false;
   try {
     await Bun.write(entryPath, generateIslandEntry(entry.name, entry.filePath));
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [entryPath],
       outdir: outDir,
       naming: outputName,
       minify: options.minify ?? process.env.NODE_ENV === "production",
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      ...(isDev ? { reactFastRefresh: true } : {}),
+      plugins: isDev ? [fastRefreshPlugin()] : [],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: { "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"), ...options.define },
     });
@@ -971,7 +1033,7 @@ if (typeof window !== 'undefined') {
   try {
     await Bun.write(srcPath, source);
 
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [srcPath],
       outdir: outDir,
       naming: outputName,
@@ -1025,7 +1087,7 @@ async function buildRouterRuntime(
   try {
     await Bun.write(routerPath, generateRouterRuntimeSource());
 
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [routerPath],
       outdir: outDir,
       naming: outputName,
@@ -1100,7 +1162,7 @@ async function buildRuntime(
     await Bun.write(runtimePath, generateRuntimeSource());
 
     // 빌드
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [runtimePath],
       outdir: outDir,
       naming: outputName,
@@ -1161,38 +1223,216 @@ interface VendorBuildResult {
   reactDomClient: string;
   jsxRuntime: string;
   jsxDevRuntime: string;
+  /**
+   * Phase 7.1 B-2: bundled `react-refresh/runtime` — emitted ONLY in
+   * dev mode. Empty string in production. Consumed by the HTML
+   * preamble (`bundler/dev.ts`) via a dynamic import.
+   */
+  reactRefreshRuntime: string;
+  /**
+   * Phase 7.1 B-2: Mandu's `__MANDU_HMR__` glue module — also dev-only.
+   * Imported once by the HTML preamble which then calls `installGlobal`
+   * with the already-loaded refresh runtime.
+   */
+  fastRefreshRuntime: string;
   errors: string[];
 }
 
+/**
+ * Phase 7.1 B-2 — source generator for the `react-refresh/runtime` shim.
+ *
+ * The shim simply re-exports the upstream module under a default export
+ * that `fast-refresh-runtime.ts`'s `installGlobal({ runtimeImport })`
+ * can consume. Mirrors the pattern Vite uses for its `/@react-refresh`
+ * endpoint.
+ */
+function generateReactRefreshRuntimeShimSource(): string {
+  return `
+/**
+ * Mandu React Refresh Runtime Shim (Generated, dev-only)
+ * Re-exports the upstream react-refresh/runtime so the bundler can
+ * pre-bundle it without leaking the CommonJS entry into the app graph.
+ */
+import * as Runtime from 'react-refresh/runtime';
+export const injectIntoGlobalHook = Runtime.injectIntoGlobalHook;
+export const register = Runtime.register;
+export const createSignatureFunctionForTransform = Runtime.createSignatureFunctionForTransform;
+export const performReactRefresh = Runtime.performReactRefresh;
+export default {
+  injectIntoGlobalHook,
+  register,
+  createSignatureFunctionForTransform,
+  performReactRefresh,
+};
+`;
+}
+
+/**
+ * Phase 7.1 B-2 — source generator for the Mandu Fast Refresh glue.
+ *
+ * This re-exports `installGlobal` / `manduHMR` / helpers from
+ * `runtime/fast-refresh-runtime.ts`. By routing through a generated
+ * shim we keep the absolute path to core resolved once at build time
+ * (same pattern as `_devtools.js`).
+ */
+function generateFastRefreshRuntimeShimSource(): string {
+  const runtimePath = path
+    .resolve(import.meta.dir, "..", "runtime", "fast-refresh-runtime.ts")
+    .replace(/\\/g, "/");
+  return `
+/**
+ * Mandu Fast Refresh Runtime Shim (Generated, dev-only)
+ * Wires the react-refresh runtime to window.__MANDU_HMR__.
+ */
+export * from "${runtimePath}";
+import { installGlobal } from "${runtimePath}";
+export { installGlobal };
+`;
+}
+
 /**
  * Vendor shim 번들 빌드
  * React, ReactDOM, ReactDOMClient를 각각의 shim으로 빌드
+ *
+ * Phase 7.2.S2: caches the built shim outputs on disk under
+ * `.mandu/vendor-cache/` keyed by Bun + React + ReactDOM + react-refresh +
+ * @mandujs/core versions. Warm boots reuse the cached files instead of
+ * re-running Bun.build, eliminating ~80-120 ms from cold start.
  */
 async function buildVendorShims(
+  rootDir: string,
   outDir: string,
   options: BundlerOptions
 ): Promise<VendorBuildResult> {
   const errors: string[] = [];
-  type VendorShimKey = "react" | "reactDom" | "reactDomClient" | "jsxRuntime" | "jsxDevRuntime";
+  type VendorShimKey =
+    | "react"
+    | "reactDom"
+    | "reactDomClient"
+    | "jsxRuntime"
+    | "jsxDevRuntime"
+    | "reactRefreshRuntime"
+    | "fastRefreshRuntime";
   const results: Record<VendorShimKey, string> = {
     react: "",
     reactDom: "",
     reactDomClient: "",
     jsxRuntime: "",
     jsxDevRuntime: "",
+    reactRefreshRuntime: "",
+    fastRefreshRuntime: "",
   };
 
-  const shims: Array<{ name: string; source: string; key: VendorShimKey }> = [
-    { name: "_react", source: generateReactShimSource(), key: "react" },
-    { name: "_react-dom", source: generateReactDOMShimSource(), key: "reactDom" },
-    { name: "_react-dom-client", source: generateReactDOMClientShimSource(), key: "reactDomClient" },
-    { name: "_jsx-runtime", source: generateJsxRuntimeShimSource(), key: "jsxRuntime" },
-    { name: "_jsx-dev-runtime", source: generateJsxDevRuntimeShimSource(), key: "jsxDevRuntime" },
+  // Phase 7.1 B-2: dev-only Fast Refresh shims. In production we skip
+  // them entirely so `react-refresh/runtime` is never bundled and the
+  // attack surface / bundle size regressions stay zero for deploys.
+  const isDev =
+    (options.minify ?? process.env.NODE_ENV === "production") === false;
+
+  const shims: Array<{ name: string; source: string; key: VendorShimKey; cacheId: string }> = [
+    { name: "_react", source: generateReactShimSource(), key: "react", cacheId: "react" },
+    { name: "_react-dom", source: generateReactDOMShimSource(), key: "reactDom", cacheId: "react-dom" },
+    { name: "_react-dom-client", source: generateReactDOMClientShimSource(), key: "reactDomClient", cacheId: "react-dom-client" },
+    { name: "_jsx-runtime", source: generateJsxRuntimeShimSource(), key: "jsxRuntime", cacheId: "jsx-runtime" },
+    { name: "_jsx-dev-runtime", source: generateJsxDevRuntimeShimSource(), key: "jsxDevRuntime", cacheId: "jsx-dev-runtime" },
   ];
+  if (isDev) {
+    shims.push(
+      {
+        name: "_vendor-react-refresh",
+        source: generateReactRefreshRuntimeShimSource(),
+        key: "reactRefreshRuntime",
+        cacheId: "react-refresh-runtime",
+      },
+      {
+        name: "_fast-refresh-runtime",
+        source: generateFastRefreshRuntimeShimSource(),
+        key: "fastRefreshRuntime",
+        cacheId: "fast-refresh-glue",
+      },
+    );
+  }
+
+  // Phase 7.2.S2 — Tier 2 disk cache consultation. Production builds
+  // (non-dev, minified) still rebuild fresh because (a) the shim set is
+  // smaller (no fast-refresh) and (b) production is one-shot — there's no
+  // warm workflow to amortize the cache cost against. Dev warm restarts
+  // are where the cache pays off.
+  //
+  // `MANDU_VENDOR_CACHE=0` disables the cache (escape hatch for debugging
+  // cache-invalidation bugs without touching code).
+  const cacheEnabled = isDev && process.env.MANDU_VENDOR_CACHE !== "0";
+  let cacheKeys: VendorCacheKeyInput | null = null;
+
+  if (cacheEnabled) {
+    try {
+      cacheKeys = await resolveVendorCacheKeys(rootDir);
+      const hitOrMiss = await readVendorCache(rootDir, cacheKeys);
+
+      if (hitOrMiss.kind === "hit") {
+        // Attempt to restore every shim file to outDir.
+        const restored = await restoreVendorCache(
+          rootDir,
+          hitOrMiss.manifest,
+          outDir,
+        );
+        if (restored !== null) {
+          // Map the restored files into the result shape. If a shim is
+          // not in the manifest (eg. an older cache from before we added
+          // fast-refresh) we rebuild just that one — but the simpler
+          // policy is to require the manifest to cover every entry the
+          // current shim list wants, so we only accept hits that include
+          // everything. Otherwise fall through to rebuild.
+          const expected = new Set(shims.map((s) => s.cacheId));
+          const present = new Set(restored.keys());
+          let allPresent = true;
+          for (const id of expected) {
+            if (!present.has(id)) {
+              allPresent = false;
+              break;
+            }
+          }
+          if (allPresent) {
+            // Populate result + return. Every shim's outputPath references
+            // the freshly-restored file in `outDir`.
+            for (const shim of shims) {
+              const dst = restored.get(shim.cacheId);
+              if (dst) {
+                const fileName = path.basename(dst);
+                results[shim.key] = `/.mandu/client/${fileName}`;
+              }
+            }
+            mark(HMR_PERF.VENDOR_CACHE_HIT);
+            measure(HMR_PERF.VENDOR_CACHE_HIT, HMR_PERF.VENDOR_CACHE_HIT);
+            return {
+              success: true,
+              react: results.react,
+              reactDom: results.reactDom,
+              reactDomClient: results.reactDomClient,
+              jsxRuntime: results.jsxRuntime,
+              jsxDevRuntime: results.jsxDevRuntime,
+              reactRefreshRuntime: results.reactRefreshRuntime,
+              fastRefreshRuntime: results.fastRefreshRuntime,
+              errors,
+            };
+          }
+          // Restored but missing one of the expected shims — fall through.
+        }
+        // Restore failed — fall through to rebuild.
+      }
+
+      // Miss / failed restore: record the miss marker for perf logs.
+      mark(HMR_PERF.VENDOR_CACHE_MISS);
+      measure(HMR_PERF.VENDOR_CACHE_MISS, HMR_PERF.VENDOR_CACHE_MISS);
+    } catch {
+      // Any cache failure falls through to the full rebuild path — cache
+      // is strictly an optimisation.
+    }
+  }
 
   const buildShim = async (
-    shim: { name: string; source: string; key: VendorShimKey }
-  ): Promise<{ key: VendorShimKey; outputPath?: string; error?: string }> => {
+    shim: { name: string; source: string; key: VendorShimKey; cacheId: string }
+  ): Promise<{ key: VendorShimKey; cacheId: string; outputName?: string; outputPath?: string; error?: string }> => {
     const srcPath = path.join(outDir, `${shim.name}.src.js`);
     const outputName = `${shim.name}.js`;
 
@@ -1207,8 +1447,11 @@ async function buildVendorShims(
       } else if (shim.name === "_jsx-runtime" || shim.name === "_jsx-dev-runtime") {
         shimExternal = ["react"];
       }
+      // `_vendor-react-refresh` and `_fast-refresh-runtime` are
+      // self-contained: we WANT react-refresh bundled in so the
+      // preamble's single dynamic import pulls the whole graph.
 
-      const result = await Bun.build({
+      const result = await safeBuild({
         entrypoints: [srcPath],
         outdir: outDir,
         naming: outputName,
@@ -1228,32 +1471,57 @@ async function buildVendorShims(
         const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
         return {
           key: shim.key,
+          cacheId: shim.cacheId,
           error: `Vendor shim '${shim.name}' build failed (source: ${srcPath}):\n${grouped}\n  Hint: Check the import paths and ensure the vendor package is installed.`,
         };
       }
 
       return {
         key: shim.key,
+        cacheId: shim.cacheId,
+        outputName,
         outputPath: `/.mandu/client/${outputName}`,
       };
     } catch (error) {
       await fs.unlink(srcPath).catch(() => {});
       return {
         key: shim.key,
+        cacheId: shim.cacheId,
         error: `[${shim.name}] ${String(error)}`,
       };
     }
   };
 
   const buildResults = await Promise.all(shims.map((shim) => buildShim(shim)));
+  const writeEntries: VendorCacheWriteEntry[] = [];
   for (const result of buildResults) {
     if (result.error) {
       errors.push(result.error);
-    } else if (result.outputPath) {
+    } else if (result.outputPath && result.outputName) {
       results[result.key] = result.outputPath;
+      writeEntries.push({
+        logicalId: result.cacheId,
+        absPath: path.join(outDir, result.outputName),
+      });
     }
   }
 
+  // Phase 7.2.S2 — persist freshly-built shims for next boot. Best-effort;
+  // a write failure is logged via perf markers (opt-in) but never breaks
+  // the build. Only write when every shim succeeded — partial manifests
+  // would still satisfy the expected-set check on next boot but we
+  // prefer writing only complete manifests.
+  if (cacheEnabled && cacheKeys && errors.length === 0 && writeEntries.length > 0) {
+    // Fire-and-forget so the fast path isn't blocked on disk. The
+    // returned VendorBuildResult does not depend on the write outcome.
+    mark(HMR_PERF.VENDOR_CACHE_WRITE);
+    void writeVendorCache(rootDir, cacheKeys, writeEntries)
+      .then(() => {
+        measure(HMR_PERF.VENDOR_CACHE_WRITE, HMR_PERF.VENDOR_CACHE_WRITE);
+      })
+      .catch(() => {});
+  }
+
   return {
     success: errors.length === 0,
     react: results.react,
@@ -1261,6 +1529,8 @@ async function buildVendorShims(
     reactDomClient: results.reactDomClient,
     jsxRuntime: results.jsxRuntime,
     jsxDevRuntime: results.jsxDevRuntime,
+    reactRefreshRuntime: results.reactRefreshRuntime,
+    fastRefreshRuntime: results.fastRefreshRuntime,
     errors,
   };
 }
@@ -1278,13 +1548,17 @@ async function buildIsland(
   const entryPath = path.join(outDir, `_entry_${route.id}.js`);
   const outputName = `${route.id}.island.js`;
 
+  // Phase 7.1 B-1/B-4: wire native Fast Refresh transform + Mandu's
+  // boundary injection plugin. Dev-only; prod bundles remain clean.
+  const isDev =
+    (options.minify ?? process.env.NODE_ENV === "production") === false;
   try {
     // 엔트리 래퍼 생성
     await Bun.write(entryPath, generateIslandEntry(route.id, clientModulePath));
 
     // 빌드
     // splitting 옵션: true면 공통 코드를 별도 청크로 추출
-    const result = await Bun.build({
+    const result = await safeBuild({
       entrypoints: [entryPath],
       outdir: outDir,
       naming: options.splitting ? "[name]-[hash].js" : outputName,
@@ -1292,6 +1566,8 @@ async function buildIsland(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       splitting: options.splitting ?? (process.env.NODE_ENV === "production"),
+      ...(isDev ? { reactFastRefresh: true } : {}),
+      plugins: isDev ? [fastRefreshPlugin()] : [],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
@@ -1385,6 +1661,17 @@ function createBundleManifest(
     }
   }
 
+  // Phase 7.1 B-2: expose Fast Refresh dev bundles so the HTML
+  // preamble can inject a dynamic import pointing at them. Only
+  // populated when buildVendorShims ran in dev mode.
+  const fastRefresh =
+    vendorResult.reactRefreshRuntime && vendorResult.fastRefreshRuntime
+      ? {
+          runtime: vendorResult.reactRefreshRuntime,
+          glue: vendorResult.fastRefreshRuntime,
+        }
+      : undefined;
+
   return {
     version: 1,
     buildTime: new Date().toISOString(),
@@ -1395,6 +1682,7 @@ function createBundleManifest(
       runtime: runtimePath,
       vendor: vendorResult.react, // primary vendor for backwards compatibility
       router: routerPath, // Client-side Router
+      ...(fastRefresh ? { fastRefresh } : {}),
     },
     importMap: {
       imports: {
@@ -1456,6 +1744,7 @@ export async function buildClientBundles(
   rootDir: string,
   options: BundlerOptions = {}
 ): Promise<BundleResult> {
+  mark("bundler:full");
   const startTime = performance.now();
   const outputs: BundleOutput[] = [];
   const errors: string[] = [];
@@ -1715,7 +2004,9 @@ export async function buildClientBundles(
   const isDev = env === "development";
   const runtimePromise = buildRuntime(outDir, options);
   const routerPromise = buildRouterRuntime(outDir, options);
-  const vendorPromise = buildVendorShims(outDir, options);
+  // Phase 7.2.S2 — `rootDir` is now threaded through so buildVendorShims can
+  // consult `.mandu/vendor-cache/` for warm-boot shim reuse.
+  const vendorPromise = buildVendorShims(rootDir, outDir, options);
   const devtoolsPromise = isDev ? buildDevtoolsBundle(outDir, options) : null;
 
   const [runtimeResult, routerResult, vendorResult, devtoolsResult] = await Promise.all([
@@ -1828,6 +2119,7 @@ export async function buildClientBundles(
   // 7. 통계 계산
   const stats = calculateStats(outputs, startTime);
 
+  measure("bundler:full", "bundler:full");
   return {
     success: errors.length === 0,
     outputs,