@mandujs/core 0.9.45 → 0.10.0

package/src/error/domains.ts

@@ -0,0 +1,265 @@
+/**
+ * 도메인별 에러 클래스
+ *
+ * ManduError 인터페이스 기반의 실제 Error 클래스들.
+ * try-catch에서 instanceof 체크 가능.
+ */
+
+import { ErrorCode, ERROR_MESSAGES, ERROR_SUMMARIES } from "./types";
+import type { ManduError, RouteContext, ErrorType } from "./types";
+
+/**
+ * Mandu 에러 베이스 클래스
+ */
+export abstract class ManduBaseError extends Error implements ManduError {
+  abstract readonly errorType: ErrorType;
+  readonly code: ErrorCode | string;
+  readonly httpStatus?: number;
+  readonly summary: string;
+  readonly fix: { file: string; suggestion: string; line?: number };
+  readonly route?: RouteContext;
+  readonly timestamp: string;
+
+  constructor(
+    code: ErrorCode | string,
+    message: string,
+    fix: { file: string; suggestion: string; line?: number },
+    options?: {
+      httpStatus?: number;
+      route?: RouteContext;
+      cause?: unknown;
+    }
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = this.constructor.name;
+    this.code = code;
+    this.httpStatus = options?.httpStatus;
+    this.summary =
+      typeof code === "string" && code in ERROR_SUMMARIES
+        ? ERROR_SUMMARIES[code as ErrorCode]
+        : message;
+    this.fix = fix;
+    this.route = options?.route;
+    this.timestamp = new Date().toISOString();
+  }
+
+  /**
+   * ManduError 인터페이스로 변환
+   */
+  toManduError(): ManduError {
+    return {
+      errorType: this.errorType,
+      code: this.code,
+      httpStatus: this.httpStatus,
+      message: this.message,
+      summary: this.summary,
+      fix: this.fix,
+      route: this.route,
+      timestamp: this.timestamp,
+    };
+  }
+}
+
+// ============================================================
+// 파일 시스템 에러
+// ============================================================
+
+/**
+ * 파일 읽기/쓰기 에러
+ */
+export class FileError extends ManduBaseError {
+  readonly errorType = "LOGIC_ERROR" as const;
+  readonly filePath: string;
+  readonly operation: "read" | "write" | "access" | "stat";
+
+  constructor(
+    filePath: string,
+    operation: "read" | "write" | "access" | "stat",
+    cause?: unknown
+  ) {
+    const message = `파일 ${operation} 실패: ${filePath}`;
+    super(
+      ErrorCode.SLOT_IMPORT_ERROR,
+      message,
+      {
+        file: filePath,
+        suggestion: `파일이 존재하고 읽기 권한이 있는지 확인하세요`,
+      },
+      { cause }
+    );
+    this.filePath = filePath;
+    this.operation = operation;
+  }
+}
+
+/**
+ * 디렉토리 읽기 에러
+ */
+export class DirectoryError extends ManduBaseError {
+  readonly errorType = "LOGIC_ERROR" as const;
+  readonly dirPath: string;
+
+  constructor(dirPath: string, cause?: unknown) {
+    super(
+      ErrorCode.SLOT_NOT_FOUND,
+      `디렉토리 읽기 실패: ${dirPath}`,
+      {
+        file: dirPath,
+        suggestion: `디렉토리가 존재하고 접근 가능한지 확인하세요`,
+      },
+      { cause }
+    );
+    this.dirPath = dirPath;
+  }
+}
+
+// ============================================================
+// Guard 에러
+// ============================================================
+
+/**
+ * Guard 아키텍처 검사 에러
+ */
+export class GuardError extends ManduBaseError {
+  readonly errorType = "LOGIC_ERROR" as const;
+  readonly ruleId: string;
+
+  constructor(
+    ruleId: string,
+    message: string,
+    file: string,
+    options?: {
+      line?: number;
+      suggestion?: string;
+      cause?: unknown;
+    }
+  ) {
+    super(
+      ErrorCode.SLOT_VALIDATION_ERROR,
+      message,
+      {
+        file,
+        suggestion: options?.suggestion || "아키텍처 규칙을 확인하세요",
+        line: options?.line,
+      },
+      { cause: options?.cause }
+    );
+    this.ruleId = ruleId;
+  }
+}
+
+// ============================================================
+// Router 에러
+// ============================================================
+
+/**
+ * 라우터 에러
+ */
+export class RouterError extends ManduBaseError {
+  readonly errorType = "FRAMEWORK_BUG" as const;
+
+  constructor(
+    message: string,
+    file: string,
+    options?: {
+      route?: RouteContext;
+      cause?: unknown;
+    }
+  ) {
+    super(
+      ErrorCode.FRAMEWORK_ROUTER_ERROR,
+      message,
+      {
+        file,
+        suggestion: "라우트 설정을 확인하세요",
+      },
+      { httpStatus: 500, ...options }
+    );
+  }
+}
+
+// ============================================================
+// SSR 에러
+// ============================================================
+
+/**
+ * SSR 렌더링 에러
+ */
+export class SSRError extends ManduBaseError {
+  readonly errorType = "FRAMEWORK_BUG" as const;
+
+  constructor(
+    message: string,
+    route: RouteContext,
+    cause?: unknown
+  ) {
+    super(
+      ErrorCode.FRAMEWORK_SSR_ERROR,
+      message,
+      {
+        file: `app/${route.id}/page.tsx`,
+        suggestion: "페이지 컴포넌트에서 렌더링 오류가 발생했습니다",
+      },
+      { httpStatus: 500, route, cause }
+    );
+  }
+}
+
+// ============================================================
+// Contract 에러
+// ============================================================
+
+/**
+ * API 계약 위반 에러
+ */
+export class ContractError extends ManduBaseError {
+  readonly errorType = "LOGIC_ERROR" as const;
+
+  constructor(
+    message: string,
+    contractFile: string,
+    options?: {
+      route?: RouteContext;
+      cause?: unknown;
+    }
+  ) {
+    super(
+      ErrorCode.SLOT_VALIDATION_ERROR,
+      message,
+      {
+        file: contractFile,
+        suggestion: "API 계약과 실제 구현이 일치하는지 확인하세요",
+      },
+      { httpStatus: 400, ...options }
+    );
+  }
+}
+
+// ============================================================
+// Security 에러
+// ============================================================
+
+/**
+ * 보안 관련 에러
+ */
+export class SecurityError extends ManduBaseError {
+  readonly errorType = "LOGIC_ERROR" as const;
+  readonly securityType: "path_traversal" | "injection" | "unauthorized" | "import_violation";
+
+  constructor(
+    securityType: "path_traversal" | "injection" | "unauthorized" | "import_violation",
+    message: string,
+    file?: string
+  ) {
+    super(
+      ErrorCode.SLOT_HANDLER_ERROR,
+      message,
+      {
+        file: file || "unknown",
+        suggestion: "보안 정책을 위반하는 요청입니다",
+      },
+      { httpStatus: 403 }
+    );
+    this.securityType = securityType;
+  }
+}

