@mandujs/core 0.41.2 → 0.43.0

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

@@ -0,0 +1,253 @@
+/**
+ * React Compiler bailout detector (#240 Phase 2).
+ *
+ * React Compiler silently skips components it can't safely memoize
+ * ("15% bailout"). Developers have no way to know which components
+ * are in the skipped set without this static pass.
+ *
+ * This module runs `eslint-plugin-react-compiler` in-process against a
+ * caller-supplied list of files (islands / `"use client"` pages /
+ * partials — the same files the bundler's `manduClientPlugins` gate
+ * picks up) and returns normalized diagnostics. `mandu check` wires
+ * this up behind `experimental.reactCompiler.enabled`.
+ *
+ * ## Why ESLint, not oxlint?
+ *
+ * The canonical rule lives at `react-compiler/react-compiler` in
+ * `eslint-plugin-react-compiler`. Oxlint has no port at the time of
+ * writing. When oxlint gains the rule we can swap this runner for a
+ * thin `oxlint --rule react-compiler/react-compiler` shell without
+ * changing callers — the `runReactCompilerLint` signature stays.
+ *
+ * ## Graceful degradation
+ *
+ * `eslint` and `eslint-plugin-react-compiler` are **optional** peer
+ * dependencies. If either is missing the runner returns `[]` and logs
+ * a single warning — the build is never blocked.
+ */
+
+import path from "node:path";
+
+export interface ReactCompilerDiagnostic {
+  /** Absolute path to the offending file. */
+  file: string;
+  /** 1-indexed line. */
+  line: number;
+  /** 1-indexed column. */
+  column: number;
+  /** Human-readable message produced by the rule. */
+  message: string;
+  /** Always `"react-compiler/react-compiler"`. */
+  ruleId: string;
+  /** ESLint severity — "error" (`2`) or "warning" (`1`). */
+  severity: "warning" | "error";
+}
+
+export interface RunReactCompilerLintOptions {
+  /**
+   * Project root — used to resolve `eslint` / the plugin from the
+   * project's own `node_modules` before falling back to Mandu's.
+   */
+  projectRoot: string;
+  /**
+   * Absolute file paths to lint. Callers should pass only files the
+   * bundler would run through the Compiler (islands / client pages /
+   * partials). Passing server files wastes CPU — the rule still runs
+   * but the diagnostics are irrelevant.
+   */
+  targetFiles: readonly string[];
+  /**
+   * Severity level used for the rule. Default `"warning"`. `"error"`
+   * makes the diagnostic a hard failure in strict mode.
+   */
+  severity?: "warning" | "error";
+}
+
+export interface RunReactCompilerLintResult {
+  /** All diagnostics found. Empty array on success or graceful skip. */
+  diagnostics: ReactCompilerDiagnostic[];
+  /** When `true` the runner could not load its peers and returned `[]`. */
+  skipped: boolean;
+  /** Human-readable explanation when `skipped` is `true`. */
+  skipReason?: string;
+}
+
+// Minimal structural types for ESLint's flat-config API. We avoid a
+// hard dependency on `@types/eslint` because eslint is an optional
+// peer dep; the real module is imported dynamically at runtime.
+type ESLintMessage = {
+  ruleId: string | null;
+  severity: number;
+  message: string;
+  line?: number;
+  column?: number;
+};
+type ESLintLintResult = {
+  filePath: string;
+  messages: ESLintMessage[];
+};
+type ESLintCtor = new (opts: { overrideConfigFile?: boolean; overrideConfig?: unknown }) => {
+  lintFiles: (patterns: readonly string[]) => Promise<ESLintLintResult[]>;
+};
+
+async function resolvePeers(
+  _projectRoot: string,
+): Promise<{ ESLint: ESLintCtor; plugin: unknown } | { error: string }> {
+  try {
+    const eslintMod = (await import(/* @vite-ignore */ "eslint" as string)) as {
+      ESLint?: ESLintCtor;
+      default?: { ESLint: ESLintCtor };
+    };
+    const ESLint = eslintMod.ESLint ?? eslintMod.default?.ESLint;
+    if (!ESLint) {
+      return { error: "`eslint` loaded but `ESLint` constructor not exported" };
+    }
+    const pluginMod = (await import(
+      /* @vite-ignore */ "eslint-plugin-react-compiler" as string
+    )) as { default?: unknown };
+    const plugin = pluginMod.default ?? pluginMod;
+    return { ESLint, plugin };
+  } catch (err) {
+    return {
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+function mapSeverity(raw: number): "warning" | "error" {
+  return raw >= 2 ? "error" : "warning";
+}
+
+/**
+ * Run the `react-compiler/react-compiler` rule against a list of
+ * files. Does **not** read any ESLint config from disk — we assemble
+ * an inline flat config so the result is deterministic regardless of
+ * the host project's ESLint setup.
+ */
+export async function runReactCompilerLint(
+  options: RunReactCompilerLintOptions,
+): Promise<RunReactCompilerLintResult> {
+  if (options.targetFiles.length === 0) {
+    return { diagnostics: [], skipped: false };
+  }
+
+  const peers = await resolvePeers(options.projectRoot);
+  if ("error" in peers) {
+    console.warn(
+      "[Mandu React Compiler] Skipping bailout diagnostics — " +
+        "install `eslint` and `eslint-plugin-react-compiler` to enable. " +
+        `Reason: ${peers.error}`,
+    );
+    return {
+      diagnostics: [],
+      skipped: true,
+      skipReason: peers.error,
+    };
+  }
+  const { ESLint, plugin } = peers;
+  const severityNumber = options.severity === "error" ? 2 : 1;
+
+  // Flat config — no eslintrc resolution, no plugin auto-discovery.
+  // The override is evaluated for every target file.
+  const overrideConfig = [
+    {
+      files: ["**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}"],
+      plugins: { "react-compiler": plugin },
+      rules: { "react-compiler/react-compiler": severityNumber },
+    },
+  ];
+
+  let linter;
+  try {
+    linter = new ESLint({ overrideConfigFile: true, overrideConfig });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[Mandu React Compiler] ESLint construction failed — skipping diagnostics. ${reason}`,
+    );
+    return { diagnostics: [], skipped: true, skipReason: reason };
+  }
+
+  const results = await linter.lintFiles(options.targetFiles.slice());
+  const diagnostics: ReactCompilerDiagnostic[] = [];
+  for (const result of results) {
+    for (const msg of result.messages) {
+      if (msg.ruleId !== "react-compiler/react-compiler") continue;
+      diagnostics.push({
+        file: result.filePath,
+        line: msg.line ?? 1,
+        column: msg.column ?? 1,
+        message: msg.message,
+        ruleId: "react-compiler/react-compiler",
+        severity: mapSeverity(msg.severity),
+      });
+    }
+  }
+  return { diagnostics, skipped: false };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Report formatter — kept pure so the CLI can render or tests can snapshot
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface FormatCompilerReportOptions {
+  /** Omit absolute-path prefixes starting with this root. */
+  projectRoot?: string;
+  /** Max diagnostics shown. Excess is summarised as "... N more". Default 25. */
+  limit?: number;
+}
+
+/**
+ * Format diagnostics as a plain-text block suitable for the `mandu
+ * check` console output. Returns a single string so the caller can
+ * `log()` it in one shot.
+ */
+export function formatCompilerReport(
+  diagnostics: readonly ReactCompilerDiagnostic[],
+  options: FormatCompilerReportOptions = {},
+): string {
+  if (diagnostics.length === 0) {
+    return "🧠 React Compiler — no bailouts detected";
+  }
+  const projectRoot = options.projectRoot;
+  const limit = options.limit ?? 25;
+  const byFile = new Map<string, ReactCompilerDiagnostic[]>();
+  for (const d of diagnostics) {
+    const list = byFile.get(d.file) ?? [];
+    list.push(d);
+    byFile.set(d.file, list);
+  }
+
+  const fileCount = byFile.size;
+  const lines: string[] = [];
+  lines.push(
+    `🧠 React Compiler — ${diagnostics.length} bailout(s) in ${fileCount} file(s)`,
+  );
+  lines.push("");
+
+  const shown: ReactCompilerDiagnostic[] = [];
+  for (const ds of byFile.values()) {
+    for (const d of ds) {
+      if (shown.length >= limit) break;
+      shown.push(d);
+    }
+    if (shown.length >= limit) break;
+  }
+  for (const d of shown) {
+    const relative = projectRoot ? path.relative(projectRoot, d.file) : d.file;
+    lines.push(`  ${relative}:${d.line}:${d.column}`);
+    lines.push(`    ${d.message}`);
+  }
+  if (diagnostics.length > shown.length) {
+    lines.push(`  … and ${diagnostics.length - shown.length} more`);
+  }
+  lines.push("");
+  lines.push(
+    "→ These components will NOT be auto-memoized. Most bailouts come from " +
+      "conditional hook calls, ref escape, or mutation of shared values.",
+  );
+  lines.push(
+    "→ See https://react.dev/learn/react-compiler for common patterns.",
+  );
+  return lines.join("\n");
+}

package/src/bundler/plugins/react-compiler.ts

@@ -0,0 +1,162 @@
+/**
+ * Bundler plugin — React Compiler (#240).
+ *
+ * Auto-memoizes React components at build time via the official
+ * `babel-plugin-react-compiler`. Runs as a Bun `onLoad` transform:
+ * source → Babel + react-compiler → transformed code → Bun's remaining
+ * pipeline.
+ *
+ * Ported inline rather than depending on `bun-plugin-react-compiler`
+ * (single-maintainer, 9★ at 2026-04). The substantive logic is ~60
+ * lines; keeping it in-repo avoids the supply-chain risk without adding
+ * real maintenance cost.
+ *
+ * ## Scope
+ *
+ * Only invoked by the bundler's island / `"use client"` / partial build
+ * paths. Server-rendered files (`page.tsx` + `layout.tsx` SSR) never
+ * hit this plugin because React Compiler's memoization is a re-render
+ * optimization; SSR renders once and serializes to HTML. See
+ * `bundler/build.ts` for the gate.
+ *
+ * ## Opt-in
+ *
+ * Disabled by default. Projects enable via `mandu.config.ts`:
+ *
+ * ```ts
+ * export default {
+ *   experimental: {
+ *     reactCompiler: { enabled: true },
+ *   },
+ * } satisfies ManduConfig;
+ * ```
+ *
+ * Failure mode: if `@babel/core` or `babel-plugin-react-compiler` are
+ * missing, the plugin returns the original source verbatim and logs
+ * once per build. This preserves the "enable the flag → try it" UX
+ * without blocking anyone who forgot to install the peer deps.
+ */
+
+import type { BunPlugin } from "bun";
+import fs from "node:fs/promises";
+
+export interface ReactCompilerPluginOptions {
+  /**
+   * File filter — only matching paths get the transform. Default:
+   * `.jsx` / `.tsx`. The bundler's own client-path gate narrows this
+   * further; the regex here is a belt-and-braces check.
+   */
+  filter?: RegExp;
+  /**
+   * Options forwarded to `babel-plugin-react-compiler`. Common keys:
+   *   - `compilationMode: "annotation" | "infer" | "all"`
+   *   - `target: "19" | "18" | "17"`
+   *   - `panicThreshold: "none" | "all_errors" | "critical_errors"`
+   * Omit to use react-compiler defaults (`compilationMode: "infer"` +
+   * `target` derived from the installed `react` version).
+   */
+  reactCompilerConfig?: Record<string, unknown>;
+}
+
+const DEFAULT_FILTER = /\.(?:jsx|tsx)$/;
+
+/**
+ * Create the Bun plugin instance. Dynamic imports inside `onLoad` keep
+ * `@babel/core` out of the bundler's import graph when the plugin is
+ * never activated — the cost is a one-shot `await import()` on first
+ * use, which Bun caches.
+ */
+export function reactCompiler(
+  options: ReactCompilerPluginOptions = {},
+): BunPlugin {
+  const filter = options.filter ?? DEFAULT_FILTER;
+  const compilerConfig = options.reactCompilerConfig;
+
+  // `@babel/core` + `babel-plugin-react-compiler` are optional peer
+  // dependencies — keep them out of the type graph so projects that
+  // don't enable the compiler never need `@types/babel__core`.
+  type BabelLike = { transformAsync: (src: string, opts: unknown) => Promise<{ code?: string | null } | null> };
+  let babelMod: BabelLike | null = null;
+  let compilerPlugin: unknown = null;
+  let resolutionFailed = false;
+
+  const resolveBabel = async (): Promise<boolean> => {
+    if (resolutionFailed) return false;
+    if (babelMod && compilerPlugin) return true;
+    try {
+      // Both imports are peerDependencies declared `optional: true` so
+      // projects without React Compiler never pay the install cost. We
+      // import each separately so a missing react-compiler package
+      // doesn't mask a Babel install failure.
+      if (!babelMod) {
+        const mod = (await import(/* @vite-ignore */ "@babel/core" as string)) as unknown as BabelLike;
+        babelMod = mod;
+      }
+      if (!compilerPlugin) {
+        const cm = (await import(/* @vite-ignore */ "babel-plugin-react-compiler" as string)) as unknown as {
+          default?: unknown;
+        };
+        compilerPlugin = cm.default ?? cm;
+      }
+      return true;
+    } catch (err) {
+      resolutionFailed = true;
+      console.warn(
+        "[Mandu React Compiler] Peer dependency missing — skipping transform. " +
+          "Install @babel/core + babel-plugin-react-compiler to enable. " +
+          `Reason: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return false;
+    }
+  };
+
+  return {
+    name: "mandu:react-compiler",
+    setup(build) {
+      build.onLoad({ filter }, async ({ path: filePath }) => {
+        const ok = await resolveBabel();
+        if (!ok || !babelMod || !compilerPlugin) return undefined;
+
+        let source: string;
+        try {
+          source = await fs.readFile(filePath, "utf-8");
+        } catch {
+          // Bun will surface the original read error when it retries
+          // the load itself; returning undefined gives it the chance.
+          return undefined;
+        }
+
+        try {
+          const result = await babelMod.transformAsync(source, {
+            filename: filePath,
+            sourceMaps: "inline",
+            babelrc: false,
+            configFile: false,
+            parserOpts: {
+              plugins: [
+                "jsx",
+                "typescript",
+                "explicitResourceManagement",
+              ],
+            },
+            plugins: [[compilerPlugin, compilerConfig ?? {}]],
+          });
+          if (!result?.code) return undefined;
+          return {
+            contents: result.code,
+            loader: filePath.endsWith(".tsx") ? "tsx" : "jsx",
+          };
+        } catch (err) {
+          // Return original so Bun falls back to its normal transform —
+          // react-compiler skips plenty of components by design
+          // ("15% bailout") and we don't want a bailout to kill the
+          // build. Log once per file path with the reason.
+          console.warn(
+            `[Mandu React Compiler] skip ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          return undefined;
+        }
+      });
+    },
+  };
+}

package/src/bundler/types.ts

@@ -165,6 +165,18 @@ export interface BundlerOptions {
    */
   blockGeneratedImport?: boolean;
 
+  /**
+   * Issue #240 — React Compiler opt-in. When `enabled: true` the
+   * bundler's client-path invocations install
+   * `mandu:react-compiler` (Babel + `babel-plugin-react-compiler`)
+   * on every `.jsx`/`.tsx` file. SSR-only builds ignore this —
+   * memoization has no effect on a one-shot HTML render.
+   */
+  reactCompiler?: {
+    enabled?: boolean;
+    compilerConfig?: Record<string, unknown>;
+  };
+
   /**
    * Phase 18.τ — consumer-supplied `BunPlugin`s contributed via plugin
    * `defineBundlerPlugin()` hook. Composed AFTER Mandu's defaults so

package/src/change/integrity.ts

@@ -20,7 +20,8 @@ export async function computeFileHash(filePath: string): Promise<string> {
       throw error;
     }
     throw new Error(
-      `Failed to compute hash for ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+      `Failed to compute hash for ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
     );
   }
 }

package/src/client/index.ts

@@ -232,3 +232,13 @@ export const ManduClient = {
    */
   createPartialGroup,
 };
+
+/**
+ * `Mandu` — README-facing alias of `ManduClient`. Kept so
+ * `import { Mandu } from "@mandujs/core/client"` — the form shown in
+ * `packages/core/README.md` — resolves to the same namespace object at
+ * runtime. `ManduClient` is the canonical export; this re-export exists
+ * because the README (and third-party docs scaffolded from it) uses the
+ * shorter `Mandu.island(...)` / `Mandu.filling(...)` shape.
+ */
+export const Mandu = ManduClient;

package/src/client/island.ts

@@ -51,16 +51,27 @@ export interface IslandMetadata {
 }
 
 /**
- * 컴파일된 Island 컴포넌트 타입
+ * 컴파일된 Island 컴포넌트 타입.
+ *
+ * An island is a **page-level client bundle**, not an inline JSX element.
+ * The runtime representation is a React component **whose body unconditionally
+ * throws**, decorated with the `definition` + `__mandu_island` marker so the
+ * build pipeline can still recognise it.
+ *
+ * Why callable? A plain `{ definition, __mandu_island }` object rendered as
+ * `<MyIsland />` produced React's opaque *"Element type is invalid... got:
+ * object"* error. Making it a function lets React invoke it like any other
+ * component, which triggers our clear diagnostic below — users immediately
+ * learn to switch to `partial()` for embedded client regions.
  */
-export interface CompiledIsland<TServerData, TSetupResult> {
+export type CompiledIsland<TServerData, TSetupResult> = (() => never) & {
   /** Island 정의 */
   definition: IslandDefinition<TServerData, TSetupResult>;
   /** Island 메타데이터 (빌드 시 주입) */
   __mandu_island: true;
   /** Island ID (빌드 시 주입) */
   __mandu_island_id?: string;
-}
+};
 
 /**
  * Island 컴포넌트 생성
@@ -104,10 +115,23 @@ export function island<TServerData, TSetupResult = TServerData>(
     throw new Error("[Mandu Island] render must be a function");
   }
 
-  return {
-    definition,
-    __mandu_island: true,
-  };
+  // Function body: reached only when a server page (or any caller) tries to
+  // render the island as an inline React element — `<MyIsland />`. Islands
+  // are not inline elements; they are page-level client bundles. Throw a
+  // clear message pointing at `partial()` (the right API for embedded
+  // client regions) instead of React's generic "Element type is invalid".
+  const IslandElement = (() => {
+    throw new Error(
+      "[Mandu Island] Islands are page-level client bundles — they cannot " +
+      "be rendered as inline JSX elements. For an embedded client region " +
+      "inside a server page, use `partial()` instead (it returns a " +
+      "renderable component). See " +
+      "https://mandujs.com/docs/architect/client-rendering",
+    );
+  }) as CompiledIsland<TServerData, TSetupResult>;
+  IslandElement.definition = definition;
+  IslandElement.__mandu_island = true;
+  return IslandElement;
 }
 
 /**
@@ -233,7 +257,7 @@ export interface WrapComponentOptions<TServerData, TProps> {
   loading?: () => ReactNode;
 }
 
-export function wrapComponent<TProps extends Record<string, any>>(
+export function wrapComponent<TProps extends Record<string, unknown>>(
   Component: React.ComponentType<TProps>,
   options?: WrapComponentOptions<TProps, TProps>
 ): CompiledIsland<TProps, TProps>;
@@ -355,7 +379,7 @@ export interface CompiledPartial<TProps> {
  * }
  * ```
  */
-export function partial<TProps extends Record<string, any>>(
+export function partial<TProps extends Record<string, unknown>>(
   definition: PartialDefinition<TProps>
 ): CompiledPartial<TProps> & {
   Render: React.ComponentType<TProps>;
@@ -425,7 +449,7 @@ export interface CompiledSlot<TData, TProps> {
  * });
  * ```
  */
-export function slot<TData, TProps extends Record<string, any>>(
+export function slot<TData, TProps extends Record<string, unknown>>(
   definition: SlotDefinition<TData, TProps>
 ): CompiledSlot<TData, TProps> {
   if (!definition.id) {
@@ -473,7 +497,10 @@ export interface PartialGroup {
  * ```
  */
 export function createPartialGroup(): PartialGroup {
-  // React ComponentType variance requires `any` for heterogeneous component storage
+  // React `ComponentType<P>` is contravariant on `P`, so a heterogeneous
+  // component map genuinely needs `any` here — any narrower bag type would
+  // reject concrete `CompiledPartial<{userId: string}>` entries at `.set()`.
+  // oxlint-disable-next-line no-explicit-any -- heterogeneous React component storage
   const partials = new Map<string, CompiledPartial<any>>();
 
   return {

package/src/client/router.ts

@@ -343,7 +343,12 @@ export async function navigate(
 
     // View Transitions API — 브라우저 지원 시 URL + DOM 전환을 동기화
     if (!replace && "startViewTransition" in document) {
-      (document as any).startViewTransition(applyUpdate);
+      // `startViewTransition` is part of the View Transitions API which
+      // is not yet in every lib.dom.d.ts. Narrow the cast to the only
+      // method we call rather than widening to `any`.
+      (document as Document & {
+        startViewTransition: (callback: () => void) => unknown;
+      }).startViewTransition(applyUpdate);
     } else {
       applyUpdate();
     }

package/src/config/mandu.ts

@@ -204,6 +204,20 @@ export interface ManduConfig {
      * Default: `true`.
      */
     blockGeneratedImport?: boolean;
+    /**
+     * Follow-up E — opt-in type-aware lint layer backed by
+     * `oxlint --type-aware` (tsgolint). Declaring this block makes
+     * `mandu guard` invoke oxlint after the architecture check and
+     * merge the results into the final report; MCP's
+     * `mandu_guard_check` surface gains a `typeAware` field.
+     *
+     * @see `@mandujs/core/guard/tsgolint-bridge`
+     */
+    typeAware?: {
+      rules?: string[];
+      severity?: "off" | "warn" | "error";
+      configPath?: string;
+    };
   };
   build?: {
     outDir?: string;
@@ -657,6 +671,49 @@ export interface ManduConfig {
     ollama?: { model?: string; baseUrl?: string };
     telemetryOptOut?: boolean;
   };
+  /**
+   * Issue #240 — Experimental feature flags. Every field under here is
+   * opt-in and may change shape between minor releases. Stable features
+   * graduate out into top-level config keys.
+   */
+  experimental?: {
+    /**
+     * React Compiler (`babel-plugin-react-compiler`) integration. When
+     * `enabled: true` the bundler runs every `.jsx`/`.tsx` source on
+     * the **client build path** (islands, `"use client"` pages,
+     * partials) through Babel + react-compiler to auto-memoize
+     * components and values.
+     *
+     * SSR-only files (server `page.tsx` / `layout.tsx`) are NOT
+     * transformed — React Compiler memoizes re-renders and SSR only
+     * renders once before serializing to HTML, so the transform would
+     * add build time with zero runtime benefit.
+     *
+     * Requires peer dependencies: `@babel/core` + `babel-plugin-react-
+     * compiler`. Missing deps degrade gracefully — the plugin logs a
+     * warning and returns sources unchanged so the build still
+     * succeeds.
+     *
+     * @see packages/core/src/bundler/plugins/react-compiler.ts
+     */
+    reactCompiler?: {
+      /** Master switch. Default: `false`. */
+      enabled?: boolean;
+      /**
+       * Options forwarded verbatim to `babel-plugin-react-compiler`.
+       * Useful keys: `compilationMode`, `target`, `panicThreshold`.
+       * Omit to use react-compiler defaults.
+       */
+      compilerConfig?: Record<string, unknown>;
+      /**
+       * Phase 2 — CI-strict mode. When `true`, `mandu check` exits
+       * non-zero if the bailout linter reports any diagnostic. Useful
+       * as a regression gate once a project's client components are
+       * known-good. Default `false` (report without failing).
+       */
+      strict?: boolean;
+    };
+  };
 }
 
 export const CONFIG_FILES = [