@mandujs/core 0.9.39 → 0.9.40

package/src/contract/types.ts

@@ -11,10 +11,22 @@ import type {
   MethodRequestSchema,
 } from "./schema";
 
-/**
- * Extract inferred type from Zod schema
- */
-type InferZod<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
+/**
+ * Extract inferred type from Zod schema
+ */
+type InferZod<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
+
+/**
+ * Extract inferred type from response schema (supports ResponseSchemaWithExamples)
+ */
+export type InferResponseSchema<T> =
+  T extends { schema: infer S }
+    ? S extends z.ZodTypeAny
+      ? z.infer<S>
+      : never
+    : T extends z.ZodTypeAny
+      ? z.infer<T>
+      : never;
 
 /**
  * Infer request schema types for a single method
@@ -38,9 +50,9 @@ type InferContractRequest<T extends ContractRequestSchema> = {
 /**
  * Infer all response schemas
  */
-type InferContractResponse<T extends ContractResponseSchema> = {
-  [K in keyof T]: T[K] extends z.ZodTypeAny ? z.infer<T[K]> : never;
-};
+type InferContractResponse<T extends ContractResponseSchema> = {
+  [K in keyof T]: InferResponseSchema<T[K]>;
+};
 
 /**
  * Infer full contract types
@@ -103,22 +115,34 @@ export type InferBody<
 /**
  * Extract params type for a specific method
  */
-export type InferParams<
-  T extends ContractSchema,
-  M extends keyof T["request"]
-> = T["request"][M] extends MethodRequestSchema
-  ? T["request"][M]["params"] extends z.ZodTypeAny
-    ? z.infer<T["request"][M]["params"]>
-    : undefined
-  : undefined;
+export type InferParams<
+  T extends ContractSchema,
+  M extends keyof T["request"]
+> = T["request"][M] extends MethodRequestSchema
+  ? T["request"][M]["params"] extends z.ZodTypeAny
+    ? z.infer<T["request"][M]["params"]>
+    : undefined
+  : undefined;
+
+/**
+ * Extract headers type for a specific method
+ */
+export type InferHeaders<
+  T extends ContractSchema,
+  M extends keyof T["request"]
+> = T["request"][M] extends MethodRequestSchema
+  ? T["request"][M]["headers"] extends z.ZodTypeAny
+    ? z.infer<T["request"][M]["headers"]>
+    : undefined
+  : undefined;
 
 /**
  * Extract response type for a specific status code
  */
-export type InferResponse<
-  T extends ContractSchema,
-  S extends keyof T["response"]
-> = T["response"][S] extends z.ZodTypeAny ? z.infer<T["response"][S]> : never;
+export type InferResponse<
+  T extends ContractSchema,
+  S extends keyof T["response"]
+> = InferResponseSchema<T["response"][S]>;
 
 /**
  * Helper type to get all defined methods in a contract
@@ -159,21 +183,20 @@ export type RequiredFields<
 /**
  * Get the success response type (200 or 201)
  */
-export type SuccessResponse<T extends ContractSchema> = T["response"][200] extends z.ZodTypeAny
-  ? z.infer<T["response"][200]>
-  : T["response"][201] extends z.ZodTypeAny
-    ? z.infer<T["response"][201]>
-    : never;
+export type SuccessResponse<T extends ContractSchema> =
+  InferResponseSchema<T["response"][200]> extends never
+    ? InferResponseSchema<T["response"][201]>
+    : InferResponseSchema<T["response"][200]>;
 
 /**
  * Get the error response type (400, 404, 500, etc.)
  */
