@mandujs/core 0.9.46 → 0.10.0

package/src/utils/hasher.test.ts

@@ -0,0 +1,326 @@
+/**
+ * 결정론적 해싱 테스트
+ *
+ * @see docs/plans/08_ont-run_adoption_plan.md - 섹션 7.1
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  computeConfigHash,
+  verifyConfigIntegrity,
+  compareConfigHashes,
+  normalizeForHash,
+  isHashable,
+} from "./hasher.js";
+
+describe("computeConfigHash", () => {
+  it("should produce same hash regardless of key order", () => {
+    const config1 = { a: 1, b: 2, c: 3 };
+    const config2 = { c: 3, a: 1, b: 2 };
+    const config3 = { b: 2, c: 3, a: 1 };
+
+    const hash1 = computeConfigHash(config1);
+    const hash2 = computeConfigHash(config2);
+    const hash3 = computeConfigHash(config3);
+
+    expect(hash1).toBe(hash2);
+    expect(hash2).toBe(hash3);
+  });
+
+  it("should produce different hash for different values", () => {
+    const config1 = { a: 1 };
+    const config2 = { a: 2 };
+
+    expect(computeConfigHash(config1)).not.toBe(computeConfigHash(config2));
+  });
+
+  it("should handle nested objects with deterministic ordering", () => {
+    const config1 = {
+      server: { port: 3000, host: "localhost" },
+      database: { url: "postgres://...", pool: 10 },
+    };
+    const config2 = {
+      database: { pool: 10, url: "postgres://..." },
+      server: { host: "localhost", port: 3000 },
+    };
+
+    expect(computeConfigHash(config1)).toBe(computeConfigHash(config2));
+  });
+
+  it("should handle arrays (order matters)", () => {
+    const config1 = { items: [1, 2, 3] };
+    const config2 = { items: [1, 2, 3] };
+    const config3 = { items: [3, 2, 1] };
+
+    expect(computeConfigHash(config1)).toBe(computeConfigHash(config2));
+    expect(computeConfigHash(config1)).not.toBe(computeConfigHash(config3));
+  });
+
+  it("should exclude specified keys", () => {
+    const config1 = { a: 1, secret: "abc123" };
+    const config2 = { a: 1, secret: "xyz789" };
+
+    const hash1 = computeConfigHash(config1, { exclude: ["secret"] });
+    const hash2 = computeConfigHash(config2, { exclude: ["secret"] });
+
+    expect(hash1).toBe(hash2);
+  });
+
+  it("should produce hash of specified length", () => {
+    const config = { test: "value" };
+
+    expect(computeConfigHash(config, { length: 8 })).toHaveLength(8);
+    expect(computeConfigHash(config, { length: 16 })).toHaveLength(16);
+    expect(computeConfigHash(config, { length: 32 })).toHaveLength(32);
+  });
+
+  it("should handle empty objects", () => {
+    expect(() => computeConfigHash({})).not.toThrow();
+    expect(computeConfigHash({})).toHaveLength(16);
+  });
+
+  it("should handle null and undefined", () => {
+    expect(() => computeConfigHash(null)).not.toThrow();
+    expect(() => computeConfigHash(undefined)).not.toThrow();
+  });
+});
+
+describe("normalizeForHash", () => {
+  it("should convert Date to ISO string", () => {
+    const date = new Date("2025-01-28T00:00:00.000Z");
+    const normalized = normalizeForHash({ date });
+
+    expect(normalized).toEqual({ date: "2025-01-28T00:00:00.000Z" });
+  });
+
+  it("should convert BigInt to string with n suffix", () => {
+    const normalized = normalizeForHash({ big: BigInt(12345) });
+
+    expect(normalized).toEqual({ big: "12345n" });
+  });
+
+  it("should convert URL to href string", () => {
+    const url = new URL("https://example.com/path?query=1");
+    const normalized = normalizeForHash({ url });
+
+    expect(normalized).toEqual({ url: "https://example.com/path?query=1" });
+  });
+
+  it("should convert RegExp to string", () => {
+    const normalized = normalizeForHash({ pattern: /test/gi });
+
+    expect(normalized).toEqual({ pattern: "/test/gi" });
+  });
+
+  it("should remove functions by default", () => {
+    const normalized = normalizeForHash({
+      a: 1,
+      fn: () => console.log("test"),
+    });
+
+    expect(normalized).toEqual({ a: 1 });
+  });
+
+  it("should remove Symbol by default", () => {
+    const normalized = normalizeForHash({
+      a: 1,
+      sym: Symbol("test"),
+    });
+
+    expect(normalized).toEqual({ a: 1 });
+  });
+
+  it("should remove undefined values (like JSON.stringify)", () => {
+    const normalized = normalizeForHash({
+      a: 1,
+      b: undefined,
+      c: 3,
+    });
+
+    expect(normalized).toEqual({ a: 1, c: 3 });
+  });
+
+  it("should handle Map as sorted entries", () => {
+    const map = new Map([
+      ["z", 1],
+      ["a", 2],
+      ["m", 3],
+    ]);
+    const normalized = normalizeForHash({ data: map }) as any;
+
+    expect(normalized.data.__type__).toBe("Map");
+    expect(normalized.data.entries[0][0]).toBe("a"); // 정렬됨
+  });
+
+  it("should handle Set as sorted array", () => {
+    const set = new Set([3, 1, 2]);
+    const normalized = normalizeForHash({ data: set }) as any;
+
+    expect(normalized.data.__type__).toBe("Set");
+    expect(normalized.data.items).toEqual([1, 2, 3]); // 정렬됨
+  });
+
+  it("should detect circular references", () => {
+    const obj: any = { a: 1 };
+    obj.self = obj;
+
+    const normalized = normalizeForHash(obj) as any;
+    expect(normalized.self).toBe("__circular__");
+  });
+
+  it("should handle NaN, Infinity, -Infinity", () => {
+    const normalized = normalizeForHash({
+      nan: NaN,
+      inf: Infinity,
+      negInf: -Infinity,
+    });
+
+    expect(normalized).toEqual({
+      nan: "__NaN__",
+      inf: "__Infinity__",
+      negInf: "__-Infinity__",
+    });
+  });
+
+  it("should normalize Error objects", () => {
+    const error = new TypeError("test error");
+    const normalized = normalizeForHash({ error }) as any;
+
+    expect(normalized.error.__type__).toBe("Error");
+    expect(normalized.error.name).toBe("TypeError");
+    expect(normalized.error.message).toBe("test error");
+  });
+});
+
+describe("verifyConfigIntegrity", () => {
+  it("should return true for matching config and hash", () => {
+    const config = { server: { port: 3000 }, debug: true };
+    const hash = computeConfigHash(config);
+
+    expect(verifyConfigIntegrity(config, hash)).toBe(true);
+  });
+
+  it("should return false for modified config", () => {
+    const config = { server: { port: 3000 }, debug: true };
+    const hash = computeConfigHash(config);
+
+    const modifiedConfig = { server: { port: 3001 }, debug: true };
+
+    expect(verifyConfigIntegrity(modifiedConfig, hash)).toBe(false);
+  });
+
+  it("should work with exclude option", () => {
+    const config = { a: 1, timestamp: Date.now() };
+    const hash = computeConfigHash(config, { exclude: ["timestamp"] });
+
+    // timestamp가 달라도 해시는 같아야 함
+    const laterConfig = { a: 1, timestamp: Date.now() + 1000 };
+
+    expect(verifyConfigIntegrity(laterConfig, hash, { exclude: ["timestamp"] })).toBe(true);
+  });
+});
+
+describe("compareConfigHashes", () => {
+  it("should compare two configs", () => {
+    const config1 = { a: 1, b: 2 };
+    const config2 = { b: 2, a: 1 };
+    const config3 = { a: 1, b: 3 };
+
+    const result1 = compareConfigHashes(config1, config2);
+    const result2 = compareConfigHashes(config1, config3);
+
+    expect(result1.equal).toBe(true);
+    expect(result2.equal).toBe(false);
+  });
+});
+
+describe("isHashable", () => {
+  it("should return true for hashable values", () => {
+    expect(isHashable({ a: 1 })).toBe(true);
+    expect(isHashable([1, 2, 3])).toBe(true);
+    expect(isHashable("string")).toBe(true);
+    expect(isHashable(123)).toBe(true);
+    expect(isHashable(null)).toBe(true);
+    expect(isHashable(new Date())).toBe(true);
+  });
+
+  it("should return false for unhashable values", () => {
+    expect(isHashable(undefined)).toBe(false);
+    expect(isHashable(() => {})).toBe(false);
+    expect(isHashable(Symbol("test"))).toBe(false);
+  });
+});
+
+describe("real-world scenarios", () => {
+  it("should handle mandu config-like structure", () => {
+    const manduConfig = {
+      name: "my-project",
+      port: 3000,
+      mcpServers: {
+        sequential: {
+          command: "npx",
+          args: ["-y", "@anthropic/sequential-mcp"],
+        },
+        context7: {
+          command: "npx",
+          args: ["-y", "@context7/mcp"],
+        },
+      },
+      features: {
+        islands: true,
+        ssr: true,
+      },
+    };
+
+    const hash = computeConfigHash(manduConfig);
+    expect(hash).toHaveLength(16);
+
+    // 키 순서가 다른 동일한 설정
+    const sameConfigDifferentOrder = {
+      features: {
+        ssr: true,
+        islands: true,
+      },
+      mcpServers: {
+        context7: {
+          args: ["-y", "@context7/mcp"],
+          command: "npx",
+        },
+        sequential: {
+          args: ["-y", "@anthropic/sequential-mcp"],
+          command: "npx",
+        },
+      },
+      port: 3000,
+      name: "my-project",
+    };
+
+    expect(computeConfigHash(sameConfigDifferentOrder)).toBe(hash);
+  });
+
+  it("should handle MCP config with sensitive data exclusion", () => {
+    const mcpConfig1 = {
+      servers: {
+        api: {
+          url: "https://api.example.com",
+          token: "secret-token-123",
+        },
+      },
+    };
+
+    const mcpConfig2 = {
+      servers: {
+        api: {
+          url: "https://api.example.com",
+          token: "different-token-456",
+        },
+      },
+    };
+
+    // token을 제외하면 동일한 해시
+    const hash1 = computeConfigHash(mcpConfig1, { exclude: ["token"] });
+    const hash2 = computeConfigHash(mcpConfig2, { exclude: ["token"] });
+
+    expect(hash1).toBe(hash2);
+  });
+});

package/src/utils/hasher.ts

@@ -0,0 +1,319 @@
+/**
+ * Mandu 결정론적 해싱 유틸리티 🔐
+ *
+ * ont-run의 해싱 기법을 참고하여 구현
+ * @see DNA/ont-run/src/lockfile/hasher.ts
+ *
+ * 특징:
+ * - 키 순서에 관계없이 동일한 해시 생성 (결정론적)
+ * - 비직렬화 요소(함수, Date, BigInt 등) 정규화
+ * - 민감 키 제외 옵션
+ */
+
+import { createHash } from "node:crypto";
+
+// ============================================
+// 타입 정의
+// ============================================
+
+export interface HashOptions {
+  /** 해시 알고리즘 (기본값: sha256) */
+  algorithm?: "sha256";
+  /** 해시 길이 (기본값: 16) */
+  length?: number;
+  /** 해시에서 제외할 키 */
+  exclude?: string[];
+}
+
+export interface NormalizeOptions {
+  /** 제외할 키 패턴 */
+  exclude?: string[];
+  /** Date를 ISO 문자열로 변환 (기본값: true) */
+  dateToIso?: boolean;
+  /** BigInt를 문자열로 변환 (기본값: true) */
+  bigintToString?: boolean;
+  /** Map/Set을 배열로 변환 (기본값: true) */
+  collectionToArray?: boolean;
+  /** 함수 제거 (기본값: true) */
+  removeFunction?: boolean;
+  /** Symbol 제거 (기본값: true) */
+  removeSymbol?: boolean;
+}
+
+// ============================================
+// 정규화
+// ============================================
+
+/**
+ * 객체를 해싱 가능한 형태로 정규화
+ *
+ * 정규화 규칙:
+ * 1. 키를 알파벳 순으로 정렬
+ * 2. undefined 키 제거 (JSON.stringify와 동일)
+ * 3. 함수, Symbol 제거
+ * 4. Date → ISO 문자열
+ * 5. BigInt → 문자열 + 'n' 접미사
+ * 6. Map → [key, value] 배열
+ * 7. Set → 정렬된 배열
+ * 8. 순환 참조 감지
+ */
+export function normalizeForHash(
+  value: unknown,
+  options: NormalizeOptions = {},
+  seen: WeakSet<object> = new WeakSet()
+): unknown {
+  const {
+    exclude = [],
+    dateToIso = true,
+    bigintToString = true,
+    collectionToArray = true,
+    removeFunction = true,
+    removeSymbol = true,
+  } = options;
+
+  // null
+  if (value === null) return null;
+
+  // undefined → 제거됨 (반환하지 않음)
+  if (value === undefined) return undefined;
+
+  // 원시형
+  if (typeof value === "boolean" || typeof value === "number") {
+    // NaN, Infinity 처리
+    if (Number.isNaN(value)) return "__NaN__";
+    if (value === Infinity) return "__Infinity__";
+    if (value === -Infinity) return "__-Infinity__";
+    return value;
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  // BigInt
+  if (typeof value === "bigint") {
+    return bigintToString ? `${value}n` : value;
+  }
+
+  // Symbol
+  if (typeof value === "symbol") {
+    return removeSymbol ? undefined : `Symbol(${value.description ?? ""})`;
+  }
+
+  // 함수
+  if (typeof value === "function") {
+    return removeFunction ? undefined : `[Function: ${value.name || "anonymous"}]`;
+  }
+
+  // 객체 타입 처리
+  if (typeof value === "object") {
+    // 순환 참조 감지
+    if (seen.has(value)) {
+      return "__circular__";
+    }
+    seen.add(value);
+
+    // Date
+    if (value instanceof Date) {
+      return dateToIso ? value.toISOString() : value;
+    }
+
+    // URL
+    if (value instanceof URL) {
+      return value.href;
+    }
+
+    // RegExp
+    if (value instanceof RegExp) {
+      return value.toString();
+    }
+
+    // Error
+    if (value instanceof Error) {
+      return {
+        __type__: "Error",
+        name: value.name,
+        message: value.message,
+      };
+    }
+
+    // Map
+    if (value instanceof Map) {
+      if (!collectionToArray) return value;
+      const entries: [unknown, unknown][] = [];
+      for (const [k, v] of value.entries()) {
+        entries.push([
+          normalizeForHash(k, options, seen),
+          normalizeForHash(v, options, seen),
+        ]);
+      }
+      // 키로 정렬 (결정론적)
+      entries.sort((a, b) => {
+        const aKey = toSortableString(a[0]);
+        const bKey = toSortableString(b[0]);
+        return aKey.localeCompare(bKey);
+      });
+      return { __type__: "Map", entries };
+    }
+
+    // Set
+    if (value instanceof Set) {
+      if (!collectionToArray) return value;
+      const items: unknown[] = [];
+      for (const item of value) {
+        items.push(normalizeForHash(item, options, seen));
+      }
+      // 정렬 (결정론적)
+      items.sort((a, b) => {
+        const aStr = toSortableString(a);
+        const bStr = toSortableString(b);
+        return aStr.localeCompare(bStr);
+      });
+      return { __type__: "Set", items };
+    }
+
+    // 배열
+    if (Array.isArray(value)) {
+      return value.map((item) => normalizeForHash(item, options, seen));
+    }
+
+    // 일반 객체 - 키 정렬
+    const sortedKeys = Object.keys(value).sort();
+    const result: Record<string, unknown> = {};
+
+    for (const key of sortedKeys) {
+      // 제외 키 체크
+      if (exclude.includes(key)) continue;
+
+      const v = (value as Record<string, unknown>)[key];
+      const normalized = normalizeForHash(v, options, seen);
+
+      // undefined는 포함하지 않음 (JSON.stringify와 동일)
+      if (normalized !== undefined) {
+        result[key] = normalized;
+      }
+    }
+
+    return result;
+  }
+
+  return value;
+}
+
+// ============================================
+// 해싱
+// ============================================
+
+/**
+ * 설정 객체의 결정론적 해시 계산
+ *
+ * @example
+ * ```typescript
+ * const hash1 = computeConfigHash({ a: 1, b: 2 });
+ * const hash2 = computeConfigHash({ b: 2, a: 1 });
+ * console.log(hash1 === hash2); // true (키 순서 무관)
+ * ```
+ */
+export function computeConfigHash(
+  config: unknown,
+  options: HashOptions = {}
+): string {
+  const { algorithm = "sha256", length = 16, exclude = [] } = options;
+
+  // 1. 정규화
+  const normalized = normalizeForHash(config, { exclude });
+
+  // 2. JSON 문자열화 (이미 정렬되어 있음)
+  // undefined나 함수만 있는 경우 빈 문자열 처리
+  const jsonString = normalized === undefined ? "" : JSON.stringify(normalized);
+
+  // 3. 해싱
+  const hash = createHash(algorithm).update(jsonString).digest("hex");
+
+  // 4. 길이 조절
+  return hash.slice(0, length);
+}
+
+/**
+ * 설정 무결성 검증
+ *
+ * @example
+ * ```typescript
+ * const hash = computeConfigHash(config);
+ * // ... 나중에 ...
+ * const isValid = verifyConfigIntegrity(config, hash);
+ * ```
+ */
+export function verifyConfigIntegrity(
+  config: unknown,
+  expectedHash: string,
+  options: HashOptions = {}
+): boolean {
+  const actualHash = computeConfigHash(config, options);
+  return actualHash === expectedHash;
+}
+
+/**
+ * 두 설정의 해시 비교
+ */
+export function compareConfigHashes(
+  config1: unknown,
+  config2: unknown,
+  options: HashOptions = {}
+): { equal: boolean; hash1: string; hash2: string } {
+  const hash1 = computeConfigHash(config1, options);
+  const hash2 = computeConfigHash(config2, options);
+
+  return {
+    equal: hash1 === hash2,
+    hash1,
+    hash2,
+  };
+}
+
+// ============================================
+// 유틸리티
+// ============================================
+
+/**
+ * 해싱 가능 여부 체크
+ * (정규화 후에도 의미 있는 데이터가 있는지)
+ */
+export function isHashable(value: unknown): boolean {
+  const normalized = normalizeForHash(value);
+  return normalized !== undefined;
+}
+
+/**
+ * 해시 충돌 가능성 경고 (개발용)
+ * 16자 해시의 충돌 확률은 매우 낮지만, 디버깅용으로 제공
+ */
+export function getHashInfo(hash: string): {
+  length: number;
+  bits: number;
+  collisionProbability: string;
+} {
+  const bits = hash.length * 4; // hex는 문자당 4비트
+  // Birthday paradox 근사: sqrt(2^n) 에서 50% 충돌
+  const collisionAt = Math.pow(2, bits / 2);
+
+  return {
+    length: hash.length,
+    bits,
+    collisionProbability: `~${collisionAt.toExponential(2)} 해시에서 50% 충돌 가능`,
+  };
+}
+
+// ============================================
+// 내부 유틸
+// ============================================
+
+function toSortableString(value: unknown): string {
+  try {
+    const json = JSON.stringify(value);
+    if (typeof json === "string") return json;
+  } catch {
+    // ignore
+  }
+  return String(value);
+}

package/src/utils/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Mandu 유틸리티 모듈
+ *
+ * ont-run 기법 도입에 따른 핵심 유틸리티
+ * @see docs/plans/08_ont-run_adoption_plan.md
+ */
+
+// 해싱
+export {
+  computeConfigHash,
+  verifyConfigIntegrity,
+  compareConfigHashes,
+  normalizeForHash,
+  isHashable,
+  getHashInfo,
+  type HashOptions,
+  type NormalizeOptions,
+} from "./hasher.js";
+
+// Diff
+export {
+  diffConfig,
+  formatConfigDiff,
+  printConfigDiff,
+  summarizeDiff,
+  hasConfigChanges,
+  type ConfigDiff,
+  type DiffFormatOptions,
+} from "./differ.js";