package/src/error/index.ts

@@ -2,6 +2,18 @@
 export type { ManduError, RouteContext, FixTarget, DebugInfo, ErrorType } from "./types";
 export { ErrorCode, ERROR_MESSAGES, ERROR_SUMMARIES } from "./types";
 
+// Domain Error Classes
+export {
+  ManduBaseError,
+  FileError,
+  DirectoryError,
+  GuardError,
+  RouterError,
+  SSRError,
+  ContractError,
+  SecurityError,
+} from "./domains";
+
 // Stack Analyzer
 export { StackTraceAnalyzer, type StackFrame } from "./stack-analyzer";
 
@@ -14,16 +26,16 @@ export {
 } from "./classifier";
 
 // Formatter
-export {
-  formatErrorResponse,
-  formatErrorForConsole,
-  createNotFoundResponse,
-  createHandlerNotFoundResponse,
-  createPageLoadErrorResponse,
-  createSSRErrorResponse,
-  type FormatOptions,
-} from "./formatter";
-
-// Result helpers
-export type { Result } from "./result";
-export { ok, err, statusFromError, errorToResponse } from "./result";
+export {
+  formatErrorResponse,
+  formatErrorForConsole,
+  createNotFoundResponse,
+  createHandlerNotFoundResponse,
+  createPageLoadErrorResponse,
+  createSSRErrorResponse,
+  type FormatOptions,
+} from "./formatter";
+
+// Result helpers
+export type { Result } from "./result";
+export { ok, err, statusFromError, errorToResponse } from "./result";

package/src/filling/filling.ts

@@ -3,11 +3,11 @@
  * 체이닝 API로 비즈니스 로직 정의
  */
 
