@mandujs/core 0.3.2 → 0.3.3

package/src/filling/filling.ts

@@ -1,234 +1,256 @@
-/**
- * Mandu Filling - 만두소 🥟
- * 체이닝 API로 비즈니스 로직 정의
- */
-
-import { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
-
-/** Handler function type */
-export type Handler = (ctx: ManduContext) => Response | Promise<Response>;
-
-/** Guard function type - returns next() or Response */
-export type Guard = (ctx: ManduContext) => symbol | Response | Promise<symbol | Response>;
-
-/** HTTP methods */
-export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
-
-interface FillingConfig {
-  handlers: Map<HttpMethod, Handler>;
-  guards: Guard[];
-  methodGuards: Map<HttpMethod, Guard[]>;
-}
-
-/**
- * Mandu Filling Builder
- * @example
- * ```typescript
- * export default Mandu.filling()
- *   .guard(authCheck)
- *   .get(ctx => ctx.ok({ message: 'Hello!' }))
- *   .post(ctx => ctx.created({ id: 1 }))
- * ```
- */
-export class ManduFilling {
-  private config: FillingConfig = {
-    handlers: new Map(),
-    guards: [],
-    methodGuards: new Map(),
-  };
-
-  // ============================================
-  // 🥟 HTTP Method Handlers
-  // ============================================
-
-  /** Handle GET requests */
-  get(handler: Handler): this {
-    this.config.handlers.set("GET", handler);
-    return this;
-  }
-
-  /** Handle POST requests */
-  post(handler: Handler): this {
-    this.config.handlers.set("POST", handler);
-    return this;
-  }
-
-  /** Handle PUT requests */
-  put(handler: Handler): this {
-    this.config.handlers.set("PUT", handler);
-    return this;
-  }
-
-  /** Handle PATCH requests */
-  patch(handler: Handler): this {
-    this.config.handlers.set("PATCH", handler);
-    return this;
-  }
-
-  /** Handle DELETE requests */
-  delete(handler: Handler): this {
-    this.config.handlers.set("DELETE", handler);
-    return this;
-  }
-
-  /** Handle HEAD requests */
-  head(handler: Handler): this {
-    this.config.handlers.set("HEAD", handler);
-    return this;
-  }
-
-  /** Handle OPTIONS requests */
-  options(handler: Handler): this {
-    this.config.handlers.set("OPTIONS", handler);
-    return this;
-  }
-
-  /** Handle all methods with single handler */
-  all(handler: Handler): this {
-    const methods: HttpMethod[] = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
-    methods.forEach((method) => this.config.handlers.set(method, handler));
-    return this;
-  }
-
-  // ============================================
-  // 🥟 Guards (만두 찜기)
-  // ============================================
-
-  /**
-   * Add guard for all methods or specific methods
-   * @example
-   * .guard(authCheck)                    // all methods
-   * .guard(authCheck, 'POST', 'PUT')     // specific methods
-   */
-  guard(guardFn: Guard, ...methods: HttpMethod[]): this {
-    if (methods.length === 0) {
-      // Apply to all methods
-      this.config.guards.push(guardFn);
-    } else {
-      // Apply to specific methods
-      methods.forEach((method) => {
-        const guards = this.config.methodGuards.get(method) || [];
-        guards.push(guardFn);
-        this.config.methodGuards.set(method, guards);
-      });
-    }
-    return this;
-  }
-
-  /** Alias for guard - more semantic for middleware */
-  use(guardFn: Guard, ...methods: HttpMethod[]): this {
-    return this.guard(guardFn, ...methods);
-  }
-
-  // ============================================
-  // 🥟 Execution
-  // ============================================
-
-  /**
-   * Handle incoming request
-   * Called by generated route handler
-   */
-  async handle(request: Request, params: Record<string, string> = {}): Promise<Response> {
-    const ctx = new ManduContext(request, params);
-    const method = request.method.toUpperCase() as HttpMethod;
-
-    try {
-      // Run global guards
-      for (const guard of this.config.guards) {
-        const result = await guard(ctx);
-        if (result !== NEXT_SYMBOL) {
-          return result as Response;
-        }
-        if (!ctx.shouldContinue) {
-          return ctx.getResponse()!;
-        }
-      }
-
-      // Run method-specific guards
-      const methodGuards = this.config.methodGuards.get(method) || [];
-      for (const guard of methodGuards) {
-        const result = await guard(ctx);
-        if (result !== NEXT_SYMBOL) {
-          return result as Response;
-        }
-        if (!ctx.shouldContinue) {
-          return ctx.getResponse()!;
-        }
-      }
-
-      // Get handler for method
-      const handler = this.config.handlers.get(method);
-      if (!handler) {
-        return ctx.json(
-          {
-            status: "error",
-            message: `Method ${method} not allowed`,
-            allowed: Array.from(this.config.handlers.keys()),
-          },
-          405
-        );
-      }
-
-      // Execute handler
-      return await handler(ctx);
-    } catch (error) {
-      // Handle validation errors
-      if (error instanceof ValidationError) {
-        return ctx.json(
-          {
-            status: "error",
-            message: "Validation failed",
-            errors: error.errors,
-          },
-          400
-        );
-      }
-
-      // Handle other errors
-      console.error(`[Mandu] Handler error:`, error);
-      return ctx.fail(
-        error instanceof Error ? error.message : "Internal Server Error"
-      );
-    }
-  }
-
-  /**
-   * Get list of registered methods
-   */
-  getMethods(): HttpMethod[] {
-    return Array.from(this.config.handlers.keys());
-  }
-
-  /**
-   * Check if method is registered
-   */
-  hasMethod(method: HttpMethod): boolean {
-    return this.config.handlers.has(method);
-  }
-}
-
-/**
- * Mandu namespace with factory methods
- */
-export const Mandu = {
-  /**
-   * Create a new filling (slot logic builder)
-   * @example
-   * ```typescript
-   * import { Mandu } from '@mandujs/core'
-   *
-   * export default Mandu.filling()
-   *   .get(ctx => ctx.ok({ message: 'Hello!' }))
-   * ```
-   */
-  filling(): ManduFilling {
-    return new ManduFilling();
-  },
-
-  /**
-   * Create context manually (for testing)
-   */
-  context(request: Request, params?: Record<string, string>): ManduContext {
-    return new ManduContext(request, params);
-  },
-};
+/**
+ * Mandu Filling - 만두소 🥟
+ * 체이닝 API로 비즈니스 로직 정의
+ */
+
+import { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
+import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
+
+/** Handler function type */
+export type Handler = (ctx: ManduContext) => Response | Promise<Response>;
+
+/** Guard function type - returns next() or Response */
+export type Guard = (ctx: ManduContext) => symbol | Response | Promise<symbol | Response>;
+
+/** HTTP methods */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+interface FillingConfig {
+  handlers: Map<HttpMethod, Handler>;
+  guards: Guard[];
+  methodGuards: Map<HttpMethod, Guard[]>;
+}
+
+/**
+ * Mandu Filling Builder
+ * @example
+ * ```typescript
+ * export default Mandu.filling()
+ *   .guard(authCheck)
+ *   .get(ctx => ctx.ok({ message: 'Hello!' }))
+ *   .post(ctx => ctx.created({ id: 1 }))
+ * ```
+ */
+export class ManduFilling {
+  private config: FillingConfig = {
+    handlers: new Map(),
+    guards: [],
+    methodGuards: new Map(),
+  };
+
+  // ============================================
+  // 🥟 HTTP Method Handlers
+  // ============================================
+
+  /** Handle GET requests */
+  get(handler: Handler): this {
+    this.config.handlers.set("GET", handler);
+    return this;
+  }
+
+  /** Handle POST requests */
+  post(handler: Handler): this {
+    this.config.handlers.set("POST", handler);
+    return this;
+  }
+
+  /** Handle PUT requests */
+  put(handler: Handler): this {
+    this.config.handlers.set("PUT", handler);
+    return this;
+  }
+
+  /** Handle PATCH requests */
+  patch(handler: Handler): this {
+    this.config.handlers.set("PATCH", handler);
+    return this;
+  }
+
+  /** Handle DELETE requests */
+  delete(handler: Handler): this {
+    this.config.handlers.set("DELETE", handler);
+    return this;
+  }
+
+  /** Handle HEAD requests */
+  head(handler: Handler): this {
+    this.config.handlers.set("HEAD", handler);
+    return this;
+  }
+
+  /** Handle OPTIONS requests */
+  options(handler: Handler): this {
+    this.config.handlers.set("OPTIONS", handler);
+    return this;
+  }
+
+  /** Handle all methods with single handler */
+  all(handler: Handler): this {
+    const methods: HttpMethod[] = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+    methods.forEach((method) => this.config.handlers.set(method, handler));
+    return this;
+  }
+
+  // ============================================
+  // 🥟 Guards (만두 찜기)
+  // ============================================
+
+  /**
+   * Add guard for all methods or specific methods
+   * @example
+   * .guard(authCheck)                    // all methods
+   * .guard(authCheck, 'POST', 'PUT')     // specific methods
+   */
+  guard(guardFn: Guard, ...methods: HttpMethod[]): this {
+    if (methods.length === 0) {
+      // Apply to all methods
+      this.config.guards.push(guardFn);
+    } else {
+      // Apply to specific methods
+      methods.forEach((method) => {
+        const guards = this.config.methodGuards.get(method) || [];
+        guards.push(guardFn);
+        this.config.methodGuards.set(method, guards);
+      });
+    }
+    return this;
+  }
+
+  /** Alias for guard - more semantic for middleware */
+  use(guardFn: Guard, ...methods: HttpMethod[]): this {
+    return this.guard(guardFn, ...methods);
+  }
+
+  // ============================================
+  // 🥟 Execution
+  // ============================================
+
+  /**
+   * Handle incoming request
+   * Called by generated route handler
+   * @param request The incoming request
+   * @param params URL path parameters
+   * @param routeContext Route context for error reporting
+   */
+  async handle(
+    request: Request,
+    params: Record<string, string> = {},
+    routeContext?: { routeId: string; pattern: string }
+  ): Promise<Response> {
+    const ctx = new ManduContext(request, params);
+    const method = request.method.toUpperCase() as HttpMethod;
+
+    try {
+      // Run global guards
+      for (const guard of this.config.guards) {
+        const result = await guard(ctx);
+        if (result !== NEXT_SYMBOL) {
+          return result as Response;
+        }
+        if (!ctx.shouldContinue) {
+          return ctx.getResponse()!;
+        }
+      }
+
+      // Run method-specific guards
+      const methodGuards = this.config.methodGuards.get(method) || [];
+      for (const guard of methodGuards) {
+        const result = await guard(ctx);
+        if (result !== NEXT_SYMBOL) {
+          return result as Response;
+        }
+        if (!ctx.shouldContinue) {
+          return ctx.getResponse()!;
+        }
+      }
+
+      // Get handler for method
+      const handler = this.config.handlers.get(method);
+      if (!handler) {
+        return ctx.json(
+          {
+            status: "error",
+            message: `Method ${method} not allowed`,
+            allowed: Array.from(this.config.handlers.keys()),
+          },
+          405
+        );
+      }
+
+      // Execute handler
+      return await handler(ctx);
+    } catch (error) {
+      // Handle validation errors with enhanced error format
+      if (error instanceof ValidationError) {
+        return ctx.json(
+          {
+            errorType: "LOGIC_ERROR",
+            code: ErrorCode.SLOT_VALIDATION_ERROR,
+            message: "Validation failed",
+            summary: "입력 검증 실패 - 요청 데이터 확인 필요",
+            fix: {
+              file: routeContext ? `spec/slots/${routeContext.routeId}.slot.ts` : "spec/slots/",
+              suggestion: "요청 데이터가 스키마와 일치하는지 확인하세요",
+            },
+            route: routeContext,
+            errors: error.errors,
+            timestamp: new Date().toISOString(),
+          },
+          400
+        );
+      }
+
+      // Handle other errors with error classification
+      const classifier = new ErrorClassifier(null, routeContext);
+      const manduError = classifier.classify(error);
+
+      console.error(`[Mandu] ${manduError.errorType}:`, manduError.message);
+
+      const response = formatErrorResponse(manduError, {
+        isDev: process.env.NODE_ENV !== "production",
+      });
+
+      return ctx.json(response, 500);
+    }
+  }
+
+  /**
+   * Get list of registered methods
+   */
+  getMethods(): HttpMethod[] {
+    return Array.from(this.config.handlers.keys());
+  }
+
+  /**
+   * Check if method is registered
+   */
+  hasMethod(method: HttpMethod): boolean {
+    return this.config.handlers.has(method);
+  }
+}
+
+/**
+ * Mandu namespace with factory methods
+ */
+export const Mandu = {
+  /**
+   * Create a new filling (slot logic builder)
+   * @example
+   * ```typescript
+   * import { Mandu } from '@mandujs/core'
+   *
+   * export default Mandu.filling()
+   *   .get(ctx => ctx.ok({ message: 'Hello!' }))
+   * ```
+   */
+  filling(): ManduFilling {
+    return new ManduFilling();
+  },
+
+  /**
+   * Create context manually (for testing)
+   */
+  context(request: Request, params?: Record<string, string>): ManduContext {
+    return new ManduContext(request, params);
+  },
+};

package/src/filling/index.ts

@@ -1,7 +1,7 @@
-/**
- * Mandu Filling Module - 만두소 🥟
- */
-
-export { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
-export { ManduFilling, Mandu } from "./filling";
-export type { Handler, Guard, HttpMethod } from "./filling";
+/**
+ * Mandu Filling Module - 만두소 🥟
+ */
+
+export { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
+export { ManduFilling, Mandu } from "./filling";
+export type { Handler, Guard, HttpMethod } from "./filling";

package/src/generator/generate.ts

@@ -1,5 +1,6 @@
 import type { RoutesManifest, RouteSpec } from "../spec/schema";
 import { generateApiHandler, generatePageComponent, generateSlotLogic } from "./templates";
+import { computeHash } from "../spec/lock";
 import path from "path";
 import fs from "fs/promises";
 
@@ -20,10 +21,64 @@ export interface GenerateResult {
   errors: string[];
 }
 
+/**
+ * Spec 파일 정보
+ */
+export interface SpecSource {
+  /** Spec 파일 경로 */
+  path: string;
+  /** SHA256 해시 */
+  hash: string;
+}
+
+/**
+ * Spec 내 라우트 위치 정보
+ */
+export interface SpecLocation {
+  /** Spec 파일 경로 */
+  file: string;
+  /** routes 배열 내 인덱스 */
+  routeIndex: number;
+  /** JSON 경로 (예: "routes[0]") */
+  jsonPath: string;
+}
+
+/**
+ * Slot 파일 매핑 정보
+ */
+export interface SlotMapping {
+  /** Slot 파일 경로 */
+  slotPath: string;
+}
+
+/**
+ * Generated 파일 엔트리
+ */
+export interface GeneratedFileEntry {
+  /** 라우트 ID */
+  routeId: string;
+  /** 라우트 종류 */
+  kind: "api" | "page";
+  /** Spec 내 위치 */
+  specLocation: SpecLocation;
+  /** Slot 매핑 (있는 경우) */
+  slotMapping?: SlotMapping;
+}
+
+/**
+ * Generated Map 구조
+ */
 export interface GeneratedMap {
+  /** 버전 */
   version: number;
+  /** 생성 시각 */
   generatedAt: string;
-  files: Record<string, { routeId: string; kind: string }>;
+  /** Spec 소스 정보 */
+  specSource: SpecSource;
+  /** 생성된 파일 매핑 */
+  files: Record<string, GeneratedFileEntry>;
+  /** 프레임워크 내부 파일 패턴 */
+  frameworkPaths: string[];
 }
 
 async function ensureDir(dirPath: string): Promise<void> {
@@ -66,14 +121,37 @@ export async function generateRoutes(
   const generatedMap: GeneratedMap = {
     version: manifest.version,
     generatedAt: new Date().toISOString(),
+    specSource: {
+      path: "spec/routes.manifest.json",
+      hash: computeHash(manifest),
+    },
     files: {},
+    frameworkPaths: [
+      "@mandujs/core",
+      "packages/core/src",
+      "node_modules/@mandujs",
+    ],
   };
 
   const expectedServerFiles = new Set<string>();
   const expectedWebFiles = new Set<string>();
 
-  for (const route of manifest.routes) {
+  for (let routeIndex = 0; routeIndex < manifest.routes.length; routeIndex++) {
+    const route = manifest.routes[routeIndex];
+
     try {
+      // Spec 위치 정보
+      const specLocation: SpecLocation = {
+        file: "spec/routes.manifest.json",
+        routeIndex,
+        jsonPath: `routes[${routeIndex}]`,
+      };
+
+      // Slot 매핑 정보 (있는 경우)
+      const slotMapping: SlotMapping | undefined = route.slotModule
+        ? { slotPath: route.slotModule }
+        : undefined;
+
       // Server handler
       const serverFileName = `${route.id}.route.ts`;
       const serverFilePath = path.join(serverRoutesDir, serverFileName);
@@ -85,7 +163,9 @@ export async function generateRoutes(
 
       generatedMap.files[`apps/server/generated/routes/${serverFileName}`] = {
         routeId: route.id,
-        kind: route.kind,
+        kind: route.kind as "api" | "page",
+        specLocation,
+        slotMapping,
       };
 
       // Slot file (only if slotModule is specified)
@@ -119,6 +199,8 @@ export async function generateRoutes(
         generatedMap.files[`apps/web/generated/routes/${webFileName}`] = {
           routeId: route.id,
           kind: route.kind,
+          specLocation,
+          slotMapping,
         };
       }
     } catch (error) {

package/src/generator/index.ts

@@ -1,2 +1,2 @@
-export * from "./generate";
-export * from "./templates";
+export * from "./generate";
+export * from "./templates";