@mandujs/core 0.4.2 → 0.5.0

package/src/generator/contract-glue.ts

@@ -0,0 +1,285 @@
+/**
+ * Mandu Contract Type Glue Generator
+ * Contract에서 TypeScript 타입 글루 코드 생성
+ */
+
+import type { RouteSpec } from "../spec/schema";
+
+/**
+ * Convert string to PascalCase
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/**
+ * Compute relative import path
+ */
+function computeRelativePath(fromDir: string, toPath: string): string {
+  const fromParts = fromDir.replace(/\\/g, "/").split("/");
+  const toParts = toPath.replace(/\\/g, "/").split("/");
+
+  let commonLength = 0;
+  while (
+    commonLength < fromParts.length &&
+    commonLength < toParts.length &&
+    fromParts[commonLength] === toParts[commonLength]
+  ) {
+    commonLength++;
+  }
+
+  const upCount = fromParts.length - commonLength;
+  const relativeParts = toParts.slice(commonLength);
+  const ups = Array(upCount).fill("..");
+
+  let result = [...ups, ...relativeParts].join("/");
+  result = result.replace(/\.ts$/, "");
+
+  return result;
+}
+
+/**
+ * Generate type glue code for a route with contract
+ *
+ * @example
+ * ```typescript
+ * // generated/types/users.types.ts
+ * import type { InferContract, InferQuery, InferBody, InferResponse } from "@mandujs/core";
+ * import contract from "../../spec/contracts/users.contract";
+ *
+ * export type UsersContract = InferContract<typeof contract>;
+ *
+ * // Request types
+ * export type UsersGetQuery = InferQuery<typeof contract, "GET">;
+ * export type UsersPostBody = InferBody<typeof contract, "POST">;
+ *
+ * // Response types
+ * export type UsersResponse200 = InferResponse<typeof contract, 200>;
+ * export type UsersResponse201 = InferResponse<typeof contract, 201>;
+ * ```
+ */
+export function generateContractTypeGlue(
+  route: RouteSpec,
+  typesDir: string = "apps/server/generated/types"
+): string {
+  if (!route.contractModule) {
+    return "";
+  }
+
+  const pascalName = toPascalCase(route.id);
+  const contractImportPath = computeRelativePath(typesDir, route.contractModule);
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Type glue for route: ${route.id}
+// Contract: ${route.contractModule}
+
+import type { InferContract, InferQuery, InferBody, InferParams, InferResponse } from "@mandujs/core";
+import contract from "${contractImportPath}";
+
+/**
+ * Full contract type for ${route.id}
+ */
+export type ${pascalName}Contract = InferContract<typeof contract>;
+
+// ============================================
+// Request Types
+// ============================================
+
+/** GET query parameters */
+export type ${pascalName}GetQuery = InferQuery<typeof contract, "GET">;
+
+/** POST request body */
+export type ${pascalName}PostBody = InferBody<typeof contract, "POST">;
+
+/** PUT request body */
+export type ${pascalName}PutBody = InferBody<typeof contract, "PUT">;
+
+/** PATCH request body */
+export type ${pascalName}PatchBody = InferBody<typeof contract, "PATCH">;
+
+/** DELETE query parameters */
+export type ${pascalName}DeleteQuery = InferQuery<typeof contract, "DELETE">;
+
+/** Path parameters (if any) */
+export type ${pascalName}Params = InferParams<typeof contract, "GET">;
+
+// ============================================
+// Response Types
+// ============================================
+
+/** 200 OK response */
+export type ${pascalName}Response200 = InferResponse<typeof contract, 200>;
+
+/** 201 Created response */
+export type ${pascalName}Response201 = InferResponse<typeof contract, 201>;
+
+/** 204 No Content response */
+export type ${pascalName}Response204 = InferResponse<typeof contract, 204>;
+
+/** 400 Bad Request response */
+export type ${pascalName}Response400 = InferResponse<typeof contract, 400>;
+
+/** 404 Not Found response */
+export type ${pascalName}Response404 = InferResponse<typeof contract, 404>;
+
+// Re-export contract for runtime use
+export { contract };
+`;
+}
+
+/**
+ * Generate contract template for a route
+ *
+ * @example
+ * ```typescript
+ * // spec/contracts/users.contract.ts
+ * import { z } from "zod";
+ * import { Mandu } from "@mandujs/core";
+ *
+ * export default Mandu.contract({
+ *   description: "Users API",
+ *   tags: ["users"],
+ *   request: {
+ *     GET: { query: z.object({ page: z.coerce.number().default(1) }) },
+ *     POST: { body: z.object({ name: z.string() }) },
+ *   },
+ *   response: {
+ *     200: z.object({ data: z.array(z.unknown()) }),
+ *     201: z.object({ data: z.unknown() }),
+ *     400: z.object({ error: z.string() }),
+ *   },
+ * });
+ * ```
+ */
+export function generateContractTemplate(route: RouteSpec): string {
+  const methods = route.methods || ["GET"];
+  const hasGet = methods.includes("GET");
+  const hasPost = methods.includes("POST");
+  const hasPut = methods.includes("PUT");
+  const hasPatch = methods.includes("PATCH");
+  const hasDelete = methods.includes("DELETE");
+
+  const requestParts: string[] = [];
+
+  if (hasGet) {
+    requestParts.push(`    GET: {
+      query: z.object({
+        page: z.coerce.number().int().min(1).default(1),
+        limit: z.coerce.number().int().min(1).max(100).default(10),
+      }),
+    }`);
+  }
+
+  if (hasPost) {
+    requestParts.push(`    POST: {
+      body: z.object({
+        // TODO: Define your request body schema
+        name: z.string().min(1),
+      }),
+    }`);
+  }
+
+  if (hasPut) {
+    requestParts.push(`    PUT: {
+      body: z.object({
+        // TODO: Define your request body schema
+        name: z.string().min(1),
+      }),
+    }`);
+  }
+
+  if (hasPatch) {
+    requestParts.push(`    PATCH: {
+      body: z.object({
+        // TODO: Define your partial update schema
+        name: z.string().min(1).optional(),
+      }),
+    }`);
+  }
+
+  if (hasDelete) {
+    requestParts.push(`    DELETE: {
+      // Usually no body for DELETE
+    }`);
+  }
+
+  return `// 📜 Mandu Contract - ${route.id}
+// Pattern: ${route.pattern}
+// 이 파일에서 API 스키마를 정의하세요.
+
+import { z } from "zod";
+import { Mandu } from "@mandujs/core";
+
+// ============================================
+// 🥟 Schema Definitions
+// ============================================
+
+// TODO: Define your data schemas here
+// const ItemSchema = z.object({
+//   id: z.string().uuid(),
+//   name: z.string(),
+//   createdAt: z.string().datetime(),
+// });
+
+// ============================================
+// 📜 Contract Definition
+// ============================================
+
+export default Mandu.contract({
+  description: "${toPascalCase(route.id)} API",
+  tags: ["${route.id}"],
+
+  request: {
+${requestParts.join(",\n\n")}
+  },
+
+  response: {
+    200: z.object({
+      data: z.unknown(),
+      // TODO: Define your success response schema
+    }),
+    ${hasPost || hasPut ? `201: z.object({
+      data: z.unknown(),
+      // TODO: Define your created response schema
+    }),
+    ` : ""}400: z.object({
+      error: z.string(),
+      details: z.array(z.object({
+        type: z.string(),
+        issues: z.array(z.object({
+          path: z.string(),
+          message: z.string(),
+        })),
+      })).optional(),
+    }),
+    404: z.object({
+      error: z.string(),
+    }),
+  },
+});
+
+// 💡 Contract 사용법:
+// 1. 위의 스키마를 실제 데이터 구조에 맞게 정의하세요
+// 2. mandu generate를 실행하면 타입이 자동으로 Slot에 연결됩니다
+// 3. OpenAPI 문서가 자동으로 생성됩니다
+`;
+}
+
+/**
+ * Generate index file that exports all contract types
+ */
+export function generateContractTypesIndex(routeIds: string[]): string {
+  const exports = routeIds.map((id) => {
+    const fileName = `${id}.types`;
+    return `export * from "./${fileName}";`;
+  });
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Contract type exports
+
+${exports.join("\n")}
+`;
+}