-export type ErrorResponse<T extends ContractSchema> =
-  | (T["response"][400] extends z.ZodTypeAny ? z.infer<T["response"][400]> : never)
-  | (T["response"][401] extends z.ZodTypeAny ? z.infer<T["response"][401]> : never)
-  | (T["response"][403] extends z.ZodTypeAny ? z.infer<T["response"][403]> : never)
-  | (T["response"][404] extends z.ZodTypeAny ? z.infer<T["response"][404]> : never)
-  | (T["response"][500] extends z.ZodTypeAny ? z.infer<T["response"][500]> : never);
+export type ErrorResponse<T extends ContractSchema> =
+  | InferResponseSchema<T["response"][400]>
+  | InferResponseSchema<T["response"][401]>
+  | InferResponseSchema<T["response"][403]>
+  | InferResponseSchema<T["response"][404]>
+  | InferResponseSchema<T["response"][500]>;
 
 /**
  * Utility type for strict contract enforcement
@@ -210,8 +233,8 @@ export type ContractFetchOptions<
 /**
  * Response type union for a contract
  */
-export type ContractResponseUnion<T extends ContractSchema> = {
-  [K in keyof T["response"]]: T["response"][K] extends z.ZodTypeAny
-    ? { status: K; data: z.infer<T["response"][K]> }
-    : never;
-}[keyof T["response"]];
+export type ContractResponseUnion<T extends ContractSchema> = {
+  [K in keyof T["response"]]: InferResponseSchema<T["response"][K]> extends never
+    ? never
+    : { status: K; data: InferResponseSchema<T["response"][K]> };
+}[keyof T["response"]];

package/src/contract/validator.ts

@@ -13,21 +13,32 @@
  */
 
 import type { z } from "zod";
-import type {
-  ContractSchema,
-  ContractValidationResult,
-  ContractValidationError,
-  ContractValidationIssue,
-  MethodRequestSchema,
-  ContractNormalizeMode,
-} from "./schema";
+import type {
+  ContractSchema,
+  ContractValidationResult,
+  ContractValidationError,
+  ContractValidationIssue,
+  MethodRequestSchema,
+  ContractNormalizeMode,
+  ResponseSchemaWithExamples,
+} from "./schema";
 import {
   type NormalizeMode,
   type NormalizeOptions,
   normalizeSchema,
   createCoerceSchema,
 } from "./normalize";
-import { ZodObject } from "zod";
+import { ZodObject } from "zod";
+
+function isResponseSchemaWithExamples(
+  schema: z.ZodTypeAny | ResponseSchemaWithExamples | undefined
+): schema is ResponseSchemaWithExamples {
+  return (
+    schema !== undefined &&
+    typeof schema === "object" &&
+    "schema" in schema
+  );
+}
 
 /**
  * Validator 옵션
@@ -442,14 +453,18 @@ export class ContractValidator {
    * @param responseBody - The response body (already parsed)
    * @param statusCode - HTTP status code
    */
