@mandujs/core 0.3.2 → 0.3.4

package/src/error/stack-analyzer.ts

@@ -0,0 +1,295 @@
+import type { GeneratedMap } from "../generator/generate";
+
+/**
+ * 스택 프레임 정보
+ */
+export interface StackFrame {
+  /** 파일 경로 */
+  file: string;
+  /** 라인 번호 */
+  line: number;
+  /** 컬럼 번호 (선택) */
+  column?: number;
+  /** 함수 이름 (선택) */
+  functionName?: string;
+  /** 네이티브 코드 여부 */
+  isNative: boolean;
+}
+
+/**
+ * 스택 트레이스 분석기
+ */
+export class StackTraceAnalyzer {
+  /** Generated 파일 매핑 */
+  private generatedMap: GeneratedMap | null;
+  /** 프로젝트 루트 디렉토리 */
+  private rootDir: string;
+
+  constructor(generatedMap: GeneratedMap | null = null, rootDir: string = process.cwd()) {
+    this.generatedMap = generatedMap;
+    this.rootDir = rootDir;
+  }
+
+  /**
+   * Error.stack 문자열을 구조화된 프레임으로 파싱
+   */
+  parseStack(stack: string | undefined): StackFrame[] {
+    if (!stack) return [];
+
+    const frames: StackFrame[] = [];
+    const lines = stack.split("\n");
+
+    for (const line of lines) {
+      const frame = this.parseStackLine(line);
+      if (frame) {
+        frames.push(frame);
+      }
+    }
+
+    return frames;
+  }
+
+  /**
+   * 단일 스택 라인 파싱
+   * V8/Bun 형식: "    at functionName (file:line:column)"
+   *           또는 "    at file:line:column"
+   */
+  private parseStackLine(line: string): StackFrame | null {
+    const trimmed = line.trim();
+
+    // "at " 로 시작하지 않으면 스킵
+    if (!trimmed.startsWith("at ")) {
+      return null;
+    }
+
+    const content = trimmed.slice(3); // "at " 제거
+
+    // 네이티브 코드 체크
+    if (content.includes("[native code]") || content.startsWith("native")) {
+      return {
+        file: "native",
+        line: 0,
+        isNative: true,
+      };
+    }
+
+    // 패턴 1: "functionName (file:line:column)"
+    const withFnMatch = content.match(/^(.+?)\s+\((.+?):(\d+):(\d+)\)$/);
+    if (withFnMatch) {
+      return {
+        functionName: withFnMatch[1],
+        file: this.normalizePath(withFnMatch[2]),
+        line: parseInt(withFnMatch[3], 10),
+        column: parseInt(withFnMatch[4], 10),
+        isNative: false,
+      };
+    }
+
+    // 패턴 2: "functionName (file:line)"
+    const withFnNoColMatch = content.match(/^(.+?)\s+\((.+?):(\d+)\)$/);
+    if (withFnNoColMatch) {
+      return {
+        functionName: withFnNoColMatch[1],
+        file: this.normalizePath(withFnNoColMatch[2]),
+        line: parseInt(withFnNoColMatch[3], 10),
+        isNative: false,
+      };
+    }
+
+    // 패턴 3: "file:line:column"
+    const noFnMatch = content.match(/^(.+?):(\d+):(\d+)$/);
+    if (noFnMatch) {
+      return {
+        file: this.normalizePath(noFnMatch[1]),
+        line: parseInt(noFnMatch[2], 10),
+        column: parseInt(noFnMatch[3], 10),
+        isNative: false,
+      };
+    }
+
+    // 패턴 4: "file:line"
+    const noFnNoColMatch = content.match(/^(.+?):(\d+)$/);
+    if (noFnNoColMatch) {
+      return {
+        file: this.normalizePath(noFnNoColMatch[1]),
+        line: parseInt(noFnNoColMatch[2], 10),
+        isNative: false,
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * 파일 경로 정규화 (상대 경로로 변환)
+   */
+  private normalizePath(filePath: string): string {
+    // Windows 경로 정규화
+    let normalized = filePath.replace(/\\/g, "/");
+
+    // 프로젝트 루트 제거
+    const rootNormalized = this.rootDir.replace(/\\/g, "/");
+    if (normalized.startsWith(rootNormalized)) {
+      normalized = normalized.slice(rootNormalized.length);
+      if (normalized.startsWith("/")) {
+        normalized = normalized.slice(1);
+      }
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Generated 파일인지 확인
+   */
+  isGeneratedFile(file: string): boolean {
+    if (!this.generatedMap) return false;
+
+    const normalized = this.normalizePath(file);
+    return normalized in this.generatedMap.files;
+  }
+
+  /**
+   * Slot 파일인지 확인
+   */
+  isSlotFile(file: string): boolean {
+    const normalized = this.normalizePath(file);
+
+    // slots 디렉토리 내 파일
+    if (normalized.includes("/slots/") || normalized.includes("\\slots\\")) {
+      return true;
+    }
+
+    // spec/slots 패턴
+    if (normalized.startsWith("spec/slots/")) {
+      return true;
+    }
+
+    // GeneratedMap의 slotMapping 확인
+    if (this.generatedMap) {
+      for (const entry of Object.values(this.generatedMap.files)) {
+        if (entry.slotMapping?.slotPath === normalized) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Spec 파일인지 확인
+   */
+  isSpecFile(file: string): boolean {
+    const normalized = this.normalizePath(file);
+
+    // spec/ 디렉토리 내 JSON 파일
+    if (normalized.startsWith("spec/") && normalized.endsWith(".json")) {
+      return true;
+    }
+
+    // spec 로더/스키마 파일
+    if (normalized.includes("spec/load") || normalized.includes("spec/schema")) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * 프레임워크 내부 파일인지 확인
+   */
+  isFrameworkFile(file: string): boolean {
+    const normalized = this.normalizePath(file);
+
+    // @mandujs/core 패키지
+    if (normalized.includes("@mandujs/core")) {
+      return true;
+    }
+
+    // packages/core/src 내부
+    if (normalized.includes("packages/core/src")) {
+      return true;
+    }
+
+    // node_modules 내부 (프레임워크 제외한 외부 라이브러리)
+    if (normalized.includes("node_modules") && !normalized.includes("@mandujs")) {
+      return false; // 외부 라이브러리는 프레임워크로 취급 안 함
+    }
+
+    // GeneratedMap의 frameworkPaths 확인
+    if (this.generatedMap?.frameworkPaths) {
+      for (const pattern of this.generatedMap.frameworkPaths) {
+        if (normalized.includes(pattern)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * 스택에서 "blame frame" 찾기 (첫 번째 사용자 관련 프레임)
+   */
+  findBlameFrame(frames: StackFrame[]): StackFrame | null {
+    for (const frame of frames) {
+      if (frame.isNative) continue;
+
+      // Slot 파일 우선
+      if (this.isSlotFile(frame.file)) {
+        return frame;
+      }
+
+      // Spec 파일
+      if (this.isSpecFile(frame.file)) {
+        return frame;
+      }
+    }
+
+    // Slot/Spec이 없으면 첫 번째 non-native 프레임
+    for (const frame of frames) {
+      if (!frame.isNative && !this.isFrameworkFile(frame.file)) {
+        return frame;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Generated 파일 위치를 Slot 위치로 매핑
+   */
+  mapToSlotLocation(generatedFile: string, _line: number): { file: string; line: number } | null {
+    if (!this.generatedMap) return null;
+
+    const normalized = this.normalizePath(generatedFile);
+    const entry = this.generatedMap.files[normalized];
+
+    if (!entry?.slotMapping) return null;
+
+    // Slot 파일의 시작 위치 반환 (정확한 라인 매핑은 향후 개선)
+    return {
+      file: entry.slotMapping.slotPath,
+      line: 1,
+    };
+  }
+
+  /**
+   * 에러 출처 타입 결정
+   */
+  determineErrorSource(
+    frames: StackFrame[]
+  ): "slot" | "spec" | "generated" | "framework" | "unknown" {
+    for (const frame of frames) {
+      if (frame.isNative) continue;
+
+      if (this.isSlotFile(frame.file)) return "slot";
+      if (this.isSpecFile(frame.file)) return "spec";
+      if (this.isGeneratedFile(frame.file)) return "generated";
+      if (this.isFrameworkFile(frame.file)) return "framework";
+    }
+
+    return "unknown";
+  }
+}

package/src/error/types.ts

@@ -0,0 +1,140 @@
+/**
+ * 에러 타입 분류
+ */
+export type ErrorType = "SPEC_ERROR" | "LOGIC_ERROR" | "FRAMEWORK_BUG";
+
+/**
+ * 에러 코드 체계
+ * - SPEC_ERROR: E1xx
+ * - LOGIC_ERROR: E2xx
+ * - FRAMEWORK_BUG: Fxxx
+ */
+export enum ErrorCode {
+  // SPEC_ERROR (1xx)
+  SPEC_NOT_FOUND = "MANDU_E101",
+  SPEC_PARSE_ERROR = "MANDU_E102",
+  SPEC_VALIDATION_ERROR = "MANDU_E103",
+  SPEC_ROUTE_DUPLICATE = "MANDU_E104",
+  SPEC_ROUTE_NOT_FOUND = "MANDU_E105",
+
+  // LOGIC_ERROR (2xx)
+  SLOT_NOT_FOUND = "MANDU_E201",
+  SLOT_IMPORT_ERROR = "MANDU_E202",
+  SLOT_RUNTIME_ERROR = "MANDU_E203",
+  SLOT_VALIDATION_ERROR = "MANDU_E204",
+  SLOT_HANDLER_ERROR = "MANDU_E205",
+
+  // FRAMEWORK_BUG (Fxx)
+  FRAMEWORK_GENERATOR_ERROR = "MANDU_F001",
+  FRAMEWORK_SSR_ERROR = "MANDU_F002",
+  FRAMEWORK_ROUTER_ERROR = "MANDU_F003",
+  FRAMEWORK_INTERNAL = "MANDU_F999",
+}
+
+/**
+ * 수정 대상 정보
+ */
+export interface FixTarget {
+  /** 수정해야 할 파일 경로 */
+  file: string;
+  /** 수정 가이드 */
+  suggestion: string;
+  /** 라인 번호 (선택) */
+  line?: number;
+}
+
+/**
+ * 라우트 컨텍스트
+ */
+export interface RouteContext {
+  /** 라우트 ID */
+  id: string;
+  /** URL 패턴 */
+  pattern: string;
+  /** 라우트 종류 */
+  kind?: "api" | "page";
+}
+
+/**
+ * 디버그 정보 (개발 모드에서만 포함)
+ */
+export interface DebugInfo {
+  /** 스택 트레이스 */
+  stack: string;
+  /** 원본 에러 메시지 */
+  originalError: string;
+  /** Generated 파일 경로 (있는 경우) */
+  generatedFile?: string;
+}
+
+/**
+ * Mandu 에러 응답 구조
+ */
+export interface ManduError {
+  /** 에러 타입 */
+  errorType: ErrorType;
+  /** 에러 코드 */
+  code: ErrorCode | string;
+  /** 에러 메시지 */
+  message: string;
+  /** 한줄 요약 (에이전트용) */
+  summary: string;
+  /** 수정 대상 정보 */
+  fix: FixTarget;
+  /** 라우트 컨텍스트 (있는 경우) */
+  route?: RouteContext;
+  /** 디버그 정보 (개발 모드) */
+  debug?: DebugInfo;
+  /** 타임스탬프 */
+  timestamp: string;
+}
+
+/**
+ * 에러 코드 → 메시지 매핑
+ */
+export const ERROR_MESSAGES: Record<ErrorCode, string> = {
+  // SPEC_ERROR
+  [ErrorCode.SPEC_NOT_FOUND]: "Spec 파일을 찾을 수 없습니다",
+  [ErrorCode.SPEC_PARSE_ERROR]: "Spec 파일 파싱 오류",
+  [ErrorCode.SPEC_VALIDATION_ERROR]: "Spec 스키마 검증 실패",
+  [ErrorCode.SPEC_ROUTE_DUPLICATE]: "라우트 패턴 중복",
+  [ErrorCode.SPEC_ROUTE_NOT_FOUND]: "라우트를 찾을 수 없습니다",
+
+  // LOGIC_ERROR
+  [ErrorCode.SLOT_NOT_FOUND]: "Slot 파일을 찾을 수 없습니다",
+  [ErrorCode.SLOT_IMPORT_ERROR]: "Slot 파일 import 오류",
+  [ErrorCode.SLOT_RUNTIME_ERROR]: "Slot 런타임 오류",
+  [ErrorCode.SLOT_VALIDATION_ERROR]: "입력 검증 실패",
+  [ErrorCode.SLOT_HANDLER_ERROR]: "핸들러 실행 오류",
+
+  // FRAMEWORK_BUG
+  [ErrorCode.FRAMEWORK_GENERATOR_ERROR]: "Generator 내부 오류",
+  [ErrorCode.FRAMEWORK_SSR_ERROR]: "SSR 렌더링 오류",
+  [ErrorCode.FRAMEWORK_ROUTER_ERROR]: "Router 내부 오류",
+  [ErrorCode.FRAMEWORK_INTERNAL]: "알 수 없는 내부 오류",
+};
+
+/**
+ * 에러 코드 → 요약 매핑
+ */
+export const ERROR_SUMMARIES: Record<ErrorCode, string> = {
+  // SPEC_ERROR
+  [ErrorCode.SPEC_NOT_FOUND]: "Spec 파일 없음 - spec 디렉토리 확인 필요",
+  [ErrorCode.SPEC_PARSE_ERROR]: "Spec 파싱 오류 - JSON 문법 확인 필요",
+  [ErrorCode.SPEC_VALIDATION_ERROR]: "Spec 검증 실패 - 스키마 확인 필요",
+  [ErrorCode.SPEC_ROUTE_DUPLICATE]: "라우트 중복 - spec 파일 수정 필요",
+  [ErrorCode.SPEC_ROUTE_NOT_FOUND]: "라우트 없음 - spec 파일에 추가 필요",
+
+  // LOGIC_ERROR
+  [ErrorCode.SLOT_NOT_FOUND]: "Slot 파일 없음 - generate 실행 필요",
+  [ErrorCode.SLOT_IMPORT_ERROR]: "Slot import 오류 - slot 파일 확인 필요",
+  [ErrorCode.SLOT_RUNTIME_ERROR]: "Slot 런타임 오류 - slot 파일 수정 필요",
+  [ErrorCode.SLOT_VALIDATION_ERROR]: "입력 검증 실패 - 요청 데이터 확인 필요",
+  [ErrorCode.SLOT_HANDLER_ERROR]: "핸들러 오류 - slot 파일 수정 필요",
+
+  // FRAMEWORK_BUG
+  [ErrorCode.FRAMEWORK_GENERATOR_ERROR]: "Generator 오류 - 버그 리포트 필요",
+  [ErrorCode.FRAMEWORK_SSR_ERROR]: "SSR 오류 - 버그 리포트 필요",
+  [ErrorCode.FRAMEWORK_ROUTER_ERROR]: "Router 오류 - 버그 리포트 필요",
+  [ErrorCode.FRAMEWORK_INTERNAL]: "내부 오류 - 버그 리포트 필요",
+};