@mandujs/core 0.9.46 → 0.11.0

package/src/lockfile/validate.ts

@@ -0,0 +1,308 @@
+/**
+ * Mandu Lockfile 검증 ✅
+ *
+ * Lockfile과 현재 설정의 일치 여부 검증
+ */
+
+import { diffConfig } from "../utils/differ.js";
+import { computeCurrentHashes, resolveMcpSources } from "./generate.js";
+import {
+  type ManduLockfile,
+  type LockfileValidationResult,
+  type LockfileError,
+  type LockfileWarning,
+  type LockfileMode,
+  type LockfilePolicyOptions,
+  DEFAULT_POLICIES,
+  LOCKFILE_SCHEMA_VERSION,
+  BYPASS_ENV_VAR,
+} from "./types.js";
+
+// ============================================
+// 검증
+// ============================================
+
+/**
+ * Lockfile 검증
+ *
+ * @param config 현재 설정
+ * @param lockfile Lockfile 데이터
+ * @returns 검증 결과
+ *
+ * @example
+ * ```typescript
+ * const lockfile = await readLockfile(projectRoot);
+ * if (lockfile) {
+ *   const result = validateLockfile(config, lockfile);
+ *   if (!result.valid) {
+ *     console.error("Lockfile mismatch:", result.errors);
+ *   }
+ * }
+ * ```
+ */
+export function validateLockfile(
+  config: Record<string, unknown>,
+  lockfile: ManduLockfile,
+  mcpConfig?: Record<string, unknown> | null
+): LockfileValidationResult {
+  const errors: LockfileError[] = [];
+  const warnings: LockfileWarning[] = [];
+
+  // 현재 해시 계산
+  const { configHash, mcpConfigHash } = computeCurrentHashes(config, mcpConfig);
+  const { mcpServers } = resolveMcpSources(config, mcpConfig);
+
+  // 1. 스키마 버전 체크
+  if (lockfile.schemaVersion !== LOCKFILE_SCHEMA_VERSION) {
+    warnings.push({
+      code: "LOCKFILE_OUTDATED",
+      message: `Lockfile schema version mismatch: expected ${LOCKFILE_SCHEMA_VERSION}, got ${lockfile.schemaVersion}`,
+      details: {
+        expected: LOCKFILE_SCHEMA_VERSION,
+        actual: lockfile.schemaVersion,
+      },
+    });
+  }
+
+  // 2. 설정 해시 비교
+  if (configHash !== lockfile.configHash) {
+    errors.push({
+      code: "CONFIG_HASH_MISMATCH",
+      message: "Configuration has changed since lockfile was generated",
+      details: {
+        expected: lockfile.configHash,
+        actual: configHash,
+      },
+    });
+  }
+
+  // 3. MCP 설정 해시 비교 (있는 경우)
+  if (lockfile.mcpConfigHash && mcpConfigHash !== lockfile.mcpConfigHash) {
+    errors.push({
+      code: "MCP_CONFIG_HASH_MISMATCH",
+      message: "MCP configuration has changed since lockfile was generated",
+      details: {
+        expected: lockfile.mcpConfigHash,
+        actual: mcpConfigHash,
+      },
+    });
+  }
+
+  // 4. MCP 서버 변경 감지
+  if (lockfile.mcpServers && mcpServers) {
+    const lockedServers = new Set(Object.keys(lockfile.mcpServers));
+    const currentServers = new Set(Object.keys(mcpServers));
+
+    // 추가된 서버
+    for (const server of currentServers) {
+      if (!lockedServers.has(server)) {
+        warnings.push({
+          code: "MCP_SERVER_ADDED",
+          message: `MCP server "${server}" was added`,
+          details: { server },
+        });
+      }
+    }
+
+    // 삭제된 서버
+    for (const server of lockedServers) {
+      if (!currentServers.has(server)) {
+        warnings.push({
+          code: "MCP_SERVER_REMOVED",
+          message: `MCP server "${server}" was removed`,
+          details: { server },
+        });
+      }
+    }
+  }
+
+  // 5. 스냅샷 누락 경고
+  if (!lockfile.snapshot) {
+    warnings.push({
+      code: "SNAPSHOT_MISSING",
+      message: "Lockfile does not include configuration snapshot",
+    });
+  }
+
+  // 6. Diff 계산 (오류가 있는 경우에만)
+  let diff;
+  if (errors.length > 0 && lockfile.snapshot) {
+    const configForDiff = mcpServers
+      ? { ...config, mcpServers }
+      : config;
+    diff = diffConfig(lockfile.snapshot.config, configForDiff);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    diff,
+    currentHash: configHash,
+    lockedHash: lockfile.configHash,
+  };
+}
+
+// ============================================
+// 정책 기반 검증
+// ============================================
+
+/**
+ * 환경 정책에 따른 검증 수행
+ */
+export function validateWithPolicy(
+  config: Record<string, unknown>,
+  lockfile: ManduLockfile | null,
+  mode?: LockfileMode,
+  mcpConfig?: Record<string, unknown> | null
+): {
+  result: LockfileValidationResult | null;
+  action: "pass" | "warn" | "error" | "block";
+  bypassed: boolean;
+} {
+  const resolvedMode = mode ?? detectMode();
+  const policy = DEFAULT_POLICIES[resolvedMode];
+  const bypassed = isBypassed();
+
+  // Lockfile 없는 경우
+  if (!lockfile) {
+    const action = bypassed ? "warn" : policy.onMissing;
+    return {
+      result: null,
+      action: action === "create" ? "warn" : action,
+      bypassed,
+    };
+  }
+
+  // 검증 수행
+  const result = validateLockfile(config, lockfile, mcpConfig);
+
+  // 통과
+  if (result.valid) {
+    return { result, action: "pass", bypassed };
+  }
+
+  // 불일치 시 정책 적용
+  const action = bypassed ? "warn" : policy.onMismatch;
+  return { result, action, bypassed };
+}
+
+/**
+ * 현재 모드 감지
+ */
+export function detectMode(): LockfileMode {
+  // CI 환경
+  if (
+    process.env.CI === "true" ||
+    process.env.GITHUB_ACTIONS === "true" ||
+    process.env.GITLAB_CI === "true"
+  ) {
+    return "ci";
+  }
+
+  // 빌드 모드 (npm run build 등)
+  if (process.env.npm_lifecycle_event === "build") {
+    return "build";
+  }
+
+  // 프로덕션
+  if (process.env.NODE_ENV === "production") {
+    return "production";
+  }
+
+  return "development";
+}
+
+/**
+ * 우회 환경변수 체크
+ */
+export function isBypassed(): boolean {
+  return process.env[BYPASS_ENV_VAR] === "1" || process.env[BYPASS_ENV_VAR] === "true";
+}
+
+// ============================================
+// 빠른 검증
+// ============================================
+
+/**
+ * 해시만 빠르게 비교
+ */
+export function quickValidate(
+  config: Record<string, unknown>,
+  lockfile: ManduLockfile,
+  mcpConfig?: Record<string, unknown> | null
+): boolean {
+  const { configHash } = computeCurrentHashes(config, mcpConfig);
+  return configHash === lockfile.configHash;
+}
+
+/**
+ * Lockfile이 최신인지 확인
+ */
+export function isLockfileStale(
+  config: Record<string, unknown>,
+  lockfile: ManduLockfile,
+  mcpConfig?: Record<string, unknown> | null
+): boolean {
+  return !quickValidate(config, lockfile, mcpConfig);
+}
+
+// ============================================
+// 검증 결과 포맷팅
+// ============================================
+
+/**
+ * 검증 결과를 콘솔 메시지로 변환
+ */
+export function formatValidationResult(
+  result: LockfileValidationResult
+): string {
+  const lines: string[] = [];
+
+  if (result.valid) {
+    lines.push("✅ Lockfile 검증 통과");
+    lines.push(`   해시: ${result.currentHash}`);
+  } else {
+    lines.push("❌ Lockfile 검증 실패");
+    lines.push("");
+
+    for (const error of result.errors) {
+      lines.push(`   🔴 ${error.message}`);
+      if (error.details) {
+        lines.push(`      예상: ${error.details.expected}`);
+        lines.push(`      실제: ${error.details.actual}`);
+      }
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push("");
+    lines.push("   경고:");
+    for (const warning of result.warnings) {
+      lines.push(`   ⚠️  ${warning.message}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 정책 액션에 따른 메시지 생성
+ */
+export function formatPolicyAction(
+  action: "pass" | "warn" | "error" | "block",
+  bypassed: boolean
+): string {
+  const bypassNote = bypassed ? " (우회됨)" : "";
+
+  switch (action) {
+    case "pass":
+      return "✅ Lockfile 검증 통과";
+    case "warn":
+      return `⚠️  Lockfile 불일치 - 경고${bypassNote}`;
+    case "error":
+      return `❌ Lockfile 불일치 - 빌드 실패${bypassNote}`;
+    case "block":
+      return `🛑 Lockfile 불일치 - 서버 시작 차단${bypassNote}`;
+  }
+}

package/src/logging/index.ts

@@ -0,0 +1,22 @@
+/**
+ * DNA-008: Structured Logging System
+ *
+ * 구조화된 로깅 시스템
+ * - Transport 기반 다중 출력
+ * - 동적 전송 추가/제거
+ * - 레벨별 필터링
+ */
+
+export {
+  transportRegistry,
+  attachLogTransport,
+  detachLogTransport,
+  entryToTransportRecord,
+  createConsoleTransport,
+  createBufferTransport,
+  createFilteredTransport,
+  createBatchTransport,
+  type LogTransport,
+  type LogTransportRecord,
+  type TransportRegistration,
+} from "./transports.js";

package/src/logging/transports.ts

@@ -0,0 +1,365 @@
+/**
+ * DNA-008: Structured Logging - Transport System
+ *
+ * 로그 전송 레지스트리
+ * - 다중 전송 지원 (콘솔, 파일, 외부 서비스)
+ * - 동적 전송 추가/제거
+ * - 레벨별 필터링
+ */
+
+import type { LogLevel, LogEntry } from "../runtime/logger.js";
+
+/**
+ * 로그 전송 레코드 (Transport에 전달되는 데이터)
+ */
+export interface LogTransportRecord {
+  /** 타임스탬프 (ISO 문자열) */
+  timestamp: string;
+  /** 로그 레벨 */
+  level: LogLevel;
+  /** 요청 ID */
+  requestId?: string;
+  /** HTTP 메서드 */
+  method?: string;
+  /** 요청 경로 */
+  path?: string;
+  /** HTTP 상태 코드 */
+  status?: number;
+  /** 응답 시간 (ms) */
+  duration?: number;
+  /** 에러 정보 */
+  error?: {
+    message: string;
+    stack?: string;
+    code?: string;
+  };
+  /** 커스텀 메타데이터 */
+  meta?: Record<string, unknown>;
+  /** 느린 요청 여부 */
+  slow?: boolean;
+  /** 원본 LogEntry (필요시 접근) */
+  raw?: LogEntry;
+}
+
+/**
+ * 로그 전송 함수 타입
+ */
+export type LogTransport = (record: LogTransportRecord) => void | Promise<void>;
+
+/**
+ * 전송 등록 정보
+ */
+export interface TransportRegistration {
+  /** 전송 ID */
+  id: string;
+  /** 전송 함수 */
+  transport: LogTransport;
+  /** 최소 로그 레벨 (이 레벨 이상만 전송) */
+  minLevel?: LogLevel;
+  /** 활성화 여부 */
+  enabled: boolean;
+}
+
+/**
+ * 로그 레벨 우선순위
+ */
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/**
+ * 전역 전송 레지스트리
+ */
+class TransportRegistry {
+  private transports = new Map<string, TransportRegistration>();
+
+  /**
+   * 전송 추가
+   *
+   * @example
+   * ```ts
+   * attachLogTransport("file", async (record) => {
+   *   await appendFile("app.log", JSON.stringify(record) + "\n");
+   * });
+   * ```
+   */
+  attach(
+    id: string,
+    transport: LogTransport,
+    options: { minLevel?: LogLevel; enabled?: boolean } = {}
+  ): void {
+    this.transports.set(id, {
+      id,
+      transport,
+      minLevel: options.minLevel,
+      enabled: options.enabled ?? true,
+    });
+  }
+
+  /**
+   * 전송 제거
+   */
+  detach(id: string): boolean {
+    return this.transports.delete(id);
+  }
+
+  /**
+   * 전송 활성화/비활성화
+   */
+  setEnabled(id: string, enabled: boolean): void {
+    const registration = this.transports.get(id);
+    if (registration) {
+      registration.enabled = enabled;
+    }
+  }
+
+  /**
+   * 모든 전송에 로그 전달
+   */
+  async dispatch(record: LogTransportRecord): Promise<void> {
+    const recordLevel = LEVEL_PRIORITY[record.level];
+
+    const promises: Promise<void>[] = [];
+
+    for (const registration of this.transports.values()) {
+      if (!registration.enabled) continue;
+
+      // 레벨 필터링
+      if (registration.minLevel) {
+        const minLevel = LEVEL_PRIORITY[registration.minLevel];
+        if (recordLevel < minLevel) continue;
+      }
+
+      try {
+        const result = registration.transport(record);
+        if (result instanceof Promise) {
+          promises.push(result.catch((err) => {
+            console.error(`[Log Transport] Error in ${registration.id}:`, err);
+          }));
+        }
+      } catch (err) {
+        console.error(`[Log Transport] Error in ${registration.id}:`, err);
+      }
+    }
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * 동기적으로 모든 전송에 로그 전달 (비동기 전송은 fire-and-forget)
+   */
+  dispatchSync(record: LogTransportRecord): void {
+    const recordLevel = LEVEL_PRIORITY[record.level];
+
+    for (const registration of this.transports.values()) {
+      if (!registration.enabled) continue;
+
+      if (registration.minLevel) {
+        const minLevel = LEVEL_PRIORITY[registration.minLevel];
+        if (recordLevel < minLevel) continue;
+      }
+
+      try {
+        const result = registration.transport(record);
+        if (result instanceof Promise) {
+          // 비동기 결과는 무시 (fire-and-forget)
+          result.catch((err) => {
+            console.error(`[Log Transport] Error in ${registration.id}:`, err);
+          });
+        }
+      } catch (err) {
+        console.error(`[Log Transport] Error in ${registration.id}:`, err);
+      }
+    }
+  }
+
+  /**
+   * 등록된 전송 목록
+   */
+  list(): TransportRegistration[] {
+    return Array.from(this.transports.values());
+  }
+
+  /**
+   * 전송 존재 여부
+   */
+  has(id: string): boolean {
+    return this.transports.has(id);
+  }
+
+  /**
+   * 모든 전송 제거
+   */
+  clear(): void {
+    this.transports.clear();
+  }
+
+  /**
+   * 전송 개수
+   */
+  get size(): number {
+    return this.transports.size;
+  }
+}
+
+/**
+ * 전역 전송 레지스트리 인스턴스
+ */
+export const transportRegistry = new TransportRegistry();
+
+/**
+ * 로그 전송 추가 (편의 함수)
+ *
+ * @example
+ * ```ts
+ * // 파일 전송
+ * attachLogTransport("file", async (record) => {
+ *   await fs.appendFile("app.log", JSON.stringify(record) + "\n");
+ * }, { minLevel: "info" });
+ *
+ * // 외부 서비스 전송
+ * attachLogTransport("datadog", async (record) => {
+ *   await fetch("https://http-intake.logs.datadoghq.com/...", {
+ *     method: "POST",
+ *     body: JSON.stringify(record),
+ *   });
+ * }, { minLevel: "warn" });
+ * ```
+ */
+export function attachLogTransport(
+  id: string,
+  transport: LogTransport,
+  options?: { minLevel?: LogLevel; enabled?: boolean }
+): void {
+  transportRegistry.attach(id, transport, options);
+}
+
+/**
+ * 로그 전송 제거 (편의 함수)
+ */
+export function detachLogTransport(id: string): boolean {
+  return transportRegistry.detach(id);
+}
+
+/**
+ * LogEntry를 LogTransportRecord로 변환
+ */
+export function entryToTransportRecord(entry: LogEntry): LogTransportRecord {
+  return {
+    timestamp: entry.timestamp,
+    level: entry.level,
+    requestId: entry.requestId,
+    method: entry.method,
+    path: entry.path,
+    status: entry.status,
+    duration: entry.duration,
+    error: entry.error ? {
+      message: entry.error.message,
+      stack: entry.error.stack,
+    } : undefined,
+    slow: entry.slow,
+    raw: entry,
+  };
+}
+
+// ============================================
+// Built-in Transports
+// ============================================
+
+/**
+ * 콘솔 전송 (기본)
+ */
+export function createConsoleTransport(options: {
+  format?: "json" | "pretty";
+} = {}): LogTransport {
+  const { format = "pretty" } = options;
+
+  return (record) => {
+    const output = format === "json"
+      ? JSON.stringify(record)
+      : `[${record.timestamp}] ${record.level.toUpperCase()} ${record.method ?? ""} ${record.path ?? ""} ${record.status ?? ""} ${record.duration ? record.duration.toFixed(0) + "ms" : ""}`;
+
+    switch (record.level) {
+      case "error":
+        console.error(output);
+        break;
+      case "warn":
+        console.warn(output);
+        break;
+      default:
+        console.log(output);
+    }
+  };
+}
+
+/**
+ * 메모리 버퍼 전송 (테스트용)
+ */
+export function createBufferTransport(buffer: LogTransportRecord[]): LogTransport {
+  return (record) => {
+    buffer.push(record);
+  };
+}
+
+/**
+ * 필터링 전송 래퍼
+ */
+export function createFilteredTransport(
+  transport: LogTransport,
+  filter: (record: LogTransportRecord) => boolean
+): LogTransport {
+  return (record) => {
+    if (filter(record)) {
+      return transport(record);
+    }
+  };
+}
+
+/**
+ * 배치 전송 (성능 최적화)
+ */
+export function createBatchTransport(
+  flush: (records: LogTransportRecord[]) => void | Promise<void>,
+  options: {
+    maxSize?: number;
+    flushInterval?: number;
+  } = {}
+): { transport: LogTransport; flush: () => Promise<void>; stop: () => void } {
+  const { maxSize = 100, flushInterval = 5000 } = options;
+
+  const buffer: LogTransportRecord[] = [];
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const doFlush = async () => {
+    if (buffer.length === 0) return;
+    const records = buffer.splice(0, buffer.length);
+    await flush(records);
+  };
+
+  timer = setInterval(() => {
+    doFlush().catch((err) => {
+      console.error("[Batch Transport] Flush error:", err);
+    });
+  }, flushInterval);
+
+  return {
+    transport: (record) => {
+      buffer.push(record);
+      if (buffer.length >= maxSize) {
+        doFlush().catch((err) => {
+          console.error("[Batch Transport] Flush error:", err);
+        });
+      }
+    },
+    flush: doFlush,
+    stop: () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+}