package/src/generator/generate.ts

@@ -1,5 +1,6 @@
 import type { RoutesManifest, RouteSpec } from "../spec/schema";
 import { generateApiHandler, generatePageComponent, generateSlotLogic } from "./templates";
+import { generateContractTypeGlue, generateContractTemplate, generateContractTypesIndex } from "./contract-glue";
 import { computeHash } from "../spec/lock";
 import path from "path";
 import fs from "fs/promises";
@@ -51,6 +52,16 @@ export interface SlotMapping {
   slotPath: string;
 }
 
+/**
+ * Contract 파일 매핑 정보
+ */
+export interface ContractMapping {
+  /** Contract 파일 경로 */
+  contractPath: string;
+  /** Type glue 파일 경로 */
+  typeGluePath: string;
+}
+
 /**
  * Generated 파일 엔트리
  */
@@ -63,6 +74,8 @@ export interface GeneratedFileEntry {
   specLocation: SpecLocation;
   /** Slot 매핑 (있는 경우) */
   slotMapping?: SlotMapping;
+  /** Contract 매핑 (있는 경우) */
+  contractMapping?: ContractMapping;
 }
 
 /**
@@ -98,6 +111,15 @@ async function getExistingFiles(dir: string): Promise<string[]> {
   }
 }
 
+async function getTypeFiles(dir: string): Promise<string[]> {
+  try {
+    const files = await fs.readdir(dir);
+    return files.filter((f) => f.endsWith(".types.ts") || f === "index.ts");
+  } catch {
+    return [];
+  }
+}
+
 export async function generateRoutes(
   manifest: RoutesManifest,
   rootDir: string
@@ -112,10 +134,12 @@ export async function generateRoutes(
 
   const serverRoutesDir = path.join(rootDir, "apps/server/generated/routes");
   const webRoutesDir = path.join(rootDir, "apps/web/generated/routes");
+  const typesDir = path.join(rootDir, "apps/server/generated/types");
   const mapDir = path.join(rootDir, "packages/core/map");
 
   await ensureDir(serverRoutesDir);
   await ensureDir(webRoutesDir);
+  await ensureDir(typesDir);
   await ensureDir(mapDir);
 
   const generatedMap: GeneratedMap = {
@@ -135,6 +159,8 @@ export async function generateRoutes(
 
   const expectedServerFiles = new Set<string>();
   const expectedWebFiles = new Set<string>();
+  const expectedTypeFiles = new Set<string>();
+  const routesWithContracts: string[] = [];
 
   for (let routeIndex = 0; routeIndex < manifest.routes.length; routeIndex++) {
     const route = manifest.routes[routeIndex];
@@ -152,6 +178,9 @@ export async function generateRoutes(
         ? { slotPath: route.slotModule }
         : undefined;
 
+      // Contract 매핑 정보 (있는 경우)
+      let contractMapping: ContractMapping | undefined;
+
       // Server handler
       const serverFileName = `${route.id}.route.ts`;
       const serverFilePath = path.join(serverRoutesDir, serverFileName);
@@ -161,11 +190,46 @@ export async function generateRoutes(
       await Bun.write(serverFilePath, handlerContent);
       result.created.push(serverFilePath);
 
+      // Contract file (only if contractModule is specified)
+      if (route.contractModule) {
+        const contractFilePath = path.join(rootDir, route.contractModule);
+        const contractDir = path.dirname(contractFilePath);
+
+        await ensureDir(contractDir);
+
+        // contract 파일이 이미 존재하면 덮어쓰지 않음 (사용자 코드 보존)
+        const contractExists = await fileExists(contractFilePath);
+        if (!contractExists) {
+          const contractContent = generateContractTemplate(route);
+          await Bun.write(contractFilePath, contractContent);
+          result.created.push(contractFilePath);
+        } else {
+          result.skipped.push(contractFilePath);
+        }
+
+        // Generate type glue
+        const typeFileName = `${route.id}.types.ts`;
+        const typeFilePath = path.join(typesDir, typeFileName);
+        expectedTypeFiles.add(typeFileName);
+
+        const typeGlueContent = generateContractTypeGlue(route, "apps/server/generated/types");
+        await Bun.write(typeFilePath, typeGlueContent);
+        result.created.push(typeFilePath);
+
+        contractMapping = {
+          contractPath: route.contractModule,
+          typeGluePath: `apps/server/generated/types/${typeFileName}`,
+        };
+
+        routesWithContracts.push(route.id);
+      }
+
       generatedMap.files[`apps/server/generated/routes/${serverFileName}`] = {
         routeId: route.id,
         kind: route.kind as "api" | "page",
         specLocation,
         slotMapping,
+        contractMapping,
       };
 
       // Slot file (only if slotModule is specified)
@@ -201,6 +265,7 @@ export async function generateRoutes(
           kind: route.kind,
           specLocation,
           slotMapping,
+          contractMapping,
         };
       }
     } catch (error) {
@@ -211,6 +276,14 @@ export async function generateRoutes(
     }
   }
 
+  // Generate types index if there are contracts
+  if (routesWithContracts.length > 0) {
+    const typesIndexContent = generateContractTypesIndex(routesWithContracts);
+    const typesIndexPath = path.join(typesDir, "index.ts");
+    await Bun.write(typesIndexPath, typesIndexContent);
+    result.created.push(typesIndexPath);
+  }
+
   // Clean up stale files
   const existingServerFiles = await getExistingFiles(serverRoutesDir);
   for (const file of existingServerFiles) {
@@ -230,6 +303,16 @@ export async function generateRoutes(
     }
   }
 
+  // Clean up stale type files
+  const existingTypeFiles = await getTypeFiles(typesDir);
+  for (const file of existingTypeFiles) {
+    if (!expectedTypeFiles.has(file) && file !== "index.ts") {
+      const filePath = path.join(typesDir, file);
+      await fs.unlink(filePath);
+      result.deleted.push(filePath);
+    }
+  }
+
   // Write generated map
   const mapPath = path.join(mapDir, "generated.map.json");
   await Bun.write(mapPath, JSON.stringify(generatedMap, null, 2));

package/src/generator/index.ts

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

package/src/generator/templates.ts

@@ -1,7 +1,12 @@
 import type { RouteSpec } from "../spec/schema";
 
 export function generateApiHandler(route: RouteSpec): string {
-  // slotModule이 있으면 slot을 호출하는 버전 생성
+  // contractModule + slotModule이 있으면 contract 검증 버전 생성
+  if (route.contractModule && route.slotModule) {
+    return generateApiHandlerWithContract(route);
+  }
+
+  // slotModule만 있으면 slot을 호출하는 버전 생성
   if (route.slotModule) {
     return generateApiHandlerWithSlot(route);
   }
@@ -43,6 +48,68 @@ export default async function handler(
 `;
 }
 
+export function generateApiHandlerWithContract(route: RouteSpec): string {
+  const slotImportPath = computeSlotImportPath(route.slotModule!, "apps/server/generated/routes");
+  const contractImportPath = computeSlotImportPath(route.contractModule!, "apps/server/generated/routes");
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Contract Module: ${route.contractModule}
+// Slot Module: ${route.slotModule}
+
+import type { Request } from "bun";
+import { ContractValidator, formatValidationErrors } from "@mandujs/core";
+import contract from "${contractImportPath}";
+import filling from "${slotImportPath}";
+
+const validator = new ContractValidator(contract);
+const isDev = process.env.NODE_ENV !== "production";
+
+export default async function handler(
+  req: Request,
+  params: Record<string, string>
+): Promise<Response> {
+  const method = req.method;
+
+  // 1. Request Validation
+  const reqValidation = await validator.validateRequest(req, method, params);
+  if (!reqValidation.success) {
+    return Response.json(
+      formatValidationErrors(reqValidation.errors!),
+      { status: 400 }
+    );
+  }
+
+  // 2. Execute Filling
+  const response = await filling.handle(req, params, {
+    routeId: "${route.id}",
+    pattern: "${route.pattern}",
+  });
+
+  // 3. Response Validation (dev only)
+  if (isDev && response.headers.get("content-type")?.includes("application/json")) {
+    try {
+      const cloned = response.clone();
+      const body = await cloned.json();
+      const resValidation = validator.validateResponse(body, response.status);
+      if (!resValidation.success) {
+        console.warn(
+          "\\x1b[33m[Mandu] Contract violation in response:\\x1b[0m",
+          "${route.id}",
+          resValidation.errors
+        );
+      }
+    } catch {
+      // Ignore JSON parse errors for non-JSON responses
+    }
+  }
+
+  return response;
+}
+`;
+}
+
 export function generateSlotLogic(route: RouteSpec): string {
   return `// 🥟 Mandu Filling - ${route.id}
 // Pattern: ${route.pattern}
@@ -122,7 +189,7 @@ function computeSlotImportPath(slotModule: string, fromDir: string): string {
 }
 
 export function generatePageComponent(route: RouteSpec): string {
-  const pageName = capitalize(route.id);
+  const pageName = toPascalCase(route.id);
   return `// Generated by Mandu - DO NOT EDIT DIRECTLY
 // Route ID: ${route.id}
 // Pattern: ${route.pattern}
@@ -143,6 +210,14 @@ export default function ${pageName}Page({ params }: Props): React.ReactElement {
 `;
 }
 
-function capitalize(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1);
+/**
+ * Convert string to PascalCase (handles kebab-case, snake_case)
+ * "todo-page" → "TodoPage"
+ * "user_profile" → "UserProfile"
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
 }

package/src/guard/check.ts

@@ -1,5 +1,6 @@
 import { GUARD_RULES, FORBIDDEN_IMPORTS, type GuardViolation } from "./rules";
 import { verifyLock, computeHash } from "../spec/lock";
+import { runContractGuardCheck } from "./contract-guard";
 import type { RoutesManifest } from "../spec/schema";
 import type { GeneratedMap } from "../generator/generate";
 import path from "path";
@@ -248,6 +249,10 @@ export async function runGuardCheck(
   const slotViolations = await checkSlotFileExists(manifest, rootDir);
   violations.push(...slotViolations);
 
+  // Rule 6-9: Contract-related checks
+  const contractViolations = await runContractGuardCheck(manifest, rootDir);
+  violations.push(...contractViolations);
+
   return {
     passed: violations.length === 0,
     violations,