-  validateResponse(responseBody: unknown, statusCode: number): ContractValidationResult {
-    const responseSchema = this.contract.response[statusCode];
-    if (!responseSchema) {
-      // No schema defined for this status code, pass through
-      return { success: true };
-    }
-
-    const result = responseSchema.safeParse(responseBody);
+  validateResponse(responseBody: unknown, statusCode: number): ContractValidationResult {
+    const responseSchemaOrWithExamples = this.contract.response[statusCode];
+    if (!responseSchemaOrWithExamples) {
+      // No schema defined for this status code, pass through
+      return { success: true };
+    }
+
+    const responseSchema = isResponseSchemaWithExamples(responseSchemaOrWithExamples)
+      ? responseSchemaOrWithExamples.schema
+      : responseSchemaOrWithExamples;
+
+    const result = responseSchema.safeParse(responseBody);
     if (!result.success) {
       const errors: ContractValidationError[] = [
         {

package/src/filling/context.ts

@@ -4,6 +4,19 @@
  */
 
 import type { ZodSchema } from "zod";
+import type { ContractSchema, ContractMethod } from "../contract/schema";
+import type { InferBody, InferHeaders, InferParams, InferQuery, InferResponse } from "../contract/types";
+import { ContractValidator, type ContractValidatorOptions } from "../contract/validator";
+
+type ContractInput<
+  TContract extends ContractSchema,
+  TMethod extends ContractMethod,
+> = {
+  query: InferQuery<TContract, TMethod>;
+  body: InferBody<TContract, TMethod>;
+  params: InferParams<TContract, TMethod>;
+  headers: InferHeaders<TContract, TMethod>;
+};
 
 // ========== Cookie Types ==========
 
@@ -316,6 +329,34 @@ export class ManduContext {
     return data as T;
   }
 
+  /**
+   * Parse and validate request input via Contract
+   * @example
+   * const input = await ctx.input(userContract, "POST", { id: "123" })
+   */
+  async input<
+    TContract extends ContractSchema,
+    TMethod extends ContractMethod,
+  >(
+    contract: TContract,
+    method: TMethod,
+    pathParams: Record<string, string> = {},
+    options: ContractValidatorOptions = {}
+  ): Promise<ContractInput<TContract, TMethod>> {
+    const validator = new ContractValidator(contract, options);
+    const result = await validator.validateAndNormalizeRequest(
+      this.request,
+      method,
+      pathParams
+    );
+
+    if (!result.success) {
+      throw new ValidationError(result.errors ?? []);
+    }
+
+    return (result.data ?? {}) as ContractInput<TContract, TMethod>;
+  }
+
   // ============================================
   // 🥟 Response 보내기
   // ============================================
@@ -376,6 +417,68 @@ export class ManduContext {
     return this.withCookies(response);
   }
 
+  /**
+   * Validate and send response via Contract
+   * @example
+   * return ctx.output(userContract, 200, { data: users })
+   */
+  output<
+    TContract extends ContractSchema,
+    TStatus extends keyof TContract["response"],
+  >(
+    contract: TContract,
+    status: TStatus,
+    data: InferResponse<TContract, TStatus>,
+    options: ContractValidatorOptions = {}
+  ): Response {
+    const validator = new ContractValidator(contract, options);
+    const result = validator.validateResponse(data, Number(status));
+
+    if (!result.success) {
+      if (options.mode === "strict") {
+        const errorResponse = Response.json(
+          {
+            errorType: "CONTRACT_VIOLATION",
+            code: "MANDU_C001",
+            message: "Response does not match contract schema",
+            summary: "응답이 Contract 스키마와 일치하지 않습니다",
+            statusCode: Number(status),
+            violations: result.errors,
+            timestamp: new Date().toISOString(),
+          },
+          { status: 500 }
+        );
+        return this.withCookies(errorResponse);
+      }
+
+      console.warn(
+        "\x1b[33m[Mandu] Contract violation in response:\x1b[0m",
+        result.errors
+      );
+    }
+
+    const payload = result.success ? result.data : data;
+    return this.json(payload as InferResponse<TContract, TStatus>, Number(status));
+  }
+
+  /** 200 OK with Contract validation */
+  okContract<TContract extends ContractSchema>(
+    contract: TContract,
+    data: InferResponse<TContract, 200>,
+    options: ContractValidatorOptions = {}
+  ): Response {
+    return this.output(contract, 200 as keyof TContract["response"], data, options);
+  }
+
+  /** 201 Created with Contract validation */
+  createdContract<TContract extends ContractSchema>(
+    contract: TContract,
+    data: InferResponse<TContract, 201>,
+    options: ContractValidatorOptions = {}
+  ): Response {
+    return this.output(contract, 201 as keyof TContract["response"], data, options);
+  }
+
   /** Custom text response */
   text(data: string, status: number = 200): Response {
     const response = new Response(data, {

package/src/generator/templates.ts

@@ -110,10 +110,14 @@ export default async function handler(
 `;
 }
 
-export function generateSlotLogic(route: RouteSpec): string {
-  return `// 🥟 Mandu Filling - ${route.id}
-// Pattern: ${route.pattern}
-// 이 파일에서 비즈니스 로직을 구현하세요.
+export function generateSlotLogic(route: RouteSpec): string {
+  if (route.contractModule) {
+    return generateSlotLogicWithContract(route);
+  }
+
+  return `// 🥟 Mandu Filling - ${route.id}
+// Pattern: ${route.pattern}
+// 이 파일에서 비즈니스 로직을 구현하세요.
 
 import { Mandu } from "@mandujs/core";
 
@@ -145,17 +149,62 @@ export default Mandu.filling()
 // 💡 Context (ctx) API:
 // ctx.query            - Query parameters { name: 'value' }
 // ctx.params           - Path parameters { id: '123' }
-// ctx.body()           - Request body (자동 파싱)
-// ctx.body(zodSchema)  - Body with validation
-// ctx.headers          - Request headers
-// ctx.ok(data)         - 200 OK
-// ctx.created(data)    - 201 Created
-// ctx.error(msg)       - 400 Bad Request
-// ctx.notFound(msg)    - 404 Not Found
-// ctx.set(key, value)  - Guard에서 Handler로 데이터 전달
-// ctx.get(key)         - Guard에서 설정한 데이터 읽기
-`;
-}
+// ctx.body()           - Request body (자동 파싱)
+// ctx.body(zodSchema)  - Body with validation
+// ctx.headers          - Request headers
+// ctx.ok(data)         - 200 OK
+// ctx.created(data)    - 201 Created
+// ctx.error(msg)       - 400 Bad Request
+// ctx.notFound(msg)    - 404 Not Found
+// ctx.set(key, value)  - Guard에서 Handler로 데이터 전달
+// ctx.get(key)         - Guard에서 설정한 데이터 읽기
+`;
+}
+
+export function generateSlotLogicWithContract(route: RouteSpec): string {
+  const contractImportPath = computeSlotImportPath(
+    route.contractModule!,
+    pathDirname(route.slotModule ?? "spec/slots")
+  );
+
+  return `// 🥟 Mandu Filling - ${route.id}
+// Pattern: ${route.pattern}
+// Contract Module: ${route.contractModule}
+// 이 파일에서 비즈니스 로직을 구현하세요.
+
+import { Mandu } from "@mandujs/core";
+import contract from "${contractImportPath}";
+
+export default Mandu.filling()
+  // 📋 GET ${route.pattern}
+  .get(async (ctx) => {
+    const input = await ctx.input(contract, "GET", ctx.params);
+    // TODO: 계약의 응답 코드에 맞게 status를 조정하세요
+    return ctx.output(contract, 200, {
+      message: "Hello from ${route.id}!",
+      input,
+      timestamp: new Date().toISOString(),
+    });
+  })
+
+  // ➕ POST ${route.pattern}
+  .post(async (ctx) => {
+    const input = await ctx.input(contract, "POST", ctx.params);
+    // TODO: 계약의 응답 코드에 맞게 status를 조정하세요
+    return ctx.output(contract, 201, {
+      message: "Created!",
+      input,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+// 💡 Contract 기반 사용법:
+// ctx.input(contract, "GET")  - Contract로 요청 검증 + 정규화
+// ctx.output(contract, 200, data) - Contract로 응답 검증
+// ctx.okContract(contract, data)  - 200 OK (Contract 검증)
+// ctx.createdContract(contract, data) - 201 Created (Contract 검증)
+`;
+}
 
 function computeSlotImportPath(slotModule: string, fromDir: string): string {
   // slotModule: "apps/server/slots/users.logic.ts"
@@ -334,9 +383,13 @@ export default {
  * "todo-page" → "TodoPage"
  * "user_profile" → "UserProfile"
  */
-function toPascalCase(str: string): string {
+function toPascalCase(str: string): string {
   return str
     .split(/[-_]/)
     .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
     .join("");
-}
+}
+
+function pathDirname(filePath: string): string {
+  return filePath.replace(/\\/g, "/").split("/").slice(0, -1).join("/");
+}

package/src/guard/analyzer.ts

@@ -239,11 +239,16 @@ export function resolveImportLayer(
 export function extractSlice(filePath: string, layer: string): string | undefined {
   const relativePath = filePath.replace(/\\/g, "/");
 
-  // layer/slice/... 형식에서 slice 추출
-  const pattern = new RegExp(`${layer}/([^/]+)`);
-  const match = relativePath.match(pattern);
+  const marker = `${layer}/`;
+  const index = relativePath.indexOf(marker);
+  if (index === -1) {
+    return undefined;
+  }
+
+  const rest = relativePath.slice(index + marker.length);
+  const slice = rest.split("/")[0];
 
-  return match?.[1];
+  return slice || undefined;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════

package/src/guard/check.ts

@@ -1,16 +1,46 @@
-import { GUARD_RULES, FORBIDDEN_IMPORTS, type GuardViolation } from "./rules";
-import { verifyLock, computeHash } from "../spec/lock";
-import { runContractGuardCheck } from "./contract-guard";
-import { validateSlotContent } from "../slot/validator";
-import type { RoutesManifest } from "../spec/schema";
-import type { GeneratedMap } from "../generator/generate";
-import path from "path";
-import fs from "fs/promises";
-
-export interface GuardCheckResult {
-  passed: boolean;
-  violations: GuardViolation[];
-}
+import { GUARD_RULES, FORBIDDEN_IMPORTS, type GuardViolation } from "./rules";
+import { verifyLock, computeHash } from "../spec/lock";
+import { runContractGuardCheck } from "./contract-guard";
+import { validateSlotContent } from "../slot/validator";
+import type { RoutesManifest } from "../spec/schema";
+import type { GeneratedMap } from "../generator/generate";
+import { loadManduConfig, type GuardRuleSeverity } from "../config";
+import path from "path";
+import fs from "fs/promises";
+
+export interface GuardCheckResult {
+  passed: boolean;
+  violations: GuardViolation[];
+}
+
+function normalizeSeverity(level: GuardRuleSeverity): "error" | "warning" | "off" {
+  if (level === "warn") return "warning";
+  return level;
+}
+
+function applyRuleSeverity(
+  violations: GuardViolation[],
+  config: { rules?: Record<string, GuardRuleSeverity>; contractRequired?: GuardRuleSeverity }
+): GuardViolation[] {
+  const resolved: GuardViolation[] = [];
+  const ruleOverrides = config.rules ?? {};
+
+  for (const violation of violations) {
+    let override = ruleOverrides[violation.ruleId];
+    if (violation.ruleId === "CONTRACT_MISSING" && config.contractRequired) {
+      override = config.contractRequired;
+    }
+
+    const baseSeverity = violation.severity ?? GUARD_RULES[violation.ruleId]?.severity ?? "error";
+    const finalSeverity = override ? normalizeSeverity(override) : baseSeverity;
+
+    if (finalSeverity === "off") continue;
+
+    resolved.push({ ...violation, severity: finalSeverity });
+  }
+
+  return resolved;
+}
 
 async function fileExists(filePath: string): Promise<boolean> {
   try {
@@ -170,13 +200,15 @@ export async function checkSlotContentValidation(
       if (issue.severity === "error") {
         // Map slot issue codes to guard rule IDs
         let ruleId = "SLOT_VALIDATION_ERROR";
-        if (issue.code === "MISSING_DEFAULT_EXPORT") {
-          ruleId = GUARD_RULES.SLOT_MISSING_DEFAULT_EXPORT?.id ?? "SLOT_MISSING_DEFAULT_EXPORT";
-        } else if (issue.code === "NO_RESPONSE_PATTERN" || issue.code === "INVALID_HANDLER_RETURN") {
-          ruleId = GUARD_RULES.SLOT_INVALID_RETURN?.id ?? "SLOT_INVALID_RETURN";
-        } else if (issue.code === "MISSING_FILLING_PATTERN") {
-          ruleId = GUARD_RULES.SLOT_MISSING_FILLING_PATTERN?.id ?? "SLOT_MISSING_FILLING_PATTERN";
-        }
+        if (issue.code === "MISSING_DEFAULT_EXPORT") {
+          ruleId = GUARD_RULES.SLOT_MISSING_DEFAULT_EXPORT?.id ?? "SLOT_MISSING_DEFAULT_EXPORT";
+        } else if (issue.code === "NO_RESPONSE_PATTERN" || issue.code === "INVALID_HANDLER_RETURN") {
+          ruleId = GUARD_RULES.SLOT_INVALID_RETURN?.id ?? "SLOT_INVALID_RETURN";
+        } else if (issue.code === "MISSING_FILLING_PATTERN") {
+          ruleId = GUARD_RULES.SLOT_MISSING_FILLING_PATTERN?.id ?? "SLOT_MISSING_FILLING_PATTERN";
+        } else if (issue.code === "ZOD_DIRECT_IMPORT") {
+          ruleId = GUARD_RULES.SLOT_ZOD_DIRECT_IMPORT?.id ?? "SLOT_ZOD_DIRECT_IMPORT";
+        }
 
         violations.push({
           ruleId,
@@ -332,11 +364,12 @@ export async function checkSpecDirNaming(
   return violations;
 }
 
-export async function runGuardCheck(
-  manifest: RoutesManifest,
-  rootDir: string
-): Promise<GuardCheckResult> {
-  const violations: GuardViolation[] = [];
+export async function runGuardCheck(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<GuardCheckResult> {
+  const violations: GuardViolation[] = [];
+  const config = await loadManduConfig(rootDir);
 
   const lockPath = path.join(rootDir, "spec/spec.lock.json");
   const mapPath = path.join(rootDir, "packages/core/map/generated.map.json");
@@ -392,8 +425,11 @@ export async function runGuardCheck(
   const specDirViolations = await checkSpecDirNaming(rootDir);
   violations.push(...specDirViolations);
 
-  return {
-    passed: violations.length === 0,
-    violations,
-  };
-}
+  const resolvedViolations = applyRuleSeverity(violations, config.guard ?? {});
+  const passed = resolvedViolations.every((v) => v.severity !== "error");
+
+  return {
+    passed,
+    violations: resolvedViolations,
+  };
+}

package/src/guard/contract-guard.ts

@@ -199,15 +199,15 @@ export async function checkContractSlotConsistency(
 /**
  * Run all contract-related guard checks
  */
-export async function runContractGuardCheck(
-  manifest: RoutesManifest,
-  rootDir: string
-): Promise<ContractViolation[]> {
-  const violations: ContractViolation[] = [];
-
-  // Check missing contracts (warning level)
-  // const missingContracts = await checkMissingContract(manifest, rootDir);
-  // violations.push(...missingContracts);
+export async function runContractGuardCheck(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<ContractViolation[]> {
+  const violations: ContractViolation[] = [];
+
+  // Check missing contracts (warning level)
+  const missingContracts = await checkMissingContract(manifest, rootDir);
+  violations.push(...missingContracts);
 
   // Check contract file exists
   const notFoundContracts = await checkContractFileExists(manifest, rootDir);

package/src/guard/file-type.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { validateFileAnalysis } from "./validator";
+import { fsdPreset } from "./presets/fsd";
+import type { FileAnalysis, GuardConfig } from "./types";
+
+describe("TypeScript-only rule", () => {
+  const layers = fsdPreset.layers;
+  const config: GuardConfig = {
+    preset: "fsd",
+    severity: { fileType: "error" },
+  };
+
+  it("should flag .jsx files", () => {
+    const analysis: FileAnalysis = {
+      filePath: "src/pages/home.jsx",
+      layer: "pages",
+      imports: [],
+      analyzedAt: Date.now(),
+    };
+
+    const violations = validateFileAnalysis(analysis, layers, config);
+    expect(violations.some((v) => v.type === "file-type")).toBe(true);
+  });
+});