-import { ManduContext, ValidationError } from "./context";
-import { AuthenticationError, AuthorizationError } from "./auth";
-import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
-import { TIMEOUTS } from "../constants";
-import { createContract, type ContractDefinition, type ContractInstance } from "../contract";
+import { ManduContext, ValidationError } from "./context";
+import { AuthenticationError, AuthorizationError } from "./auth";
+import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
+import { TIMEOUTS } from "../constants";
+import { createContract, type ContractDefinition, type ContractInstance } from "../contract";
 import {
   type Middleware as RuntimeMiddleware,
   type MiddlewareEntry,
@@ -26,6 +26,7 @@ import {
   executeLifecycle,
   type ExecuteOptions,
 } from "../runtime/lifecycle";
+import type { SlotMetadata, SlotConstraints } from "../guard/semantic-slots";
 
 /** Handler function type */
 export type Handler = (ctx: ManduContext) => Response | Promise<Response>;
@@ -60,6 +61,8 @@ interface FillingConfig<TLoaderData = unknown> {
   loader?: Loader<TLoaderData>;
   lifecycle: LifecycleStore;
   middleware: MiddlewareEntry[];
+  /** Semantic slot metadata */
+  semantic: SlotMetadata;
 }
 
 export class ManduFilling<TLoaderData = unknown> {
@@ -67,8 +70,87 @@ export class ManduFilling<TLoaderData = unknown> {
     handlers: new Map(),
     lifecycle: createLifecycleStore(),
     middleware: [],
+    semantic: {},
   };
 
+  /**
+   * Semantic Slot: 슬롯의 목적 정의
+   * AI가 이 슬롯의 역할을 이해하고 적절한 구현을 하도록 안내
+   *
+   * @example
+   * ```typescript
+   * Mandu.filling()
+   *   .purpose("사용자 목록 조회 API")
+   *   .get(async (ctx) => { ... });
+   * ```
+   */
+  purpose(purposeText: string): this {
+    this.config.semantic.purpose = purposeText;
+    return this;
+  }
+
+  /**
+   * Semantic Slot: 상세 설명 추가
+   *
+   * @example
+   * ```typescript
+   * Mandu.filling()
+   *   .purpose("사용자 목록 조회 API")
+   *   .description("페이지네이션된 사용자 목록 반환. 관리자 전용.")
+   *   .get(async (ctx) => { ... });
+   * ```
+   */
+  description(descText: string): this {
+    this.config.semantic.description = descText;
+    return this;
+  }
+
+  /**
+   * Semantic Slot: 제약 조건 정의
+   * AI가 이 범위 내에서만 구현하도록 제한
+   *
+   * @example
+   * ```typescript
+   * Mandu.filling()
+   *   .purpose("사용자 목록 조회 API")
+   *   .constraints({
+   *     maxLines: 50,
+   *     maxCyclomaticComplexity: 10,
+   *     requiredPatterns: ["input-validation", "error-handling"],
+   *     forbiddenPatterns: ["direct-db-write"],
+   *     allowedImports: ["server/domain/user/*", "shared/utils/*"],
+   *   })
+   *   .get(async (ctx) => { ... });
+   * ```
+   */
+  constraints(constraintsConfig: SlotConstraints): this {
+    this.config.semantic.constraints = constraintsConfig;
+    return this;
+  }
+
+  /**
+   * Semantic Slot: 태그 추가 (검색 및 분류용)
+   */
+  tags(...tagList: string[]): this {
+    this.config.semantic.tags = tagList;
+    return this;
+  }
+
+  /**
+   * Semantic Slot: 소유자/담당자 지정
+   */
+  owner(ownerName: string): this {
+    this.config.semantic.owner = ownerName;
+    return this;
+  }
+
+  /**
+   * 슬롯 메타데이터 가져오기
+   */
+  getSemanticMetadata(): SlotMetadata {
+    return { ...this.config.semantic };
+  }
+
   loader(loaderFn: Loader<TLoaderData>): this {
     this.config.loader = loaderFn;
     return this;
@@ -81,7 +163,7 @@ export class ManduFilling<TLoaderData = unknown> {
     if (!this.config.loader) {
       return undefined;
     }
-    const { timeout = TIMEOUTS.LOADER_DEFAULT, fallback } = options;
+    const { timeout = TIMEOUTS.LOADER_DEFAULT, fallback } = options;
     try {
       const loaderPromise = Promise.resolve(this.config.loader(ctx));
       const timeoutPromise = new Promise<never>((_, reject) => {

package/src/guard/analyzer.ts

@@ -4,7 +4,7 @@
  * 파일 분석 및 Import 추출
  */
 
-import { readFile } from "fs/promises";
+import { safeReadFile } from "../utils/safe-io";
 import { dirname, isAbsolute, relative, resolve } from "path";
 import { minimatch } from "minimatch";
 import type {
@@ -263,7 +263,12 @@ export async function analyzeFile(
   layers: LayerDefinition[],
   rootDir: string
 ): Promise<FileAnalysis> {
-  const content = await readFile(filePath, "utf-8");
+  const result = await safeReadFile(filePath);
+  if (!result.ok) {
+    throw new Error(`파일 분석 실패: ${filePath} - ${result.error.message}`);
+  }
+
+  const content = result.value;
   const imports = extractImports(content);
   const layer = resolveFileLayer(filePath, layers, rootDir);
   const slice = layer ? extractSlice(filePath, layer) : undefined;