@mandujs/core 0.9.45 → 0.10.0

package/src/guard/config-guard.ts

@@ -0,0 +1,281 @@
+/**
+ * Config Guard - 설정 무결성 검증
+ *
+ * Lockfile을 사용한 설정 무결성 검증을 Guard 시스템에 통합
+ *
+ * @see docs/plans/09_lockfile_integration_plan.md
+ */
+
+import {
+  readLockfile,
+  readMcpConfig,
+  validateLockfile,
+  validateWithPolicy,
+  detectMode,
+  type ManduLockfile,
+  type LockfileValidationResult,
+  type LockfileMode,
+} from "../lockfile";
+import type { ConfigDiff } from "../utils/differ";
+
+// ============================================
+// 타입
+// ============================================
+
+export interface ConfigGuardError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface ConfigGuardWarning {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface ConfigGuardResult {
+  /** 설정 로드 성공 여부 */
+  configValid: boolean;
+  /** lockfile 검증 통과 여부 */
+  lockfileValid: boolean;
+  /** lockfile 존재 여부 */
+  lockfileExists: boolean;
+  /** 심각한 오류 */
+  errors: ConfigGuardError[];
+  /** 경고 */
+  warnings: ConfigGuardWarning[];
+  /** 설정 변경 사항 */
+  diff?: ConfigDiff;
+  /** 현재 해시 */
+  currentHash?: string;
+  /** lockfile 해시 */
+  lockedHash?: string;
+  /** 정책 액션 */
+  action: "pass" | "warn" | "error" | "block";
+  /** 우회 여부 */
+  bypassed: boolean;
+}
+
+export interface ConfigGuardOptions {
+  /** 검증 모드 (환경 자동 감지가 기본) */
+  mode?: LockfileMode;
+}
+
+// ============================================
+// 메인 함수
+// ============================================
+
+/**
+ * 설정 무결성 검증 (Guard 통합용)
+ *
+ * @param rootDir 프로젝트 루트 디렉토리
+ * @param config 현재 설정 객체
+ * @param options 검증 옵션
+ * @returns 검증 결과
+ *
+ * @example
+ * ```typescript
+ * const result = await guardConfig(rootDir, config);
+ * if (!result.lockfileValid) {
+ *   console.error("설정 무결성 검증 실패");
+ * }
+ * ```
+ */
+export async function guardConfig(
+  rootDir: string,
+  config: Record<string, unknown>,
+  options: ConfigGuardOptions = {}
+): Promise<ConfigGuardResult> {
+  const errors: ConfigGuardError[] = [];
+  const warnings: ConfigGuardWarning[] = [];
+
+  // 1. Lockfile 읽기
+  const lockfile = await readLockfile(rootDir);
+  const lockfileExists = lockfile !== null;
+
+  // 1-1. MCP 설정 읽기 (선택)
+  let mcpConfig: Record<string, unknown> | null = null;
+  try {
+    mcpConfig = await readMcpConfig(rootDir);
+  } catch (error) {
+    warnings.push({
+      code: "MCP_CONFIG_PARSE_ERROR",
+      message: `MCP 설정 로드 실패: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+
+  // 2. 정책 기반 검증
+  const mode = options.mode ?? detectMode();
+  const { result, action, bypassed } = validateWithPolicy(config, lockfile, mode, mcpConfig);
+
+  // 3. 결과 처리
+  if (!lockfileExists) {
+    warnings.push({
+      code: "LOCKFILE_NOT_FOUND",
+      message: "Lockfile이 존재하지 않습니다. 'mandu lock'으로 생성하세요.",
+    });
+  }
+
+  if (result) {
+    // 오류 변환
+    for (const error of result.errors) {
+      errors.push({
+        code: error.code,
+        message: error.message,
+        details: error.details,
+      });
+    }
+
+    // 경고 변환
+    for (const warning of result.warnings) {
+      warnings.push({
+        code: warning.code,
+        message: warning.message,
+        details: warning.details,
+      });
+    }
+  }
+
+  return {
+    configValid: true,
+    lockfileValid: result?.valid ?? false,
+    lockfileExists,
+    errors,
+    warnings,
+    diff: result?.diff,
+    currentHash: result?.currentHash,
+    lockedHash: result?.lockedHash,
+    action,
+    bypassed,
+  };
+}
+
+/**
+ * 빠른 무결성 검증 (해시만 비교)
+ */
+export async function quickConfigGuard(
+  rootDir: string,
+  config: Record<string, unknown>
+): Promise<boolean> {
+  const lockfile = await readLockfile(rootDir);
+  if (!lockfile) return true; // lockfile 없으면 통과
+  let mcpConfig: Record<string, unknown> | null = null;
+  try {
+    mcpConfig = await readMcpConfig(rootDir);
+  } catch {
+    // ignore
+  }
+
+  const result = validateLockfile(config, lockfile, mcpConfig);
+  return result.valid;
+}
+
+// ============================================
+// 포맷팅
+// ============================================
+
+/**
+ * Config Guard 결과를 콘솔 메시지로 변환
+ */
+export function formatConfigGuardResult(result: ConfigGuardResult): string {
+  const lines: string[] = [];
+
+  if (result.lockfileValid) {
+    lines.push("✅ 설정 무결성 확인됨");
+    if (result.currentHash) {
+      lines.push(`   해시: ${result.currentHash}`);
+    }
+  } else if (!result.lockfileExists) {
+    lines.push("💡 Lockfile 없음");
+    lines.push("   'mandu lock'으로 생성 권장");
+  } else {
+    lines.push("❌ 설정 무결성 검증 실패");
+
+    for (const error of result.errors) {
+      lines.push(`   🔴 ${error.message}`);
+    }
+  }
+
+  if (result.warnings.length > 0 && result.lockfileExists) {
+    lines.push("");
+    lines.push("   경고:");
+    for (const warning of result.warnings) {
+      lines.push(`   ⚠️  ${warning.message}`);
+    }
+  }
+
+  if (result.bypassed) {
+    lines.push("");
+    lines.push("   ⚡ MANDU_LOCK_BYPASS=1로 우회됨");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Config Guard 결과를 JSON으로 변환 (에이전트용)
+ */
+export function formatConfigGuardAsJSON(result: ConfigGuardResult): string {
+  return JSON.stringify(
+    {
+      ok: result.lockfileValid,
+      lockfileExists: result.lockfileExists,
+      action: result.action,
+      bypassed: result.bypassed,
+      currentHash: result.currentHash,
+      lockedHash: result.lockedHash,
+      errors: result.errors,
+      warnings: result.warnings,
+      hasDiff: result.diff?.hasChanges ?? false,
+    },
+    null,
+    2
+  );
+}
+
+// ============================================
+// 통합 헬스 체크
+// ============================================
+
+export interface UnifiedHealthResult {
+  /** 전체 통과 여부 */
+  ok: boolean;
+  /** 건강 점수 (0-100) */
+  healthScore: number;
+  /** 아키텍처 검증 */
+  architecture: {
+    violations: number;
+    errors: number;
+    warnings: number;
+  };
+  /** 설정 검증 */
+  config: ConfigGuardResult;
+}
+
+/**
+ * 통합 헬스 점수 계산
+ */
+export function calculateHealthScore(
+  archViolations: number,
+  archErrors: number,
+  configResult: ConfigGuardResult
+): number {
+  let score = 100;
+
+  // 아키텍처 위반 감점
+  score -= archErrors * 10;
+  score -= (archViolations - archErrors) * 2;
+
+  // 설정 무결성 감점
+  if (!configResult.lockfileExists) {
+    score -= 5; // lockfile 없음
+  } else if (!configResult.lockfileValid) {
+    score -= 20; // 불일치
+  }
+
+  // 경고 감점
+  score -= configResult.warnings.length * 1;
+
+  return Math.max(0, Math.min(100, score));
+}

package/src/guard/decision-memory.test.ts

@@ -0,0 +1,293 @@
+/**
+ * Decision Memory Tests
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, mkdtemp, readFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  parseADRMarkdown,
+  formatADRAsMarkdown,
+  getAllDecisions,
+  getDecisionById,
+  searchDecisions,
+  saveDecision,
+  checkConsistency,
+  generateCompactArchitecture,
+  getNextDecisionId,
+  type ArchitectureDecision,
+} from "./decision-memory";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test Setup
+// ═══════════════════════════════════════════════════════════════════════════
+
+let TEST_DIR: string;
+
+const SAMPLE_ADR_CONTENT = `# Use JWT for API Authentication
+
+**ID:** ADR-001
+**Status:** accepted
+**Date:** 2024-01-15
+**Tags:** auth, api, security, jwt
+
+## Context
+
+API 인증 방식을 결정해야 합니다. 세션 기반과 토큰 기반 중 선택이 필요합니다.
+
+## Decision
+
+JWT (JSON Web Token) + Refresh Token 조합을 사용합니다.
+- Access Token: 15분 만료
+- Refresh Token: 7일 만료, Redis에 저장
+
+## Consequences
+
+- 토큰 만료 관리가 필요합니다
+- Redis 세션 저장소가 필요합니다
+- Stateless 아키텍처 유지 가능
+
+## Related Decisions
+
+- ADR-002
+`;
+
+const SAMPLE_ADR_CONTENT_2 = `# Use Redis for Session Storage
+
+**ID:** ADR-002
+**Status:** accepted
+**Date:** 2024-01-16
+**Tags:** cache, session, redis, infrastructure
+
+## Context
+
+세션 및 캐시 저장소 선택이 필요합니다.
+
+## Decision
+
+Redis를 통합 캐시/세션 저장소로 사용합니다.
+server/infra/cache/를 통해서만 접근합니다.
+
+## Consequences
+
+- 직접 Redis 클라이언트 사용 금지
+- 캐시 추상화 레이어 필요
+
+## Related Decisions
+
+- ADR-001
+`;
+
+beforeAll(async () => {
+  // 임시 디렉토리 생성
+  TEST_DIR = await mkdtemp(join(tmpdir(), "test-decision-memory-"));
+
+  // spec/decisions 디렉토리 생성
+  await mkdir(join(TEST_DIR, "spec", "decisions"), { recursive: true });
+
+  // 샘플 ADR 파일 생성
+  await Bun.write(
+    join(TEST_DIR, "spec", "decisions", "ADR-001-jwt-auth.md"),
+    SAMPLE_ADR_CONTENT
+  );
+  await Bun.write(
+    join(TEST_DIR, "spec", "decisions", "ADR-002-redis-session.md"),
+    SAMPLE_ADR_CONTENT_2
+  );
+
+  // package.json 생성 (프로젝트 이름용)
+  await Bun.write(
+    join(TEST_DIR, "package.json"),
+    JSON.stringify({ name: "test-project" }, null, 2)
+  );
+});
+
+afterAll(async () => {
+  await rm(TEST_DIR, { recursive: true, force: true });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Unit Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("Decision Memory", () => {
+  describe("parseADRMarkdown", () => {
+    it("should parse ADR markdown correctly", () => {
+      const result = parseADRMarkdown(SAMPLE_ADR_CONTENT, "ADR-001-jwt-auth.md");
+
+      expect(result).not.toBeNull();
+      expect(result!.id).toBe("ADR-001");
+      expect(result!.title).toBe("Use JWT for API Authentication");
+      expect(result!.status).toBe("accepted");
+      expect(result!.date).toBe("2024-01-15");
+      expect(result!.tags).toContain("auth");
+      expect(result!.tags).toContain("jwt");
+      expect(result!.context).toContain("API 인증 방식");
+      expect(result!.decision).toContain("JWT");
+      expect(result!.consequences.length).toBeGreaterThan(0);
+      expect(result!.relatedDecisions).toContain("ADR-002");
+    });
+
+    it("should handle malformed content gracefully", () => {
+      const result = parseADRMarkdown("# Simple Title\n\nSome content", "test.md");
+
+      expect(result).not.toBeNull();
+      expect(result!.title).toBe("Simple Title");
+    });
+  });
+
+  describe("formatADRAsMarkdown", () => {
+    it("should format decision as markdown", () => {
+      const decision: ArchitectureDecision = {
+        id: "ADR-003",
+        title: "Test Decision",
+        status: "proposed",
+        date: "2024-02-01",
+        tags: ["test", "example"],
+        context: "This is the context",
+        decision: "This is the decision",
+        consequences: ["Consequence 1", "Consequence 2"],
+        relatedDecisions: ["ADR-001"],
+      };
+
+      const markdown = formatADRAsMarkdown(decision);
+
+      expect(markdown).toContain("# Test Decision");
+      expect(markdown).toContain("**ID:** ADR-003");
+      expect(markdown).toContain("**Status:** proposed");
+      expect(markdown).toContain("test, example");
+      expect(markdown).toContain("This is the context");
+      expect(markdown).toContain("- Consequence 1");
+      expect(markdown).toContain("- ADR-001");
+    });
+  });
+
+  describe("getAllDecisions", () => {
+    it("should load all decisions from spec/decisions", async () => {
+      const decisions = await getAllDecisions(TEST_DIR);
+
+      expect(decisions.length).toBe(2);
+      expect(decisions[0].id).toBe("ADR-001");
+      expect(decisions[1].id).toBe("ADR-002");
+    });
+
+    it("should return empty array for non-existent directory", async () => {
+      const emptyDir = await mkdtemp(join(tmpdir(), "empty-"));
+      const decisions = await getAllDecisions(emptyDir);
+
+      expect(decisions).toEqual([]);
+
+      await rm(emptyDir, { recursive: true, force: true });
+    });
+  });
+
+  describe("getDecisionById", () => {
+    it("should find decision by ID", async () => {
+      const decision = await getDecisionById(TEST_DIR, "ADR-001");
+
+      expect(decision).not.toBeNull();
+      expect(decision!.title).toBe("Use JWT for API Authentication");
+    });
+
+    it("should return null for non-existent ID", async () => {
+      const decision = await getDecisionById(TEST_DIR, "ADR-999");
+
+      expect(decision).toBeNull();
+    });
+  });
+
+  describe("searchDecisions", () => {
+    it("should find decisions by tags", async () => {
+      const result = await searchDecisions(TEST_DIR, ["auth"]);
+
+      expect(result.decisions.length).toBe(1);
+      expect(result.decisions[0].id).toBe("ADR-001");
+    });
+
+    it("should find decisions by multiple tags", async () => {
+      const result = await searchDecisions(TEST_DIR, ["auth", "cache"]);
+
+      expect(result.decisions.length).toBe(2);
+    });
+
+    it("should return empty for non-matching tags", async () => {
+      const result = await searchDecisions(TEST_DIR, ["nonexistent"]);
+
+      expect(result.decisions.length).toBe(0);
+    });
+
+    it("should perform partial tag matching", async () => {
+      const result = await searchDecisions(TEST_DIR, ["sec"]); // should match "security"
+
+      expect(result.decisions.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("saveDecision", () => {
+    it("should save new decision as markdown file", async () => {
+      const newDecision: Omit<ArchitectureDecision, "date"> = {
+        id: "ADR-003",
+        title: "Use Feature Flags",
+        status: "proposed",
+        tags: ["feature", "deployment"],
+        context: "Need controlled rollout",
+        decision: "Use feature flags for gradual rollout",
+        consequences: ["Need flag management system"],
+      };
+
+      const result = await saveDecision(TEST_DIR, newDecision);
+
+      expect(result.success).toBe(true);
+      expect(result.filePath).toContain("ADR-003");
+
+      // 파일이 실제로 생성되었는지 확인
+      const content = await readFile(result.filePath, "utf-8");
+      expect(content).toContain("Use Feature Flags");
+    });
+  });
+
+  describe("checkConsistency", () => {
+    it("should find related decisions for consistency check", async () => {
+      const result = await checkConsistency(TEST_DIR, "Add caching layer", ["cache"]);
+
+      expect(result.relatedDecisions.length).toBeGreaterThan(0);
+      expect(result.suggestions.length).toBeGreaterThan(0);
+    });
+
+    it("should return consistent=true when no warnings", async () => {
+      const result = await checkConsistency(TEST_DIR, "New feature", ["auth"]);
+
+      // accepted 상태이므로 warning 없음
+      expect(result.consistent).toBe(true);
+    });
+  });
+
+  describe("generateCompactArchitecture", () => {
+    it("should generate compact architecture summary", async () => {
+      const compact = await generateCompactArchitecture(TEST_DIR);
+
+      expect(compact.project).toBe("test-project");
+      expect(compact.keyDecisions.length).toBeGreaterThan(0);
+      expect(compact.tagCounts["auth"]).toBeGreaterThan(0);
+    });
+  });
+
+  describe("getNextDecisionId", () => {
+    it("should return next sequential ID", async () => {
+      // ADR-003을 추가했으므로 다음은 ADR-004
+      const nextId = await getNextDecisionId(TEST_DIR);
+
+      expect(nextId).toBe("ADR-004");
+    });
+
+    it("should return ADR-001 for empty project", async () => {
+      const emptyDir = await mkdtemp(join(tmpdir(), "empty-decisions-"));
+      const nextId = await getNextDecisionId(emptyDir);
+
+      expect(nextId).toBe("ADR-001");
+
+      await rm(emptyDir, { recursive: true, force: true });
+    });
+  });
+});