@mandujs/core 0.41.2 → 0.43.0

package/src/bundler/build.ts

@@ -58,6 +58,26 @@ function manduDefaultPlugins(options: BundlerOptions): BunPlugin[] {
   return defaults;
 }
 
+/**
+ * Client-path plugin composition — defaults + (optionally) React
+ * Compiler. Only the islands / `"use client"` / partial builds call
+ * this; SSR builds use `manduDefaultPlugins()` directly because React
+ * Compiler offers zero benefit for one-shot HTML rendering.
+ */
+function manduClientPlugins(options: BundlerOptions): BunPlugin[] {
+  const base = manduDefaultPlugins(options);
+  if (options.reactCompiler?.enabled !== true) return base;
+  // Lazy import to avoid pulling the react-compiler module into every
+  // build graph — SSR / non-client paths never touch this branch.
+  const { reactCompiler } = require("./plugins/react-compiler") as typeof import("./plugins/react-compiler");
+  return [
+    ...base,
+    reactCompiler({
+      reactCompilerConfig: options.reactCompiler.compilerConfig,
+    }),
+  ];
+}
+
 /**
  * Scan for *.island.tsx / *.island.ts files across hydrated route directories.
  *
@@ -83,30 +103,44 @@ async function scanIslandFiles(routes: RouteSpec[], rootDir: string): Promise<Is
   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;
+  // Sub-folders under a route directory that the scanner also descends into,
+  // one level only. Convention-driven (not configurable) so the scan cost
+  // stays predictable. `_components` is the Mandu equivalent of the widely
+  // used Next.js "private folder" convention — leading underscore signals
+  // "not a route", which is exactly the place users drop page-local island
+  // sources. Keep this list short; every name adds one `readdir` per route.
+  const ISLAND_SUBDIRS = ["_components", "_islands"] as const;
 
-    const dir = path.dirname(path.join(rootDir, route.componentModule ?? route.module));
-    if (seenDirs.has(dir)) continue;
+  const collectIslandsInDir = async (dir: string, routeId: string, priority: IslandFileEntry["priority"]) => {
+    if (seenDirs.has(dir)) return;
     seenDirs.add(dir);
-
     let files: string[];
-    try { files = await fs.readdir(dir); } catch { continue; }
-
-    const priority = getRouteHydration(route)?.priority || HYDRATION.DEFAULT_PRIORITY;
+    try { files = await fs.readdir(dir); } catch { return; }
     for (const file of files) {
       if (/\.island\.tsx?$/.test(file)) {
         entries.push({
           name: file.replace(/\.island\.tsx?$/, ""),
           filePath: path.join(dir, file),
-          routeId: route.id,
+          routeId,
           priority,
         });
       }
     }
+  };
+
+  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));
+    const priority = getRouteHydration(route)?.priority || HYDRATION.DEFAULT_PRIORITY;
+
+    await collectIslandsInDir(dir, route.id, priority);
+    for (const sub of ISLAND_SUBDIRS) {
+      await collectIslandsInDir(path.join(dir, sub), route.id, priority);
+    }
   }
   return entries;
 }
@@ -130,6 +164,62 @@ export const _testOnly_scanIslandFiles = scanIslandFiles;
  */
 export const _testOnly_getHydratedRoutes = getHydratedRoutes;
 
