@mandujs/core 0.54.32 → 0.55.0-beta.1

package/src/router/fs-routes.ts

@@ -14,11 +14,11 @@ import { DEFAULT_SCANNER_CONFIG } from "./fs-types";
 import { scanRoutes } from "./fs-scanner";
 import { loadManduConfig } from "../config";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
-import {
-  runOnRouteRegistered,
-  runOnManifestBuilt,
-} from "../plugins/runner";
-import { shouldPreserveExistingClientModule } from "./client-entry";
+import {
+  runOnRouteRegistered,
+  runOnManifestBuilt,
+} from "../plugins/runner";
+import { shouldPreserveExistingClientModule } from "./client-entry";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -87,34 +87,34 @@ export function fsRouteToRouteSpec(fsRoute: FSRouteConfig): RouteSpec {
       ...base,
       kind: "page" as const,
       componentModule: normalizePath(fsRoute.componentModule ?? ""),
-      ...(fsRoute.clientModule
-        ? {
-            clientModule: normalizePath(fsRoute.clientModule),
-            ...(fsRoute.clientExportName ? { clientExportName: fsRoute.clientExportName } : {}),
-            hydration: fsRoute.hydration ?? {
-              strategy: "island" as const,
-              priority: "immediate" as const,
-              preload: false,
-            },
-          }
-        : fsRoute.hydration
-          ? { hydration: fsRoute.hydration }
-          : {}),
-      ...(fsRoute.boundaries && fsRoute.boundaries.length > 0
-        ? {
-            boundaries: fsRoute.boundaries.map((boundary) => ({
-              ...boundary,
-              module: normalizePath(boundary.module),
-              source: {
-                ...boundary.source,
-                file: normalizePath(boundary.source.file),
-              },
-            })),
-          }
-        : {}),
-      ...(fsRoute.layoutChain && fsRoute.layoutChain.length > 0
-        ? { layoutChain: fsRoute.layoutChain.map(normalizePath) }
-        : {}),
+      ...(fsRoute.clientModule
+        ? {
+            clientModule: normalizePath(fsRoute.clientModule),
+            ...(fsRoute.clientExportName ? { clientExportName: fsRoute.clientExportName } : {}),
+            hydration: fsRoute.hydration ?? {
+              strategy: "island" as const,
+              priority: "immediate" as const,
+              preload: false,
+            },
+          }
+        : fsRoute.hydration
+          ? { hydration: fsRoute.hydration }
+          : {}),
+      ...(fsRoute.boundaries && fsRoute.boundaries.length > 0
+        ? {
+            boundaries: fsRoute.boundaries.map((boundary) => ({
+              ...boundary,
+              module: normalizePath(boundary.module),
+              source: {
+                ...boundary.source,
+                file: normalizePath(boundary.source.file),
+              },
+            })),
+          }
+        : {}),
+      ...(fsRoute.layoutChain && fsRoute.layoutChain.length > 0
+        ? { layoutChain: fsRoute.layoutChain.map(normalizePath) }
+        : {}),
       ...(fsRoute.loadingModule ? { loadingModule: normalizePath(fsRoute.loadingModule) } : {}),
       ...(fsRoute.errorModule ? { errorModule: normalizePath(fsRoute.errorModule) } : {}),
       ...(fsRoute.notFoundModule ? { notFoundModule: normalizePath(fsRoute.notFoundModule) } : {}),
@@ -324,26 +324,26 @@ export async function generateManifest(
       for (const route of manifest.routes) {
         const prev = existingMap.get(route.id);
         if (!prev) continue;
-        // 사용자가 설정한 clientModule/hydration 보존.
-        // If app/page.tsx used to be a client page and later becomes a server
-        // page, preserving the old clientModule would leak the server graph into
-        // the browser bundle.
-        if (
-          prev.clientModule &&
-          !route.clientModule &&
-          !(route.kind === "page" && route.boundaries && route.boundaries.length > 0) &&
-          await shouldPreserveExistingClientModule(route, prev.clientModule, rootDir)
-        ) {
-          route.clientModule = prev.clientModule;
-          route.clientExportName = prev.clientExportName;
-        }
-        if (prev.hydration && !route.hydration) {
-          const canPreserveHydration =
-            !!route.clientModule || prev.hydration.strategy === "none";
-          if (canPreserveHydration) {
-            route.hydration = prev.hydration;
-          }
-        }
+        // 사용자가 설정한 clientModule/hydration 보존.
+        // If app/page.tsx used to be a client page and later becomes a server
+        // page, preserving the old clientModule would leak the server graph into
+        // the browser bundle.
+        if (
+          prev.clientModule &&
+          !route.clientModule &&
+          !(route.kind === "page" && route.boundaries && route.boundaries.length > 0) &&
+          await shouldPreserveExistingClientModule(route, prev.clientModule, rootDir)
+        ) {
+          route.clientModule = prev.clientModule;
+          route.clientExportName = prev.clientExportName;
+        }
+        if (prev.hydration && !route.hydration) {
+          const canPreserveHydration =
+            !!route.clientModule || prev.hydration.strategy === "none";
+          if (canPreserveHydration) {
+            route.hydration = prev.hydration;
+          }
+        }
         // Issue #214 — preserve prerender-time fields (`dynamicParams`,
         // `staticParams`) across manifest rescans. `mandu build`'s prerender
         // phase stamps these onto the manifest; a subsequent `mandu dev`

package/src/router/fs-scanner.ts

@@ -7,7 +7,7 @@
  */
 
 import { stat } from "fs/promises";
-import { dirname, join, relative, basename, extname } from "path";
+import { dirname, join, relative, basename, extname } from "path";
 import type {
   ScannedFile,
   FSScannerConfig,
@@ -28,27 +28,27 @@ import {
   sortRoutesByPriority,
   getPatternShape,
 } from "./fs-patterns";
-import { mark, measure } from "../perf";
-import { METADATA_ROUTES } from "../routes/types";
-import type { HydrationConfig } from "../spec/schema";
-import {
-  hasUseClientDirective,
-  resolveClientImportModulePath,
-  resolveRouteLevelClientEntry,
-} from "./client-entry";
-import { analyzeRouteSource } from "./route-source-analyzer";
-import {
-  assertNoClientBoundaryDiagnostics,
-  collectStaticImportSpecifiers,
-  isClientBoundaryModuleSpecifier,
-  transformClientBoundaries,
-  validateClientBoundaryExport,
-  validateClientBoundaryServerOnlyImports,
-} from "../bundler/client-boundary-transform";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Scanner Class
-// ═══════════════════════════════════════════════════════════════════════════
+import { mark, measure } from "../perf";
+import { METADATA_ROUTES } from "../routes/types";
+import type { HydrationConfig } from "../spec/schema";
+import {
+  hasUseClientDirective,
+  resolveClientImportModulePath,
+  resolveRouteLevelClientEntry,
+} from "./client-entry";
+import { analyzeRouteSource } from "./route-source-analyzer";
+import {
+  assertNoClientBoundaryDiagnostics,
+  collectStaticImportSpecifiers,
+  isClientBoundaryModuleSpecifier,
+  transformClientBoundaries,
+  validateClientBoundaryExport,
+  validateClientBoundaryServerOnlyImports,
+} from "../bundler/client-boundary-transform";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scanner Class
+// ═══════════════════════════════════════════════════════════════════════════
 
 /**
  * FS Routes 스캐너
@@ -375,49 +375,49 @@ export class FSScanner {
       const dirPath = this.getDirPath(file.relativePath);
       const islands = islandMap.get(dirPath);
 
-      // clientModule 결정: island 파일 또는 "use client"가 있는 page 자체
-      let clientModule: string | undefined;
-      let clientExportName: string | undefined;
-      let boundaries: NonNullable<FSRouteConfig["boundaries"]> = [];
-      let hydration: HydrationConfig | undefined;
-      let pageFileContent: string | null = null;
-      let pageHasUseClient = false;
-
-      if (file.type === "page") {
-        try {
-          pageFileContent = await Bun.file(file.absolutePath).text();
-        } catch {
-          pageFileContent = null;
-        }
-        if (pageFileContent) {
-          const analysis = analyzeRouteSource(pageFileContent, modulePath);
-          hydration = analysis.hydrationConfig;
-          pageHasUseClient = analysis.directives.useClient;
-          for (const diagnostic of analysis.diagnostics) {
-            routeErrors.push({
-              type: "route_source_diagnostic",
-              message: `${diagnostic.code}: ${diagnostic.message}`,
-              filePath: file.absolutePath,
-            });
-          }
-          if (!pageHasUseClient) {
-            boundaries = await this.resolveClientBoundaries(
-              rootDir,
-              modulePath,
-              routeId,
-              pageFileContent,
-              hydration?.priority ?? "visible",
-            );
-          }
-          if (boundaries.length > 0 && !hydration) {
-            hydration = {
-              strategy: "island",
-              priority: "visible",
-              preload: false,
-            };
-          }
-        }
-      }
+      // clientModule 결정: island 파일 또는 "use client"가 있는 page 자체
+      let clientModule: string | undefined;
+      let clientExportName: string | undefined;
+      let boundaries: NonNullable<FSRouteConfig["boundaries"]> = [];
+      let hydration: HydrationConfig | undefined;
+      let pageFileContent: string | null = null;
+      let pageHasUseClient = false;
+
+      if (file.type === "page") {
+        try {
+          pageFileContent = await Bun.file(file.absolutePath).text();
+        } catch {
+          pageFileContent = null;
+        }
+        if (pageFileContent) {
+          const analysis = analyzeRouteSource(pageFileContent, modulePath);
+          hydration = analysis.hydrationConfig;
+          pageHasUseClient = analysis.directives.useClient;
+          for (const diagnostic of analysis.diagnostics) {
+            routeErrors.push({
+              type: "route_source_diagnostic",
+              message: `${diagnostic.code}: ${diagnostic.message}`,
+              filePath: file.absolutePath,
+            });
+          }
+          if (!pageHasUseClient) {
+            boundaries = await this.resolveClientBoundaries(
+              rootDir,
+              modulePath,
+              routeId,
+              pageFileContent,
+              hydration?.priority ?? "visible",
+            );
+          }
+          if (boundaries.length > 0 && !hydration) {
+            hydration = {
+              strategy: "island",
+              priority: "visible",
+              preload: false,
+            };
+          }
+        }
+      }
 
       if (islands?.[0]) {
         // 우선순위: 명시적 island 파일
@@ -435,16 +435,16 @@ export class FSScanner {
             conflictsWith: islands[0].absolutePath,
           });
         }
-      } else if (file.type === "page" && pageFileContent) {
-        // page 파일 자체에서 "use client" 확인
-        if (pageHasUseClient) {
-          clientModule = modulePath;
-        } else if (boundaries.length === 0) {
-          const routeClientEntry = await resolveRouteLevelClientEntry(rootDir, modulePath, pageFileContent);
-          clientModule = routeClientEntry?.modulePath;
-          clientExportName = routeClientEntry?.exportName;
-        }
-      }
+      } else if (file.type === "page" && pageFileContent) {
+        // page 파일 자체에서 "use client" 확인
+        if (pageHasUseClient) {
+          clientModule = modulePath;
+        } else if (boundaries.length === 0) {
+          const routeClientEntry = await resolveRouteLevelClientEntry(rootDir, modulePath, pageFileContent);
+          clientModule = routeClientEntry?.modulePath;
+          clientExportName = routeClientEntry?.exportName;
+        }
+      }
 
       // 로딩/에러/404 모듈 찾기 — nearest-ancestor resolution.
       // Phase 18.β: `not-found.tsx` joins `loading.tsx`/`error.tsx` in
@@ -459,15 +459,15 @@ export class FSScanner {
         segments: file.segments,
         pattern,
         kind: file.type === "page" ? "page" : "api",
-        module: modulePath,
-        componentModule: file.type === "page" ? modulePath : undefined,
-        clientModule,
-        clientExportName,
-        boundaries: boundaries && boundaries.length > 0 ? boundaries : undefined,
-        hydration,
-        layoutChain,
-        loadingModule,
-        errorModule,
+        module: modulePath,
+        componentModule: file.type === "page" ? modulePath : undefined,
+        clientModule,
+        clientExportName,
+        boundaries: boundaries && boundaries.length > 0 ? boundaries : undefined,
+        hydration,
+        layoutChain,
+        loadingModule,
+        errorModule,
         notFoundModule,
         sourceFile: file.absolutePath,
       };
@@ -485,7 +485,7 @@ export class FSScanner {
     return { routes, routeErrors };
   }
 
-  private hasHydrationShellMismatchRisk(pageContent: string, _islandRelativePath: string): boolean {
+  private hasHydrationShellMismatchRisk(pageContent: string, _islandRelativePath: string): boolean {
     // import문에서 island 모듈의 변수명을 직접 파싱
     const importMatch = pageContent.match(
       /import\s+([A-Za-z_$][A-Za-z0-9_$]*)\s+from\s+["'][^"']*\.island(?:\.(?:tsx?|jsx?))?["']/
@@ -502,116 +502,116 @@ export class FSScanner {
     return new RegExp(
       `typeof\\s+${islandVarName}\\s*!==\\s*["']undefined["']\\s*&&\\s*null`
     ).test(pageContent);
-  }
-
-  private async resolveClientBoundaries(
-    rootDir: string,
-    routeModule: string,
-    routeId: string,
-    source: string,
-    hydrate: NonNullable<HydrationConfig["priority"]>,
-  ): Promise<NonNullable<FSRouteConfig["boundaries"]>> {
-    const modules = await this.collectRouteBoundaryModules(rootDir, routeModule, source);
-    const boundaries: NonNullable<FSRouteConfig["boundaries"]> = [];
-
-    for (const moduleInfo of modules) {
-      const result = transformClientBoundaries(moduleInfo.source, {
-        routeId,
-        fileName: moduleInfo.modulePath,
-        hydrate,
-        ordinalOffset: boundaries.length,
-      });
-      if (result.boundaries.length === 0) continue;
-
-      const diagnostics = [...result.diagnostics];
-      const resolved = await Promise.all(result.boundaries.map(async (boundary) => {
-        const modulePath = await resolveClientImportModulePath(rootDir, boundary.source.file, boundary.module);
-        const resolvedBoundary = {
-          ...boundary,
-          module: modulePath ?? boundary.module,
-        };
-        if (modulePath) {
-          const clientSource = await Bun.file(join(rootDir, modulePath)).text();
-          diagnostics.push(...validateClientBoundaryServerOnlyImports(clientSource, resolvedBoundary, modulePath));
-          const validation = validateClientBoundaryExport(clientSource, resolvedBoundary, modulePath);
-          if (validation.diagnostic) diagnostics.push(validation.diagnostic);
-        }
-        return resolvedBoundary;
-      }));
-      assertNoClientBoundaryDiagnostics(diagnostics);
-      boundaries.push(...resolved);
-    }
-
-    return boundaries;
-  }
-
-  private async collectRouteBoundaryModules(
-    rootDir: string,
-    routeModule: string,
-    routeSource: string,
-  ): Promise<Array<{ modulePath: string; source: string }>> {
-    const visited = new Set<string>();
-    const modules: Array<{ modulePath: string; source: string }> = [];
-
-    const visit = async (modulePath: string, source: string): Promise<void> => {
-      const normalizedModulePath = modulePath.replace(/\\/g, "/").replace(/^\.\//, "");
-      if (visited.has(normalizedModulePath)) return;
-      visited.add(normalizedModulePath);
-      modules.push({ modulePath: normalizedModulePath, source });
-
-      for (const specifier of collectStaticImportSpecifiers(source, normalizedModulePath)) {
-        if (isClientBoundaryModuleSpecifier(specifier)) continue;
-        const resolved = await this.resolveRouteOwnedImportModulePath(rootDir, normalizedModulePath, specifier);
-        if (!resolved || visited.has(resolved)) continue;
-
-        let childSource: string;
-        try {
-          childSource = await Bun.file(join(rootDir, resolved)).text();
-        } catch {
-          continue;
-        }
-        if (hasUseClientDirective(childSource)) continue;
-
-        await visit(resolved, childSource);
-      }
-    };
-
-    await visit(routeModule, routeSource);
-    return modules;
-  }
-
-  private async resolveRouteOwnedImportModulePath(
-    rootDir: string,
-    importerModule: string,
-    specifier: string,
-  ): Promise<string | null> {
-    const normalized = specifier.replace(/\\/g, "/");
-    let basePath: string | null = null;
-
-    if (normalized.startsWith("@/") || normalized.startsWith("~/")) {
-      basePath = join(rootDir, "src", normalized.slice(2));
-    } else if (normalized.startsWith("./") || normalized.startsWith("../")) {
-      basePath = join(rootDir, dirname(importerModule), normalized);
-    }
-
-    if (!basePath) return null;
-
-    for (const candidate of expandRouteImportCandidates(basePath)) {
-      try {
-        const entry = await stat(candidate);
-        if (entry.isFile()) {
-          return relative(rootDir, candidate).replace(/\\/g, "/");
-        }
-      } catch {
-        // Try the next candidate.
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * 레이아웃 체인 해결
+  }
+
+  private async resolveClientBoundaries(
+    rootDir: string,
+    routeModule: string,
+    routeId: string,
+    source: string,
+    hydrate: NonNullable<HydrationConfig["priority"]>,
+  ): Promise<NonNullable<FSRouteConfig["boundaries"]>> {
+    const modules = await this.collectRouteBoundaryModules(rootDir, routeModule, source);
+    const boundaries: NonNullable<FSRouteConfig["boundaries"]> = [];
+
+    for (const moduleInfo of modules) {
+      const result = transformClientBoundaries(moduleInfo.source, {
+        routeId,
+        fileName: moduleInfo.modulePath,
+        hydrate,
+        ordinalOffset: boundaries.length,
+      });
+      if (result.boundaries.length === 0) continue;
+
+      const diagnostics = [...result.diagnostics];
+      const resolved = await Promise.all(result.boundaries.map(async (boundary) => {
+        const modulePath = await resolveClientImportModulePath(rootDir, boundary.source.file, boundary.module);
+        const resolvedBoundary = {
+          ...boundary,
+          module: modulePath ?? boundary.module,
+        };
+        if (modulePath) {
+          const clientSource = await Bun.file(join(rootDir, modulePath)).text();
+          diagnostics.push(...validateClientBoundaryServerOnlyImports(clientSource, resolvedBoundary, modulePath));
+          const validation = validateClientBoundaryExport(clientSource, resolvedBoundary, modulePath);
+          if (validation.diagnostic) diagnostics.push(validation.diagnostic);
+        }
+        return resolvedBoundary;
+      }));
+      assertNoClientBoundaryDiagnostics(diagnostics);
+      boundaries.push(...resolved);
+    }
+
+    return boundaries;
+  }
+
+  private async collectRouteBoundaryModules(
+    rootDir: string,
+    routeModule: string,
+    routeSource: string,
+  ): Promise<Array<{ modulePath: string; source: string }>> {
+    const visited = new Set<string>();
+    const modules: Array<{ modulePath: string; source: string }> = [];
+
+    const visit = async (modulePath: string, source: string): Promise<void> => {
+      const normalizedModulePath = modulePath.replace(/\\/g, "/").replace(/^\.\//, "");
+      if (visited.has(normalizedModulePath)) return;
+      visited.add(normalizedModulePath);
+      modules.push({ modulePath: normalizedModulePath, source });
+
+      for (const specifier of collectStaticImportSpecifiers(source, normalizedModulePath)) {
+        if (isClientBoundaryModuleSpecifier(specifier)) continue;
+        const resolved = await this.resolveRouteOwnedImportModulePath(rootDir, normalizedModulePath, specifier);
+        if (!resolved || visited.has(resolved)) continue;
+
+        let childSource: string;
+        try {
+          childSource = await Bun.file(join(rootDir, resolved)).text();
+        } catch {
+          continue;
+        }
+        if (hasUseClientDirective(childSource)) continue;
+
+        await visit(resolved, childSource);
+      }
+    };
+
+    await visit(routeModule, routeSource);
+    return modules;
+  }
+
+  private async resolveRouteOwnedImportModulePath(
+    rootDir: string,
+    importerModule: string,
+    specifier: string,
+  ): Promise<string | null> {
+    const normalized = specifier.replace(/\\/g, "/");
+    let basePath: string | null = null;
+
+    if (normalized.startsWith("@/") || normalized.startsWith("~/")) {
+      basePath = join(rootDir, "src", normalized.slice(2));
+    } else if (normalized.startsWith("./") || normalized.startsWith("../")) {
+      basePath = join(rootDir, dirname(importerModule), normalized);
+    }
+
+    if (!basePath) return null;
+
+    for (const candidate of expandRouteImportCandidates(basePath)) {
+      try {
+        const entry = await stat(candidate);
+        if (entry.isFile()) {
+          return relative(rootDir, candidate).replace(/\\/g, "/");
+        }
+      } catch {
+        // Try the next candidate.
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 레이아웃 체인 해결
    */
   private resolveLayoutChain(
     segments: ScannedFile["segments"],
@@ -860,7 +860,7 @@ export function synthesizeLocaleRoutes(
   return out;
 }
 
-function prefixRouteWithLocale(route: FSRouteConfig, locale: string): FSRouteConfig {
+function prefixRouteWithLocale(route: FSRouteConfig, locale: string): FSRouteConfig {
   const prefixedPattern = route.pattern === "/"
     ? `/${locale}`
     : `/${locale}${route.pattern.startsWith("/") ? route.pattern : `/${route.pattern}`}`;
@@ -876,26 +876,26 @@ function prefixRouteWithLocale(route: FSRouteConfig, locale: string): FSRouteCon
       { raw: locale, type: "static" },
       ...route.segments,
     ],
-  };
-}
-
-function expandRouteImportCandidates(basePath: string): string[] {
-  if (/\.[cm]?[jt]sx?$/.test(basePath)) return [basePath];
-  return [
-    `${basePath}.tsx`,
-    `${basePath}.ts`,
-    `${basePath}.jsx`,
-    `${basePath}.js`,
-    join(basePath, "index.tsx"),
-    join(basePath, "index.ts"),
-    join(basePath, "index.jsx"),
-    join(basePath, "index.js"),
-  ];
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Factory Function
-// ═══════════════════════════════════════════════════════════════════════════
+  };
+}
+
+function expandRouteImportCandidates(basePath: string): string[] {
+  if (/\.[cm]?[jt]sx?$/.test(basePath)) return [basePath];
+  return [
+    `${basePath}.tsx`,
+    `${basePath}.ts`,
+    `${basePath}.jsx`,
+    `${basePath}.js`,
+    join(basePath, "index.tsx"),
+    join(basePath, "index.ts"),
+    join(basePath, "index.jsx"),
+    join(basePath, "index.js"),
+  ];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Factory Function
+// ═══════════════════════════════════════════════════════════════════════════
 
 /**
  * 스캐너 생성 팩토리 함수