@mandujs/core 0.9.31 → 0.9.37

package/src/router/fs-types.ts

@@ -0,0 +1,278 @@
+/**
+ * FS Routes Types
+ *
+ * 파일 시스템 기반 라우팅 타입 정의
+ *
+ * @module router/fs-types
+ */
+
+import type { RouteKind, HydrationConfig, HttpMethod } from "../spec/schema";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Segment Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 라우트 세그먼트 타입
+ */
+export type SegmentType =
+  | "static" // 정적 세그먼트 (예: "blog")
+  | "dynamic" // 동적 세그먼트 (예: "[slug]")
+  | "catchAll" // Catch-all 세그먼트 (예: "[...path]")
+  | "optionalCatchAll" // Optional catch-all (예: "[[...path]]")
+  | "group"; // 라우트 그룹 (예: "(marketing)")
+
+/**
+ * 파싱된 라우트 세그먼트
+ */
+export interface RouteSegment {
+  /** 원본 세그먼트 이름 */
+  raw: string;
+
+  /** 세그먼트 타입 */
+  type: SegmentType;
+
+  /** 파라미터 이름 (동적 세그먼트의 경우) */
+  paramName?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// File Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 스캔된 파일 타입
+ */
+export type ScannedFileType =
+  | "page" // page.tsx - 페이지 컴포넌트
+  | "layout" // layout.tsx - 레이아웃
+  | "route" // route.ts - API 핸들러
+  | "loading" // loading.tsx - 로딩 UI
+  | "error" // error.tsx - 에러 UI
+  | "not-found" // not-found.tsx - 404 UI
+  | "island"; // *.island.tsx - Island 컴포넌트
+
+/**
+ * 스캔된 파일 정보
+ */
+export interface ScannedFile {
+  /** 절대 경로 */
+  absolutePath: string;
+
+  /** 라우트 루트 기준 상대 경로 */
+  relativePath: string;
+
+  /** 파일 타입 */
+  type: ScannedFileType;
+
+  /** 파싱된 경로 세그먼트 */
+  segments: RouteSegment[];
+
+  /** 파일 확장자 */
+  extension: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Route Config Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * FS Routes에서 생성된 라우트 설정
+ */
+export interface FSRouteConfig {
+  /** 라우트 ID (자동 생성) */
+  id: string;
+
+  /** 파싱된 경로 세그먼트 */
+  segments: RouteSegment[];
+
+  /** URL 패턴 (예: "/blog/:slug") */
+  pattern: string;
+
+  /** 라우트 종류 */
+  kind: RouteKind;
+
+  /** HTTP 메서드 (API 라우트용) */
+  methods?: HttpMethod[];
+
+  /** 페이지 컴포넌트 모듈 경로 */
+  componentModule?: string;
+
+  /** API 핸들러 모듈 경로 */
+  module: string;
+
+  /** Island 컴포넌트 모듈 경로 */
+  clientModule?: string;
+
+  /** 적용할 레이아웃 체인 */
+  layoutChain: string[];
+
+  /** 로딩 UI 모듈 경로 */
+  loadingModule?: string;
+
+  /** 에러 UI 모듈 경로 */
+  errorModule?: string;
+
+  /** Hydration 설정 */
+  hydration?: HydrationConfig;
+
+  /** 원본 파일 경로 */
+  sourceFile: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scanner Config Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * FS Routes 스캐너 설정
+ */
+export interface FSScannerConfig {
+  /** 라우트 루트 디렉토리 (기본: "app") */
+  routesDir: string;
+
+  /** 지원 확장자 (기본: [".tsx", ".ts", ".jsx", ".js"]) */
+  extensions: string[];
+
+  /** 제외 패턴 (glob) */
+  exclude: string[];
+
+  /** Island 파일 접미사 (기본: ".island") */
+  islandSuffix: string;
+
+  /** 레거시 매니페스트 경로 (병합용) */
+  legacyManifestPath?: string;
+
+  /** 레거시 매니페스트와 병합 여부 */
+  mergeWithLegacy: boolean;
+}
+
+/**
+ * 기본 스캐너 설정
+ */
+export const DEFAULT_SCANNER_CONFIG: FSScannerConfig = {
+  routesDir: "app",
+  extensions: [".tsx", ".ts", ".jsx", ".js"],
+  exclude: [
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/_*/**", // 비공개 폴더
+    "**/node_modules/**",
+  ],
+  islandSuffix: ".island",
+  legacyManifestPath: "spec/routes.manifest.json",
+  mergeWithLegacy: true,
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scan Result Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 디렉토리 스캔 결과
+ */
+export interface ScanResult {
+  /** 스캔된 파일 목록 */
+  files: ScannedFile[];
+
+  /** 생성된 라우트 설정 */
+  routes: FSRouteConfig[];
+
+  /** 에러 목록 */
+  errors: ScanError[];
+
+  /** 스캔 통계 */
+  stats: ScanStats;
+}
+
+/**
+ * 스캔 에러
+ */
+export interface ScanError {
+  /** 에러 타입 */
+  type: "invalid_segment" | "duplicate_route" | "file_read_error" | "pattern_conflict";
+
+  /** 에러 메시지 */
+  message: string;
+
+  /** 관련 파일 경로 */
+  filePath?: string;
+
+  /** 충돌하는 파일 경로 (duplicate_route의 경우) */
+  conflictsWith?: string;
+}
+
+/**
+ * 스캔 통계
+ */
+export interface ScanStats {
+  /** 총 스캔 파일 수 */
+  totalFiles: number;
+
+  /** 페이지 수 */
+  pageCount: number;
+
+  /** API 라우트 수 */
+  apiCount: number;
+
+  /** 레이아웃 수 */
+  layoutCount: number;
+
+  /** Island 수 */
+  islandCount: number;
+
+  /** 스캔 소요 시간 (ms) */
+  scanTime: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Pattern Constants
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 파일명 패턴
+ */
+export const FILE_PATTERNS = {
+  /** 페이지 파일 */
+  page: /^page\.(tsx?|jsx?)$/,
+
+  /** 레이아웃 파일 */
+  layout: /^layout\.(tsx?|jsx?)$/,
+
+  /** API 라우트 파일 */
+  route: /^route\.(ts|js)$/,
+
+  /** 로딩 UI 파일 */
+  loading: /^loading\.(tsx?|jsx?)$/,
+
+  /** 에러 UI 파일 */
+  error: /^error\.(tsx?|jsx?)$/,
+
+  /** 404 파일 */
+  notFound: /^not-found\.(tsx?|jsx?)$/,
+
+  /** Island 파일 */
+  island: /\.island\.(tsx?|jsx?)$/,
+} as const;
+
+/**
+ * 세그먼트 패턴
+ */
+export const SEGMENT_PATTERNS = {
+  /** 동적 세그먼트: [param] */
+  dynamic: /^\[([^\[\]\.]+)\]$/,
+
+  /** Catch-all: [...param] */
+  catchAll: /^\[\.\.\.([^\[\]]+)\]$/,
+
+  /** Optional catch-all: [[...param]] */
+  optionalCatchAll: /^\[\[\.\.\.([^\[\]]+)\]\]$/,
+
+  /** 라우트 그룹: (name) */
+  group: /^\(([^()]+)\)$/,
+
+  /** 비공개 폴더: _name */
+  private: /^_/,
+} as const;

package/src/router/index.ts

@@ -0,0 +1,81 @@
+/**
+ * FS Routes Module
+ *
+ * 파일 시스템 기반 라우팅 시스템
+ *
+ * @module router
+ *
+ * @example
+ * ```typescript
+ * import { scanRoutes, generateManifest, watchFSRoutes } from "@mandujs/core/router";
+ *
+ * // 간편 스캔
+ * const result = await scanRoutes("/path/to/project");
+ * console.log(result.routes);
+ *
+ * // 매니페스트 생성
+ * const { manifest } = await generateManifest("/path/to/project", {
+ *   outputPath: ".mandu/manifest.json"
+ * });
+ *
+ * // 감시 모드
+ * const watcher = await watchFSRoutes("/path/to/project", {
+ *   onChange: (result) => console.log("Routes updated!")
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  // Segment types
+  SegmentType,
+  RouteSegment,
+
+  // File types
+  ScannedFileType,
+  ScannedFile,
+
+  // Route config
+  FSRouteConfig,
+
+  // Scanner config
+  FSScannerConfig,
+
+  // Results
+  ScanResult,
+  ScanError,
+  ScanStats,
+} from "./fs-types";
+
+export { DEFAULT_SCANNER_CONFIG, FILE_PATTERNS, SEGMENT_PATTERNS } from "./fs-types";
+
+// Pattern utilities
+export {
+  parseSegment,
+  parseSegments,
+  segmentsToPattern,
+  pathToPattern,
+  detectFileType,
+  isPrivateFolder,
+  isGroupFolder,
+  generateRouteId,
+  calculateRoutePriority,
+  sortRoutesByPriority,
+  validateSegments,
+  patternsConflict,
+} from "./fs-patterns";
+
+// Scanner
+export { FSScanner, createFSScanner, scanRoutes } from "./fs-scanner";
+
+// Generator
+export type { GenerateResult, GenerateOptions, RouteChangeCallback, FSRoutesWatcher } from "./fs-routes";
+
+export {
+  fsRouteToRouteSpec,
+  scanResultToManifest,
+  mergeManifests,
+  generateManifest,
+  watchFSRoutes,
+  formatRoutesForCLI,
+} from "./fs-routes";

package/src/runtime/boundary.tsx

@@ -0,0 +1,232 @@
+/**
+ * Mandu Boundary Components
+ *
+ * Loading (Suspense) 및 Error (ErrorBoundary) UI 래퍼
+ *
+ * @module runtime/boundary
+ */
+
+import React, { Suspense, Component, type ReactNode, type ErrorInfo } from "react";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface LoadingBoundaryProps {
+  /** 로딩 중 표시할 컴포넌트 */
+  fallback: ReactNode;
+  /** 자식 컴포넌트 */
+  children: ReactNode;
+}
+
+export interface ErrorBoundaryProps {
+  /** 에러 발생 시 표시할 컴포넌트 */
+  fallback: React.ComponentType<ErrorFallbackProps>;
+  /** 자식 컴포넌트 */
+  children: ReactNode;
+  /** 에러 발생 시 콜백 */
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+
+export interface ErrorFallbackProps {
+  /** 발생한 에러 */
+  error: Error;
+  /** 에러 정보 */
+  errorInfo?: ErrorInfo;
+  /** 리셋 함수 (에러 상태 초기화) */
+  resetError: () => void;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+  errorInfo: ErrorInfo | null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Loading Boundary (Suspense Wrapper)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Loading Boundary - Suspense 래퍼
+ *
+ * @example
+ * ```tsx
+ * <LoadingBoundary fallback={<Loading />}>
+ *   <AsyncComponent />
+ * </LoadingBoundary>
+ * ```
+ */
+export function LoadingBoundary({ fallback, children }: LoadingBoundaryProps): JSX.Element {
+  return <Suspense fallback={fallback}>{children}</Suspense>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Error Boundary (Class Component)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Error Boundary - 에러 캐치 및 fallback UI 표시
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary fallback={ErrorFallback}>
+ *   <RiskyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = {
+      hasError: false,
+      error: null,
+      errorInfo: null,
+    };
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    this.setState({ errorInfo });
+    this.props.onError?.(error, errorInfo);
+  }
+
+  resetError = (): void => {
+    this.setState({
+      hasError: false,
+      error: null,
+      errorInfo: null,
+    });
+  };
+
+  render(): ReactNode {
+    const { hasError, error, errorInfo } = this.state;
+    const { fallback: Fallback, children } = this.props;
+
+    if (hasError && error) {
+      return (
+        <Fallback
+          error={error}
+          errorInfo={errorInfo ?? undefined}
+          resetError={this.resetError}
+        />
+      );
+    }
+
+    return children;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Default Fallback Components
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 기본 로딩 컴포넌트
+ */
+export function DefaultLoading(): JSX.Element {
+  return (
+    <div
+      style={{
+        display: "flex",
+        justifyContent: "center",
+        alignItems: "center",
+        padding: "2rem",
+        color: "#666",
+      }}
+    >
+      <div>Loading...</div>
+    </div>
+  );
+}
+
+/**
+ * 기본 에러 컴포넌트
+ */
+export function DefaultError({ error, resetError }: ErrorFallbackProps): JSX.Element {
+  return (
+    <div
+      style={{
+        padding: "2rem",
+        backgroundColor: "#fff3f3",
+        border: "1px solid #ffcccc",
+        borderRadius: "8px",
+        margin: "1rem",
+      }}
+    >
+      <h2 style={{ color: "#cc0000", marginTop: 0 }}>Something went wrong</h2>
+      <pre
+        style={{
+          backgroundColor: "#f5f5f5",
+          padding: "1rem",
+          borderRadius: "4px",
+          overflow: "auto",
+          fontSize: "0.875rem",
+        }}
+      >
+        {error.message}
+      </pre>
+      <button
+        onClick={resetError}
+        style={{
+          marginTop: "1rem",
+          padding: "0.5rem 1rem",
+          backgroundColor: "#cc0000",
+          color: "white",
+          border: "none",
+          borderRadius: "4px",
+          cursor: "pointer",
+        }}
+      >
+        Try again
+      </button>
+    </div>
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Combined Boundary
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface PageBoundaryProps {
+  /** 로딩 컴포넌트 (옵션) */
+  loadingComponent?: ReactNode;
+  /** 에러 컴포넌트 (옵션) */
+  errorComponent?: React.ComponentType<ErrorFallbackProps>;
+  /** 자식 컴포넌트 */
+  children: ReactNode;
+  /** 에러 발생 시 콜백 */
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+
+/**
+ * Page Boundary - Loading + Error 래퍼
+ *
+ * @example
+ * ```tsx
+ * <PageBoundary
+ *   loadingComponent={<CustomLoading />}
+ *   errorComponent={CustomError}
+ * >
+ *   <PageContent />
+ * </PageBoundary>
+ * ```
+ */
+export function PageBoundary({
+  loadingComponent,
+  errorComponent,
+  children,
+  onError,
+}: PageBoundaryProps): JSX.Element {
+  const LoadingFallback = loadingComponent ?? <DefaultLoading />;
+  const ErrorFallback = errorComponent ?? DefaultError;
+
+  return (
+    <ErrorBoundary fallback={ErrorFallback} onError={onError}>
+      <LoadingBoundary fallback={LoadingFallback}>{children}</LoadingBoundary>
+    </ErrorBoundary>
+  );
+}

package/src/runtime/index.ts

@@ -7,3 +7,4 @@ export * from "./compose";
 export * from "./lifecycle";
 export * from "./trace";
 export * from "./logger";
+export * from "./boundary";

package/src/runtime/router.test.ts

@@ -138,6 +138,41 @@ describe("Wildcard Matching", () => {
     expect(result!.params).toEqual({ [WILDCARD_PARAM_KEY]: "a/b/c" });
   });
 
+  test("matches named wildcard with remaining path", () => {
+    const router = createRouter([
+      makeRoute("docs", "/docs/:path*"),
+    ]);
+
+    const result = router.match("/docs/a/b/c");
+
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("docs");
+    expect(result!.params).toEqual({ path: "a/b/c" });
+  });
+
+  test("optional wildcard matches base path without param", () => {
+    const router = createRouter([
+      makeRoute("docs", "/docs/:path*?"),
+    ]);
+
+    const result = router.match("/docs");
+
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("docs");
+    expect(result!.params).toEqual({});
+  });
+
+  test("optional wildcard matches with remaining path", () => {
+    const router = createRouter([
+      makeRoute("docs", "/docs/:path*?"),
+    ]);
+
+    const result = router.match("/docs/intro");
+
+    expect(result).not.toBeNull();
+    expect(result!.params).toEqual({ path: "intro" });
+  });
+
   test("wildcard with single segment", () => {
     const router = createRouter([
       makeRoute("docs", "/docs/*"),
@@ -308,6 +343,24 @@ describe("Validation Errors", () => {
       expect((e as RouterError).code).toBe("WILDCARD_NOT_LAST");
     }
   });
+
+  test("throws ROUTE_CONFLICT for wildcard conflicts", () => {
+    expect(() => {
+      createRouter([
+        makeRoute("files-legacy", "/files/*"),
+        makeRoute("files-named", "/files/:path*"),
+      ]);
+    }).toThrow(RouterError);
+
+    try {
+      createRouter([
+        makeRoute("files-legacy", "/files/*"),
+        makeRoute("files-named", "/files/:path*"),
+      ]);
+    } catch (e) {
+      expect((e as RouterError).code).toBe("ROUTE_CONFLICT");
+    }
+  });
 });
 
 // ═══════════════════════════════════════════════════════════════════════════