+/**
+ * Issue #240 Phase 2 — collect every file the React Compiler plugin
+ * would touch during a client build. Used by `mandu check` to feed
+ * `runReactCompilerLint` so developers see which components are
+ * silently bailing out.
+ *
+ * Included:
+ *   - `*.island.tsx` / `*.island.ts` under each hydrated route dir
+ *     (+ `_components/` / `_islands/` siblings — matches
+ *     `scanIslandFiles` exactly).
+ *   - `route.clientModule` for every hydrated route (`"use client"`
+ *     page entry).
+ *   - `*.partial.ts` / `*.partial.tsx` anywhere under `rootDir`.
+ *
+ * Paths are absolute and deduplicated. Returns `[]` when the manifest
+ * has no hydrated routes.
+ */
+export async function collectCompilerLintTargets(
+  manifest: RoutesManifest,
+  rootDir: string,
+): Promise<string[]> {
+  const hydratedRoutes = getHydratedRoutes(manifest);
+  if (hydratedRoutes.length === 0) return [];
+
+  const out = new Set<string>();
+
+  // 1) Islands (reuses the bundler's canonical scanner).
+  const islandFiles = await scanIslandFiles(hydratedRoutes, rootDir);
+  for (const entry of islandFiles) {
+    out.add(path.resolve(entry.filePath));
+  }
+
+  // 2) `"use client"` page modules — the hydrated-route filter
+  //    already asserted `clientModule` exists.
+  for (const route of hydratedRoutes) {
+    const rel = route.clientModule ?? route.module;
+    if (rel) out.add(path.resolve(rootDir, rel));
+  }
+
+  // 3) Partials — glob the whole project once. Partials live anywhere
+  //    the user chooses, they're not sibling-scoped like islands.
+  try {
+    const glob = new Bun.Glob("**/*.partial.{ts,tsx}");
+    for await (const rel of glob.scan({ cwd: rootDir, absolute: true })) {
+      if (rel.includes(`${path.sep}node_modules${path.sep}`)) continue;
+      if (rel.includes(`${path.sep}.mandu${path.sep}`)) continue;
+      out.add(path.resolve(rel));
+    }
+  } catch {
+    // Bun.Glob unavailable or scan failed — skip partials rather than
+    // aborting the whole diagnostic run.
+  }
+
+  return Array.from(out).sort();
+}
+
 /** Build a single per-island bundle. */
 async function buildPerIslandBundle(
   entry: IslandFileEntry, outDir: string, options: BundlerOptions
@@ -150,7 +240,7 @@ async function buildPerIslandBundle(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
+      plugins: [...manduClientPlugins(options), ...(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 },
     });
@@ -1623,7 +1713,7 @@ async function buildIsland(
       target: "browser",
       splitting: options.splitting ?? (process.env.NODE_ENV === "production"),
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
+      plugins: [...manduClientPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),

package/src/bundler/dev.ts

@@ -80,6 +80,31 @@ export interface DevBundlerOptions {
    * `"resource-regen"` exactly once.
    */
   onResourceChange?: (filePath: string) => void | Promise<void>;
+  /**
+   * Issue #242 — content collection change callback.
+   *
+   * Fires when an MDX/MD/YAML/JSON file under `content/` is added,
+   * edited, or removed. Before invoking the callback the bundler has
+   * already called `invalidateAllCollections()` so the Collection API's
+   * in-memory cache is clear; the next `.all()` / `.get()` call will
+   * rescan disk.
+   *
+   * The CLI typically wires this to the HMR server's `broadcast` to
+   * trigger a full browser reload so sidebars / route trees pick up the
+   * added file. Without a callback the invalidation still happens —
+   * a manual refresh will surface the change.
+   */
+  onContentChange?: (filePath: string) => void | Promise<void>;
+  /**
+   * Issue #240 — React Compiler opt-in. Forwarded verbatim to each
+   * `buildClientBundles()` invocation (initial build + every rebuild
+   * triggered by `handleFileChange`). Off by default. SSR paths are
+   * never affected regardless of this flag.
+   */
+  reactCompiler?: {
+    enabled?: boolean;
+    compilerConfig?: Record<string, unknown>;
+  };
   /**
    * Phase 7.0 R2 Agent D — package.json change notification.
    *
@@ -375,7 +400,9 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     onAPIChange,
     onConfigReload,
     onResourceChange,
+    onContentChange,
     onPackageJsonChange,
+    reactCompiler,
     watchDirs: customWatchDirs = [],
     disableDefaultWatchDirs = false,
   } = options;
@@ -385,6 +412,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   const initialBuild = await buildClientBundles(manifest, rootDir, {
     minify: false,
     sourcemap: true,
+    reactCompiler,
   });
 
   if (initialBuild.success) {
@@ -566,6 +594,21 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     // layer simply never hit this path.
   }
 
+  // Issue #242 — content collections (MDX/MD/YAML/JSON) directory. The
+  // Collection API caches scan results in-process, so adding a new
+  // `content/docs/**/foo.mdx` at runtime is invisible until we invalidate
+  // the cache. The `content/` directory is the conventional root used by
+  // `defineCollection({ path: "content/..." })`; projects that put
+  // collection roots elsewhere simply won't match and fall back to a full
+  // manual restart, which is the prior behaviour.
+  const contentDir = path.join(rootDir, "content");
+  try {
+    await fs.promises.access(contentDir);
+    watchDirs.add(contentDir);
+  } catch {
+    // No content/ directory — most projects without docs / blogs.
+  }
+
   // 공통 컴포넌트 디렉토리 추가 (기본 + 커스텀)
   const commonDirsToCheck = disableDefaultWatchDirs
     ? customWatchDirs
@@ -761,6 +804,11 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     // anyway).
     let hasConfigReload = false;
     let hasResourceRegen = false;
+    // Issue #242 — content collection edits (MDX/MD/YAML/JSON under
+    // `content/`). Caught here so a new file triggers `invalidateAll` +
+    // full-reload instead of falling through to "unknown" and never
+    // reaching the Collection cache.
+    let hasContent = false;
 
     for (const file of files) {
       const normalized = normalizeFsPath(file);
@@ -781,6 +829,18 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
         continue;
       }
 
+      // Issue #242 — content-collection sources. Anything under the
+      // project's `content/` directory that's plausibly an entry file.
+      // The Collection API accepts `.md`/`.mdx` for MDX entries and
+      // `.json`/`.yaml`/`.yml` for data collections — cover all four.
+      if (
+        normalized.includes("/content/") &&
+        /\.(mdx?|ya?ml|json)$/.test(normalized)
+      ) {
+        hasContent = true;
+        continue;
+      }
+
       if (normalized.endsWith(".css")) {
         hasCss = true;
         continue;
@@ -831,6 +891,12 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     //      would cause a stale rebuild.
     if (hasConfigReload) return "config-reload";
     if (hasResourceRegen) return "resource-regen";
+    // Issue #242 — content changes are a leaf category: they never
+    // produce code changes, only cache invalidation + a browser refresh.
+    // Rank them above common-dir so a mixed batch that touches both
+    // still reaches the content path (otherwise common-dir would
+    // rebuild but the collection cache would stay stale).
+    if (hasContent) return "content-change";
 
     // Common-dir dominates — it already fans out to every island + SSR
     // registry. No point in double-classifying "mixed" when a fan-out fix
@@ -885,6 +951,17 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       return;
     }
 
+    // Issue #242 — content collection changes. Invalidate the shared
+    // Collection cache and notify the optional callback; no rebuild
+    // required. One invocation per debounce window.
+    if (kind === "content-change") {
+      const contentFiles = files.filter((f) =>
+        /\.(mdx?|ya?ml|json)$/.test(normalizeFsPath(f)),
+      );
+      await handleContentChange(contentFiles);
+      return;
+    }
+
     // Common-dir dominates: one full-reload-adjacent rebuild covers everyone.
     if (kind === "common-dir") {
       await handleFileChange(files.find((f) => isInCommonDir(f)) ?? files[0]);
@@ -996,6 +1073,44 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     }
   };
 
+  /**
+   * Issue #242 — dispatch a batch of content collection changes.
+   *
+   * Clears every registered `Collection`'s in-memory cache via
+   * `invalidateAllCollections()` and then invokes `onContentChange` once
+   * per file so the CLI can broadcast a full browser reload. Dynamic
+   * import keeps the bundler module tree free of a hard content-layer
+   * dependency (projects without `@mandujs/core/content` in the import
+   * closure simply get a no-op).
+   */
+  const handleContentChange = async (files: readonly string[]): Promise<void> => {
+    if (files.length === 0) return;
+    try {
+      const mod: typeof import("../content/collection") = await import("../content/collection");
+      if (typeof mod.invalidateAllCollections === "function") {
+        mod.invalidateAllCollections();
+      }
+    } catch {
+      // Content layer not in the closure — harmless.
+    }
+    if (onContentChange) {
+      for (const file of files) {
+        try {
+          await Promise.resolve(onContentChange(file));
+        } catch (err) {
+          console.error(
+            `[Mandu HMR] content-change callback threw for ${path.basename(file)}:`,
+            err instanceof Error ? err.message : String(err),
+          );
+        }
+      }
+    } else {
+      console.log(
+        `[Mandu HMR] ${files.length} content file(s) changed — collection cache invalidated`,
+      );
+    }
+  };
+
   const handleFileChange = async (changedFile: string): Promise<void> => {
     // 동시 빌드 방지 (#121) — B2 강화: 빌드 중이면 Set에 추가 (drop 방지).
     if (isBuilding) {
@@ -1020,6 +1135,13 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       await handleResourceRegenBatch([changedFile]);
       return;
     }
+    if (
+      normalized.includes("/content/") &&
+      /\.(mdx?|ya?ml|json)$/.test(normalized)
+    ) {
+      await handleContentChange([changedFile]);
+      return;
+    }
     if (isPackageJsonFile(normalized)) {
       // Advisory notification only — a `package.json` save on npm install
       // fires multiple times in <100 ms, so auto-restart would loop. The
@@ -1202,6 +1324,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
           minify: false,
           sourcemap: true,
           targetRouteIds: targetIds,
+          reactCompiler,
         });
         const buildTime = performance.now() - startTime;
         if (result.success) {
@@ -1259,6 +1382,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
           minify: false,
           sourcemap: true,
           skipFrameworkBundles: true,
+          reactCompiler,
         });
 
         const buildTime = performance.now() - startTime;
@@ -1383,6 +1507,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
         minify: false,
         sourcemap: true,
         targetRouteIds: [routeId],
+        reactCompiler,
       });
 
       const buildTime = performance.now() - startTime;

package/src/bundler/hmr-types.ts

@@ -237,6 +237,7 @@ export interface CoalescedChange {
     | "api-only"                // route.ts (API)
     | "config-reload"           // mandu.config.ts / .env — server restart
     | "resource-regen"          // *.resource.ts / *.contract.ts — code-gen
+    | "content-change"          // content/**/*.{mdx,md,json,yaml} — collection invalidate + full-reload
     | "mixed";                  // more than one category
 }
 

package/src/bundler/plugins/__tests__/react-compiler-lint.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import {
+  runReactCompilerLint,
+  formatCompilerReport,
+  type ReactCompilerDiagnostic,
+} from "../react-compiler-lint";
+
+describe("runReactCompilerLint", () => {
+  test("returns empty result with no targets without invoking ESLint", async () => {
+    const result = await runReactCompilerLint({
+      projectRoot: process.cwd(),
+      targetFiles: [],
+    });
+    expect(result.diagnostics).toEqual([]);
+    expect(result.skipped).toBe(false);
+  });
+
+  test("degrades gracefully when ESLint peer dep is missing", async () => {
+    // In a clean Mandu checkout `eslint` and
+    // `eslint-plugin-react-compiler` are not installed. The runner
+    // must report `skipped: true` + empty diagnostics + a skipReason.
+    const result = await runReactCompilerLint({
+      projectRoot: process.cwd(),
+      targetFiles: [path.resolve(__filename)],
+    });
+    // If ESLint happens to be installed in this env, diagnostics is
+    // either empty (this file has no bailouts) or the runner ran
+    // successfully. Either shape is valid — the contract we care
+    // about is "no throw + typed result."
+    expect(Array.isArray(result.diagnostics)).toBe(true);
+    expect(typeof result.skipped).toBe("boolean");
+    if (result.skipped) {
+      expect(typeof result.skipReason).toBe("string");
+    }
+  });
+});
+
+describe("formatCompilerReport", () => {
+  test("returns the no-bailouts sentinel for empty input", () => {
+    expect(formatCompilerReport([])).toContain("no bailouts detected");
+  });
+
+  test("summarises bailouts with file counts + bullet list", () => {
+    const diagnostics: ReactCompilerDiagnostic[] = [
+      {
+        file: "/app/todos/todo.island.tsx",
+        line: 42,
+        column: 5,
+        message: "Cannot memoize: ref escape in closure.",
+        ruleId: "react-compiler/react-compiler",
+        severity: "warning",
+      },
+      {
+        file: "/app/todos/todo.island.tsx",
+        line: 87,
+        column: 3,
+        message: "Cannot memoize: conditional hook call.",
+        ruleId: "react-compiler/react-compiler",
+        severity: "warning",
+      },
+      {
+        file: "/app/dashboard/chart.client.tsx",
+        line: 14,
+        column: 9,
+        message: "Cannot memoize: mutation of a shared value.",
+        ruleId: "react-compiler/react-compiler",
+        severity: "warning",
+      },
+    ];
+    const out = formatCompilerReport(diagnostics);
+    expect(out).toContain("3 bailout(s) in 2 file(s)");
+    expect(out).toContain("todo.island.tsx:42:5");
+    expect(out).toContain("chart.client.tsx:14:9");
+    expect(out).toContain("https://react.dev");
+  });
+
+  test("truncates past the limit with a '... N more' tail", () => {
+    const diagnostics: ReactCompilerDiagnostic[] = Array.from(
+      { length: 30 },
+      (_, i) => ({
+        file: `/app/x/c${i}.island.tsx`,
+        line: i + 1,
+        column: 1,
+        message: "bailout",
+        ruleId: "react-compiler/react-compiler",
+        severity: "warning" as const,
+      }),
+    );
+    const out = formatCompilerReport(diagnostics, { limit: 5 });
+    expect(out).toContain("30 bailout(s)");
+    expect(out).toContain("… and 25 more");
+  });
+
+  test("uses relative paths when projectRoot is provided", () => {
+    const diagnostic: ReactCompilerDiagnostic = {
+      file: path.resolve("/project/app/todo.island.tsx"),
+      line: 1,
+      column: 1,
+      message: "bailout",
+      ruleId: "react-compiler/react-compiler",
+      severity: "warning",
+    };
+    const out = formatCompilerReport([diagnostic], {
+      projectRoot: path.resolve("/project"),
+    });
+    expect(out).toContain(path.join("app", "todo.island.tsx"));
+    expect(out).not.toContain(path.resolve("/project/app"));
+  });
+});

package/src/bundler/plugins/index.ts

@@ -22,6 +22,20 @@ export {
   type BlockGeneratedImportsOptions,
 } from "./block-generated-imports";
 
+export {
+  reactCompiler,
+  type ReactCompilerPluginOptions,
+} from "./react-compiler";
+
+export {
+  runReactCompilerLint,
+  formatCompilerReport,
+  type ReactCompilerDiagnostic,
+  type RunReactCompilerLintOptions,
+  type RunReactCompilerLintResult,
+  type FormatCompilerReportOptions,
+} from "./react-compiler-lint";
+
 /**
  * Subset of `ManduConfig.guard` consumed by `defaultBundlerPlugins()`.
  * We deliberately don't import the full `ManduConfig` type to keep the