@mandujs/core 0.41.2 → 0.43.0

package/src/testing/snapshot.ts

@@ -1,444 +1,444 @@
-/**
- * @mandujs/core/testing/snapshot
- *
- * `toMatchSnapshot()` assertion helper for Mandu tests — mirrors the Jest
- * API but without the Jest runtime. Snapshots live next to the source
- * file as `__snapshots__/<basename>.snap` and are plain JSON for easy
- * review under `git diff`.
- *
- * ## Why a custom implementation?
- *
- * `bun test` ships its own `toMatchSnapshot`, but it (a) stores files as
- * a non-JSON textual format with newline escaping, (b) has no hook for
- * output normalization, and (c) cannot be invoked imperatively outside
- * of `expect()`. Mandu tests frequently capture generated code, routes
- * manifests, and CLI output — all of which need deterministic scrubbing
- * of timestamps, absolute paths, and random IDs before comparison.
- *
- * This module provides:
- *
- * - `matchSnapshot(value, options)` — pure function returning a
- *   `SnapshotResult`. No dependency on a test runner — callable from
- *   CLI scripts, golden-file tools, or ATE's oracle.
- * - `toMatchSnapshot(value, name)` — test-binding that throws on
- *   mismatch. Designed to be called from `bun:test` `it()` blocks.
- * - Update-in-place via `UPDATE_SNAPSHOTS=1` (or passing
- *   `update: true` programmatically).
- *
- * ## Determinism contract
- *
- * Comparison uses `JSON.stringify` with a **stable key ordering**. This
- * means snapshots are invariant under object-key reordering — which
- * prevents spurious diffs when a handler adds/removes unrelated keys.
- * Arrays preserve order (they are semantically ordered).
- *
- * For timestamps, UUIDs, and other non-deterministic values, pass a
- * `normalize` function that replaces them with stable placeholders
- * before comparison. The tests in `tests/testing/snapshot.test.ts`
- * demonstrate the common patterns.
- *
- * ## Storage layout
- *
- * ```
- * myfeature.test.ts
- * __snapshots__/
- *   myfeature.test.ts.snap   ← JSON map { "snapshot name": "stringified value" }
- * ```
- *
- * The snapshot file is one JSON object — a map of snapshot names to their
- * stringified values. This lets a single test file own many named
- * snapshots (`toMatchSnapshot(x, "user profile")`,
- * `toMatchSnapshot(y, "settings")`) without spamming the filesystem.
- *
- * @module testing/snapshot
- */
-
-import fs from "node:fs";
-import path from "node:path";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Types
-// ═══════════════════════════════════════════════════════════════════════════
-
-/** Options accepted by `matchSnapshot` / `toMatchSnapshot`. */
-export interface SnapshotOptions {
-  /**
-   * Snapshot file path. When omitted, the caller must supply `testFile`
-   * so we can derive `<dir>/__snapshots__/<basename>.snap` automatically.
-   */
-  snapshotPath?: string;
-  /**
-   * Path to the test file the snapshot belongs to. Used to derive
-   * `snapshotPath` when it is not passed explicitly.
-   */
-  testFile?: string;
-  /** Named key inside the snapshot file. Defaults to "default". */
-  name?: string;
-  /**
-   * Force update-in-place regardless of the `UPDATE_SNAPSHOTS` env var.
-   * Useful in golden-file generators or one-shot scripts.
-   */
-  update?: boolean;
-  /**
-   * Pre-comparison transform. Useful to scrub timestamps, random IDs,
-   * or absolute paths so the stored snapshot is stable across runs and
-   * machines.
-   */
-  normalize?: (value: unknown) => unknown;
-}
-
-/** Outcome of a snapshot comparison. */
-export interface SnapshotResult {
-  /** True when the stored snapshot matches (or we just wrote it). */
-  readonly match: boolean;
-  /** True when the file did not exist and we created it. */
-  readonly created: boolean;
-  /** True when we overwrote an existing snapshot (update mode). */
-  readonly updated: boolean;
-  /** The serialized form of the value being snapshotted. */
-  readonly actual: string;
-  /** The stored snapshot — `null` when the file did not exist. */
-  readonly expected: string | null;
-  /** Absolute path of the snapshot file. */
-  readonly snapshotPath: string;
-  /** The key inside the snapshot file. */
-  readonly name: string;
-  /**
-   * Minimal unified-style diff when `match === false`. Empty string
-   * on match or when the snapshot was just created.
-   */
-  readonly diff: string;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Serialization — deterministic JSON
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Stringify `value` with deterministic, sorted object keys. Arrays keep
- * their order (order is semantically meaningful for arrays). Undefined
- * values and functions become `null` so the output is valid JSON across
- * all runtimes.
- *
- * Two-space indent matches `git diff` expectations and keeps snapshots
- * reviewable in PRs. The trailing newline is intentional — `echo` /
- * `cat` don't clobber the last line.
- */
-export function stableStringify(value: unknown): string {
-  const seen = new WeakSet<object>();
-
-  const replacer = (val: unknown): unknown => {
-    if (val === null || typeof val !== "object") return val;
-    if (seen.has(val as object)) return "[Circular]";
-    seen.add(val as object);
-
-    if (Array.isArray(val)) {
-      return val.map(replacer);
-    }
-
-    // Dates / RegExps / Errors — serialize by toString() so they compare by
-    // value instead of structure (empty-object serialization would hide real
-    // differences).
-    if (val instanceof Date) return `[Date ${val.toISOString()}]`;
-    if (val instanceof RegExp) return `[RegExp ${val.toString()}]`;
-    if (val instanceof Error) return `[Error ${val.name}: ${val.message}]`;
-    if (val instanceof Map) {
-      const entries: Array<[string, unknown]> = [];
-      for (const [k, v] of val.entries()) {
-        entries.push([String(k), replacer(v)]);
-      }
-      entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
-      return { __type: "Map", entries };
-    }
-    if (val instanceof Set) {
-      const items = Array.from(val.values()).map(replacer);
-      return { __type: "Set", items };
-    }
-
-    const rec = val as Record<string, unknown>;
-    const keys = Object.keys(rec).sort();
-    const out: Record<string, unknown> = {};
-    for (const k of keys) {
-      const v = rec[k];
-      // Drop undefined/function keys — JSON cannot represent them and we
-      // want the snapshot to elide them rather than fail serialization.
-      if (typeof v === "function" || typeof v === "undefined") continue;
-      out[k] = replacer(v);
-    }
-    return out;
-  };
-
-  const normalized = replacer(value);
-  const serialized = JSON.stringify(normalized, null, 2);
-  return `${serialized ?? "null"}\n`;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Storage IO
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Build the default snapshot path from a test file: co-locate in a
- * `__snapshots__/` directory next to the test.
- */
-export function deriveSnapshotPath(testFile: string): string {
-  const dir = path.dirname(testFile);
-  const base = path.basename(testFile);
-  return path.join(dir, "__snapshots__", `${base}.snap`);
-}
-
-interface SnapshotFile {
-  readonly snapshots: Record<string, string>;
-}
-
-function readSnapshotFile(snapshotPath: string): SnapshotFile | null {
-  if (!fs.existsSync(snapshotPath)) return null;
-  const raw = fs.readFileSync(snapshotPath, "utf8");
-  if (!raw.trim()) return { snapshots: {} };
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    if (
-      typeof parsed !== "object" ||
-      parsed === null ||
-      typeof (parsed as Record<string, unknown>).snapshots !== "object" ||
-      (parsed as Record<string, unknown>).snapshots === null
-    ) {
-      // Legacy / corrupt file — treat as empty so we don't explode in CI.
-      return { snapshots: {} };
-    }
-    const raw_snapshots = (parsed as { snapshots: Record<string, unknown> }).snapshots;
-    const snapshots: Record<string, string> = {};
-    for (const [k, v] of Object.entries(raw_snapshots)) {
-      if (typeof v === "string") snapshots[k] = v;
-    }
-    return { snapshots };
-  } catch {
-    return { snapshots: {} };
-  }
-}
-
-function writeSnapshotFile(snapshotPath: string, file: SnapshotFile): void {
-  const dir = path.dirname(snapshotPath);
-  fs.mkdirSync(dir, { recursive: true });
-  // Sort keys deterministically so new additions don't reshuffle the file.
-  const sorted: Record<string, string> = {};
-  for (const key of Object.keys(file.snapshots).sort()) {
-    sorted[key] = file.snapshots[key];
-  }
-  const body = `${JSON.stringify({ snapshots: sorted }, null, 2)}\n`;
-  fs.writeFileSync(snapshotPath, body, "utf8");
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Diff — tiny line-based delta for failure messages
-// ═══════════════════════════════════════════════════════════════════════════
-
-function computeDiff(expected: string, actual: string): string {
-  const expectedLines = expected.split("\n");
-  const actualLines = actual.split("\n");
-  const max = Math.max(expectedLines.length, actualLines.length);
-  const out: string[] = [];
-  out.push("--- expected (stored snapshot)");
-  out.push("+++ actual   (current value)");
-  for (let i = 0; i < max; i++) {
-    const e = expectedLines[i];
-    const a = actualLines[i];
-    if (e === a) {
-      if (e !== undefined) out.push(`  ${e}`);
-    } else {
-      if (e !== undefined) out.push(`- ${e}`);
-      if (a !== undefined) out.push(`+ ${a}`);
-    }
-  }
-  return out.join("\n");
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Public API
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Whether update-in-place mode is active for this process.
- *
- * Controlled by the `UPDATE_SNAPSHOTS=1` environment variable. Any
- * truthy value (`"1"`, `"true"`) activates. Exported for callers that
- * want to emit different log output in update mode.
- */
-export function isUpdateMode(): boolean {
-  const raw = process.env.UPDATE_SNAPSHOTS;
-  if (!raw) return false;
-  const normalized = raw.toLowerCase();
-  return normalized === "1" || normalized === "true" || normalized === "yes";
-}
-
-/**
- * Compare `value` against the stored snapshot at the resolved path.
- *
- * This is a pure function — it does not throw. Callers decide whether
- * to fail the test (`toMatchSnapshot`) or surface the result some other
- * way (`matchSnapshot()` in a CLI golden-file script).
- */
-export function matchSnapshot(
-  value: unknown,
-  options: SnapshotOptions = {},
-): SnapshotResult {
-  const snapshotPath =
-    options.snapshotPath ??
-    (options.testFile ? deriveSnapshotPath(options.testFile) : undefined);
-
-  if (!snapshotPath) {
-    throw new TypeError(
-      "[testing/snapshot] matchSnapshot requires either snapshotPath or testFile.",
-    );
-  }
-
-  const name = options.name ?? "default";
-  const normalized = options.normalize ? options.normalize(value) : value;
-  const actual = stableStringify(normalized);
-
-  const existingFile = readSnapshotFile(snapshotPath);
-  const existing = existingFile?.snapshots[name] ?? null;
-  const shouldUpdate = options.update ?? isUpdateMode();
-
-  // First-time capture → write without comparing. Treat this as a pass so
-  // new tests don't spuriously fail on the first run. CI environments can
-  // guard against accidental captures by running with `CI=true` and
-  // enforcing `existing !== null` at a higher layer if needed.
-  if (existing === null) {
-    const next: SnapshotFile = {
-      snapshots: {
-        ...(existingFile?.snapshots ?? {}),
-        [name]: actual,
-      },
-    };
-    writeSnapshotFile(snapshotPath, next);
-    return {
-      match: true,
-      created: true,
-      updated: false,
-      actual,
-      expected: null,
-      snapshotPath,
-      name,
-      diff: "",
-    };
-  }
-
-  if (existing === actual) {
-    return {
-      match: true,
-      created: false,
-      updated: false,
-      actual,
-      expected: existing,
-      snapshotPath,
-      name,
-      diff: "",
-    };
-  }
-
-  if (shouldUpdate) {
-    const next: SnapshotFile = {
-      snapshots: {
-        ...(existingFile?.snapshots ?? {}),
-        [name]: actual,
-      },
-    };
-    writeSnapshotFile(snapshotPath, next);
-    return {
-      match: true,
-      created: false,
-      updated: true,
-      actual,
-      expected: existing,
-      snapshotPath,
-      name,
-      diff: "",
-    };
-  }
-
-  return {
-    match: false,
-    created: false,
-    updated: false,
-    actual,
-    expected: existing,
-    snapshotPath,
-    name,
-    diff: computeDiff(existing, actual),
-  };
-}
-
-/**
- * Test-suite binding. Calls `matchSnapshot()` and throws a well-formed
- * `Error` on mismatch so `bun test` / `jest` display a clear failure.
- *
- * `name` defaults to the caller-supplied string (recommended) — omit
- * it only when a single snapshot per test is sufficient.
- */
-export function toMatchSnapshot(
-  value: unknown,
-  options: SnapshotOptions | string = {},
-): SnapshotResult {
-  const opts: SnapshotOptions =
-    typeof options === "string" ? { name: options } : options;
-
-  const result = matchSnapshot(value, opts);
-
-  if (!result.match) {
-    const header =
-      `Snapshot mismatch: ${result.name}\n  snapshot: ${result.snapshotPath}\n  ` +
-      `Run with UPDATE_SNAPSHOTS=1 to accept the new value.\n`;
-    throw new Error(`${header}\n${result.diff}`);
-  }
-
-  return result;
-}
-
-/**
- * Convenience normalizer: scrub values that change every run.
- *
- * Replaces:
- *  - ISO-8601 timestamps → `"<timestamp>"`
- *  - Unix epoch millis    → `"<timestamp>"`
- *  - UUIDs (v4 + v7)      → `"<uuid>"`
- *  - Absolute file paths  → `"<abs path>"`
- *
- * Applied recursively to strings. Non-string values pass through.
- */
-export function scrubVolatile(value: unknown): unknown {
-  const ISO = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
-  const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
-  // Absolute-ish paths: POSIX (/a/b) or Windows (C:\a\b). We intentionally do
-  // not scrub short paths like `/foo` that might appear in URLs.
-  const WIN_ABS = /[A-Z]:\\[^\s"']+/g;
-  const POSIX_ABS = /\/[A-Za-z0-9_.\-]+(?:\/[A-Za-z0-9_.\-]+){2,}/g;
-
-  const walk = (v: unknown): unknown => {
-    if (typeof v === "string") {
-      return v
-        .replace(ISO, "<timestamp>")
-        .replace(UUID, "<uuid>")
-        .replace(WIN_ABS, "<abs path>")
-        .replace(POSIX_ABS, "<abs path>");
-    }
-    if (typeof v === "number") {
-      // Epoch millis in the last ~50 years → placeholder.
-      if (Number.isInteger(v) && v > 1_000_000_000_000 && v < 10_000_000_000_000) {
-        return "<timestamp>";
-      }
-      return v;
-    }
-    if (Array.isArray(v)) return v.map(walk);
-    if (v && typeof v === "object") {
-      const out: Record<string, unknown> = {};
-      for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
-        out[k] = walk(val);
-      }
-      return out;
-    }
-    return v;
-  };
-
-  return walk(value);
-}
+/**
+ * @mandujs/core/testing/snapshot
+ *
+ * `toMatchSnapshot()` assertion helper for Mandu tests — mirrors the Jest
+ * API but without the Jest runtime. Snapshots live next to the source
+ * file as `__snapshots__/<basename>.snap` and are plain JSON for easy
+ * review under `git diff`.
+ *
+ * ## Why a custom implementation?
+ *
+ * `bun test` ships its own `toMatchSnapshot`, but it (a) stores files as
+ * a non-JSON textual format with newline escaping, (b) has no hook for
+ * output normalization, and (c) cannot be invoked imperatively outside
+ * of `expect()`. Mandu tests frequently capture generated code, routes
+ * manifests, and CLI output — all of which need deterministic scrubbing
+ * of timestamps, absolute paths, and random IDs before comparison.
+ *
+ * This module provides:
+ *
+ * - `matchSnapshot(value, options)` — pure function returning a
+ *   `SnapshotResult`. No dependency on a test runner — callable from
+ *   CLI scripts, golden-file tools, or ATE's oracle.
+ * - `toMatchSnapshot(value, name)` — test-binding that throws on
+ *   mismatch. Designed to be called from `bun:test` `it()` blocks.
+ * - Update-in-place via `UPDATE_SNAPSHOTS=1` (or passing
+ *   `update: true` programmatically).
+ *
+ * ## Determinism contract
+ *
+ * Comparison uses `JSON.stringify` with a **stable key ordering**. This
+ * means snapshots are invariant under object-key reordering — which
+ * prevents spurious diffs when a handler adds/removes unrelated keys.
+ * Arrays preserve order (they are semantically ordered).
+ *
+ * For timestamps, UUIDs, and other non-deterministic values, pass a
+ * `normalize` function that replaces them with stable placeholders
+ * before comparison. The tests in `tests/testing/snapshot.test.ts`
+ * demonstrate the common patterns.
+ *
+ * ## Storage layout
+ *
+ * ```
+ * myfeature.test.ts
+ * __snapshots__/
+ *   myfeature.test.ts.snap   ← JSON map { "snapshot name": "stringified value" }
+ * ```
+ *
+ * The snapshot file is one JSON object — a map of snapshot names to their
+ * stringified values. This lets a single test file own many named
+ * snapshots (`toMatchSnapshot(x, "user profile")`,
+ * `toMatchSnapshot(y, "settings")`) without spamming the filesystem.
+ *
+ * @module testing/snapshot
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Options accepted by `matchSnapshot` / `toMatchSnapshot`. */
+export interface SnapshotOptions {
+  /**
+   * Snapshot file path. When omitted, the caller must supply `testFile`
+   * so we can derive `<dir>/__snapshots__/<basename>.snap` automatically.
+   */
+  snapshotPath?: string;
+  /**
+   * Path to the test file the snapshot belongs to. Used to derive
+   * `snapshotPath` when it is not passed explicitly.
+   */
+  testFile?: string;
+  /** Named key inside the snapshot file. Defaults to "default". */
+  name?: string;
+  /**
+   * Force update-in-place regardless of the `UPDATE_SNAPSHOTS` env var.
+   * Useful in golden-file generators or one-shot scripts.
+   */
+  update?: boolean;
+  /**
+   * Pre-comparison transform. Useful to scrub timestamps, random IDs,
+   * or absolute paths so the stored snapshot is stable across runs and
+   * machines.
+   */
+  normalize?: (value: unknown) => unknown;
+}
+
+/** Outcome of a snapshot comparison. */
+export interface SnapshotResult {
+  /** True when the stored snapshot matches (or we just wrote it). */
+  readonly match: boolean;
+  /** True when the file did not exist and we created it. */
+  readonly created: boolean;
+  /** True when we overwrote an existing snapshot (update mode). */
+  readonly updated: boolean;
+  /** The serialized form of the value being snapshotted. */
+  readonly actual: string;
+  /** The stored snapshot — `null` when the file did not exist. */
+  readonly expected: string | null;
+  /** Absolute path of the snapshot file. */
+  readonly snapshotPath: string;
+  /** The key inside the snapshot file. */
+  readonly name: string;
+  /**
+   * Minimal unified-style diff when `match === false`. Empty string
+   * on match or when the snapshot was just created.
+   */
+  readonly diff: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Serialization — deterministic JSON
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Stringify `value` with deterministic, sorted object keys. Arrays keep
+ * their order (order is semantically meaningful for arrays). Undefined
+ * values and functions become `null` so the output is valid JSON across
+ * all runtimes.
+ *
+ * Two-space indent matches `git diff` expectations and keeps snapshots
+ * reviewable in PRs. The trailing newline is intentional — `echo` /
+ * `cat` don't clobber the last line.
+ */
+export function stableStringify(value: unknown): string {
+  const seen = new WeakSet<object>();
+
+  const replacer = (val: unknown): unknown => {
+    if (val === null || typeof val !== "object") return val;
+    if (seen.has(val as object)) return "[Circular]";
+    seen.add(val as object);
+
+    if (Array.isArray(val)) {
+      return val.map(replacer);
+    }
+
+    // Dates / RegExps / Errors — serialize by toString() so they compare by
+    // value instead of structure (empty-object serialization would hide real
+    // differences).
+    if (val instanceof Date) return `[Date ${val.toISOString()}]`;
+    if (val instanceof RegExp) return `[RegExp ${val.toString()}]`;
+    if (val instanceof Error) return `[Error ${val.name}: ${val.message}]`;
+    if (val instanceof Map) {
+      const entries: Array<[string, unknown]> = [];
+      for (const [k, v] of val.entries()) {
+        entries.push([String(k), replacer(v)]);
+      }
+      entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+      return { __type: "Map", entries };
+    }
+    if (val instanceof Set) {
+      const items = Array.from(val.values()).map(replacer);
+      return { __type: "Set", items };
+    }
+
+    const rec = val as Record<string, unknown>;
+    const keys = Object.keys(rec).sort();
+    const out: Record<string, unknown> = {};
+    for (const k of keys) {
+      const v = rec[k];
+      // Drop undefined/function keys — JSON cannot represent them and we
+      // want the snapshot to elide them rather than fail serialization.
+      if (typeof v === "function" || typeof v === "undefined") continue;
+      out[k] = replacer(v);
+    }
+    return out;
+  };
+
+  const normalized = replacer(value);
+  const serialized = JSON.stringify(normalized, null, 2);
+  return `${serialized ?? "null"}\n`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Storage IO
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build the default snapshot path from a test file: co-locate in a
+ * `__snapshots__/` directory next to the test.
+ */
+export function deriveSnapshotPath(testFile: string): string {
+  const dir = path.dirname(testFile);
+  const base = path.basename(testFile);
+  return path.join(dir, "__snapshots__", `${base}.snap`);
+}
+
+interface SnapshotFile {
+  readonly snapshots: Record<string, string>;
+}
+
+function readSnapshotFile(snapshotPath: string): SnapshotFile | null {
+  if (!fs.existsSync(snapshotPath)) return null;
+  const raw = fs.readFileSync(snapshotPath, "utf8");
+  if (!raw.trim()) return { snapshots: {} };
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      typeof (parsed as Record<string, unknown>).snapshots !== "object" ||
+      (parsed as Record<string, unknown>).snapshots === null
+    ) {
+      // Legacy / corrupt file — treat as empty so we don't explode in CI.
+      return { snapshots: {} };
+    }
+    const raw_snapshots = (parsed as { snapshots: Record<string, unknown> }).snapshots;
+    const snapshots: Record<string, string> = {};
+    for (const [k, v] of Object.entries(raw_snapshots)) {
+      if (typeof v === "string") snapshots[k] = v;
+    }
+    return { snapshots };
+  } catch {
+    return { snapshots: {} };
+  }
+}
+
+function writeSnapshotFile(snapshotPath: string, file: SnapshotFile): void {
+  const dir = path.dirname(snapshotPath);
+  fs.mkdirSync(dir, { recursive: true });
+  // Sort keys deterministically so new additions don't reshuffle the file.
+  const sorted: Record<string, string> = {};
+  for (const key of Object.keys(file.snapshots).sort()) {
+    sorted[key] = file.snapshots[key];
+  }
+  const body = `${JSON.stringify({ snapshots: sorted }, null, 2)}\n`;
+  fs.writeFileSync(snapshotPath, body, "utf8");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Diff — tiny line-based delta for failure messages
+// ═══════════════════════════════════════════════════════════════════════════
+
+function computeDiff(expected: string, actual: string): string {
+  const expectedLines = expected.split("\n");
+  const actualLines = actual.split("\n");
+  const max = Math.max(expectedLines.length, actualLines.length);
+  const out: string[] = [];
+  out.push("--- expected (stored snapshot)");
+  out.push("+++ actual   (current value)");
+  for (let i = 0; i < max; i++) {
+    const e = expectedLines[i];
+    const a = actualLines[i];
+    if (e === a) {
+      if (e !== undefined) out.push(`  ${e}`);
+    } else {
+      if (e !== undefined) out.push(`- ${e}`);
+      if (a !== undefined) out.push(`+ ${a}`);
+    }
+  }
+  return out.join("\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Public API
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Whether update-in-place mode is active for this process.
+ *
+ * Controlled by the `UPDATE_SNAPSHOTS=1` environment variable. Any
+ * truthy value (`"1"`, `"true"`) activates. Exported for callers that
+ * want to emit different log output in update mode.
+ */
+export function isUpdateMode(): boolean {
+  const raw = process.env.UPDATE_SNAPSHOTS;
+  if (!raw) return false;
+  const normalized = raw.toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+/**
+ * Compare `value` against the stored snapshot at the resolved path.
+ *
+ * This is a pure function — it does not throw. Callers decide whether
+ * to fail the test (`toMatchSnapshot`) or surface the result some other
+ * way (`matchSnapshot()` in a CLI golden-file script).
+ */
+export function matchSnapshot(
+  value: unknown,
+  options: SnapshotOptions = {},
+): SnapshotResult {
+  const snapshotPath =
+    options.snapshotPath ??
+    (options.testFile ? deriveSnapshotPath(options.testFile) : undefined);
+
+  if (!snapshotPath) {
+    throw new TypeError(
+      "[testing/snapshot] matchSnapshot requires either snapshotPath or testFile.",
+    );
+  }
+
+  const name = options.name ?? "default";
+  const normalized = options.normalize ? options.normalize(value) : value;
+  const actual = stableStringify(normalized);
+
+  const existingFile = readSnapshotFile(snapshotPath);
+  const existing = existingFile?.snapshots[name] ?? null;
+  const shouldUpdate = options.update ?? isUpdateMode();
+
+  // First-time capture → write without comparing. Treat this as a pass so
+  // new tests don't spuriously fail on the first run. CI environments can
+  // guard against accidental captures by running with `CI=true` and
+  // enforcing `existing !== null` at a higher layer if needed.
+  if (existing === null) {
+    const next: SnapshotFile = {
+      snapshots: {
+        ...(existingFile?.snapshots ?? {}),
+        [name]: actual,
+      },
+    };
+    writeSnapshotFile(snapshotPath, next);
+    return {
+      match: true,
+      created: true,
+      updated: false,
+      actual,
+      expected: null,
+      snapshotPath,
+      name,
+      diff: "",
+    };
+  }
+
+  if (existing === actual) {
+    return {
+      match: true,
+      created: false,
+      updated: false,
+      actual,
+      expected: existing,
+      snapshotPath,
+      name,
+      diff: "",
+    };
+  }
+
+  if (shouldUpdate) {
+    const next: SnapshotFile = {
+      snapshots: {
+        ...(existingFile?.snapshots ?? {}),
+        [name]: actual,
+      },
+    };
+    writeSnapshotFile(snapshotPath, next);
+    return {
+      match: true,
+      created: false,
+      updated: true,
+      actual,
+      expected: existing,
+      snapshotPath,
+      name,
+      diff: "",
+    };
+  }
+
+  return {
+    match: false,
+    created: false,
+    updated: false,
+    actual,
+    expected: existing,
+    snapshotPath,
+    name,
+    diff: computeDiff(existing, actual),
+  };
+}
+
+/**
+ * Test-suite binding. Calls `matchSnapshot()` and throws a well-formed
+ * `Error` on mismatch so `bun test` / `jest` display a clear failure.
+ *
+ * `name` defaults to the caller-supplied string (recommended) — omit
+ * it only when a single snapshot per test is sufficient.
+ */
+export function toMatchSnapshot(
+  value: unknown,
+  options: SnapshotOptions | string = {},
+): SnapshotResult {
+  const opts: SnapshotOptions =
+    typeof options === "string" ? { name: options } : options;
+
+  const result = matchSnapshot(value, opts);
+
+  if (!result.match) {
+    const header =
+      `Snapshot mismatch: ${result.name}\n  snapshot: ${result.snapshotPath}\n  ` +
+      `Run with UPDATE_SNAPSHOTS=1 to accept the new value.\n`;
+    throw new Error(`${header}\n${result.diff}`);
+  }
+
+  return result;
+}
+
+/**
+ * Convenience normalizer: scrub values that change every run.
+ *
+ * Replaces:
+ *  - ISO-8601 timestamps → `"<timestamp>"`
+ *  - Unix epoch millis    → `"<timestamp>"`
+ *  - UUIDs (v4 + v7)      → `"<uuid>"`
+ *  - Absolute file paths  → `"<abs path>"`
+ *
+ * Applied recursively to strings. Non-string values pass through.
+ */
+export function scrubVolatile(value: unknown): unknown {
+  const ISO = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
+  const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+  // Absolute-ish paths: POSIX (/a/b) or Windows (C:\a\b). We intentionally do
+  // not scrub short paths like `/foo` that might appear in URLs.
+  const WIN_ABS = /[A-Z]:\\[^\s"']+/g;
+  const POSIX_ABS = /\/[A-Za-z0-9_.\-]+(?:\/[A-Za-z0-9_.\-]+){2,}/g;
+
+  const walk = (v: unknown): unknown => {
+    if (typeof v === "string") {
+      return v
+        .replace(ISO, "<timestamp>")
+        .replace(UUID, "<uuid>")
+        .replace(WIN_ABS, "<abs path>")
+        .replace(POSIX_ABS, "<abs path>");
+    }
+    if (typeof v === "number") {
+      // Epoch millis in the last ~50 years → placeholder.
+      if (Number.isInteger(v) && v > 1_000_000_000_000 && v < 10_000_000_000_000) {
+        return "<timestamp>";
+      }
+      return v;
+    }
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+        out[k] = walk(val);
+      }
+      return out;
+    }
+    return v;
+  };
+
+  return walk(value);
+}