autotel-message-contract 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# autotel-message-contract
+
+> Pin the serialized shape of your messages and prove old and new versions stay compatible, as ordinary unit tests with the contract committed beside the test.
+
+`autotel-message-contract` is contract testing for the messages your code sends and stores: events, commands, queue payloads, HTTP request/response bodies, and anything else you serialize for someone else to read.
+
+You write a small unit test that locks down a message's serialized format. Later you rename a field or change a type. The code still compiles and your other tests pass, but this one fails and points at what changed. You fix it in the same pull request, before a consumer or a stored event has hit the old format in production.
+
+It is the test-time companion to [`autotel-pact`](../autotel-pact) (runtime evidence that contracted interactions actually fired) and [`autotel-schema`](../autotel-schema) (your telemetry surface as a contract). Where those answer *did it run?* and *is my trace surface stable?*, this answers *does my message serialization stay stable and stay compatible across versions?*
+
+## Why
+
+When you change how a message serializes, the change is easy to miss. The code compiles and the tests pass, because they write and read the message with the same code. The mismatch surfaces later, when something holding the old format reads it: a stored event, a message waiting on a queue, or another service.
+
+`autotel-message-contract` takes the small, brokerless approach:
+
+- **The checks are ordinary unit tests** in your existing suite, with no broker, schema registry, or mock service to run, and nothing to start in Docker.
+- **The contract is the serialized output committed next to the test**, so a format change appears in a normal diff and is reviewed like any other code.
+- **The check uses your application's own serializer**, so the snapshot is the exact bytes you ship.
+
+It checks the serialized shape of a message and whether its versions stay compatible. It doesn't exercise a live exchange between running services, so it complements that kind of tooling (Pact, `autotel-pact`) rather than replacing it.
+
+## Install
+
+```bash
+pnpm add -D autotel-message-contract
+# autotel is an optional peer dependency; this package works standalone
+```
+
+## Snapshot check: pin the serialized shape
+
+A snapshot check confirms a message still serializes to the bytes you approved, so nothing reading it downstream breaks. The first run writes the approved file and passes; you review and commit it. From then on the check compares against it.
+
+```ts
+import { messageContract } from 'autotel-message-contract';
+import { OrderPlaced } from './events';
+
+it('OrderPlaced serialization is unchanged', () => {
+  messageContract({ snapshot: 'OrderPlaced' })
+    .given(new OrderPlaced('ord-1', 'Alice', placedAt))
+    .whenSerialized()
+    .thenContractIsUnchanged();
+});
+```
+
+The approved file lands in a `__contracts__/` directory beside the test (`OrderPlaced.approved.txt`). When the format drifts, the failure shows you what moved:
+
+```
+Message contract drifted from its approved snapshot.
+  serializer: json
+  snapshot:   .../__contracts__/OrderPlaced.approved.txt
+
+  {
+-   "customer": "Alice",
++   "customerName": "Alice",
+    "orderId": "ord-1"
+  }
+
+If this change is intentional, re-run with AUTOTEL_CONTRACT_UPDATE=1 to update the
+approved file, then review and commit it.
+```
+
+### Use your application's serializer
+
+The default serializer is JSON with deterministic key ordering, good enough to pin most events. The snapshot is only meaningful if it matches the shape your consumers see. Pass your app's real serializer so the snapshot records the exact bytes you ship (snake_case, custom date formats, omitted nulls, `superjson`, `devalue`, protobuf):
+
+```ts
+import { messageContract } from 'autotel-message-contract';
+
+messageContract({ serializer: mySnakeCaseSerializer, snapshot: 'OrderPlaced' })
+  .given(new OrderPlaced('ord-1', 'Alice', placedAt))
+  .whenSerialized()
+  .thenContractIsUnchanged();
+```
+
+A `MessageSerializer` is `{ name, serialize, deserialize }`. `jsonSerializer({ indent: 0, sortKeys: false })` gives you the compact, order-preserving bytes you put on the wire.
+
+## Compatibility check: prove versions still read each other
+
+A compatibility check is for the version you evolve on purpose, so changing a message doesn't strand the ones already in your store or on the wire. TypeScript erases types at runtime, so instead of a class you hand over a **reader**: a [Standard Schema](https://standardschema.dev) (Zod ≥3.24, Valibot, ArkType) or a plain parse function.
+
+**Backward compatible**: confirm a newer reader still reads what an older writer produced (events you stored last year, a request already sent):
+
+```ts
+import { messageContract } from 'autotel-message-contract';
+import { OrderPlacedV2 } from './events'; // a Zod schema
+
+await messageContract()
+  .given(orderPlacedV1) // bytes an old version wrote
+  .whenDeserializedAs(OrderPlacedV2)
+  .thenBackwardCompatible((v2) => {
+    expect(v2.coupon).toBeUndefined(); // newly-added field defaults sensibly
+  });
+```
+
+**Forward compatible**: confirm a consumer that hasn't upgraded yet still reads what the newer writer produces, so you can ship the new shape before the readers have caught up:
+
+```ts
+await messageContract()
+  .given(orderPlacedV2) // bytes the new version writes
+  .whenDeserializedAs(OrderPlacedV1)
+  .thenForwardCompatible();
+```
+
+Compatibility checks are stricter than simple parse-success: after the target
+reader accepts the payload, the package re-serializes the parsed value and
+checks that shared fields still mean the same thing. Silent field renames or
+lossy transforms fail even if the reader does not throw.
+
+### Replay a saved snapshot as the source version
+
+When you want to prove that today's reader still accepts a payload you approved
+months ago, point the check at the approved file directly:
+
+```ts
+import { approvedSnapshot, messageContract } from 'autotel-message-contract';
+
+await messageContract({ snapshot: 'OrderPlaced_v1' })
+  .given(approvedSnapshot())
+  .whenDeserializedAs(OrderPlacedV2)
+  .thenBackwardCompatible();
+```
+
+You can also pass an explicit location: `approvedSnapshot({ dir, name })` or
+`approvedSnapshot({ path })`.
+
+When the versions have drifted apart, the failure names the issues:
+
+```
+Not backward-compatible: the newer reader rejected a message an older writer produced.
+  serializer: json
+  serialized: {"customerName":"Alice","orderId":"ord-1"}
+  issues:
+    - customer: Required
+```
+
+## Updating snapshots
+
+When a change is intentional, re-run with any of these set, review the diff, and commit:
+
+```bash
+AUTOTEL_CONTRACT_UPDATE=1 pnpm test
+# UPDATE_CONTRACTS / UPDATE_SNAPSHOTS also work
+```
+
+Or per-check: `messageContract({ snapshot: 'X', update: true })`.
+
+## What this package does NOT do
+
+- **Does not replace Pact / `autotel-pact`.** It checks serialized shape and version compatibility, not a live exchange between running services.
+- **Does not infer your serializer.** Pass your app's serializer to pin the bytes you ship; the default is deterministic JSON.
+- **Does not pin API/type surface.** Single-purpose by design. For module or type-surface pinning use a dedicated tool like [`@microsoft/api-extractor`](https://api-extractor.com) or [`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io).
+
+## API
+
+| Export | Purpose |
+|--------|---------|
+| `messageContract(options?)` | Start a check: `.given(msg).whenSerialized()` / `.whenDeserializedAs(reader)`. |
+| `approvedSnapshot(location?)` | Use a committed approved file as the source version in a compatibility check. |
+| `jsonSerializer(options?)` | Deterministic JSON serializer; `defaultSerializer` is `jsonSerializer()`. |
+| `read(reader, value)` | Run a reader (schema or parse fn) against a value; never throws. |
+| `lineDiff`, `resolveSnapshotPath`, `readSnapshot`, `writeSnapshot`, `isUpdateMode` | Lower-level building blocks. |
+
+## License
+
+MIT © Jag Reehal

package/dist/index.cjs

@@ -0,0 +1,453 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const require_serializer = require('./serializer.cjs');
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+
+//#region src/diff.ts
+/**
+* Minimal line diff for snapshot failures. The goal is a message that points
+* at *what moved* — a renamed field, a switched date format, a dropped value —
+* not a full diff engine. Lines only in the approved file are marked `-`, lines
+* only in the actual output are marked `+`, and a little surrounding context is
+* kept so the change is readable in a terminal.
+*/
+function lineDiff(approved, actual) {
+	const a = approved.split("\n");
+	const b = actual.split("\n");
+	const lcs = longestCommonSubsequence(a, b);
+	const out = [];
+	let i = 0;
+	let j = 0;
+	for (const [ai, bj] of lcs) {
+		while (i < ai) out.push(`- ${a[i++]}`);
+		while (j < bj) out.push(`+ ${b[j++]}`);
+		out.push(`  ${a[i++]}`);
+		j++;
+	}
+	while (i < a.length) out.push(`- ${a[i++]}`);
+	while (j < b.length) out.push(`+ ${b[j++]}`);
+	return out.join("\n");
+}
+/** Indices `[i, j]` of lines common to both, longest such subsequence. */
+function longestCommonSubsequence(a, b) {
+	const n = a.length;
+	const m = b.length;
+	const table = Array.from({ length: n + 1 }, () => Array.from({ length: m + 1 }, () => 0));
+	for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+	const pairs = [];
+	let i = 0;
+	let j = 0;
+	while (i < n && j < m) if (a[i] === b[j]) {
+		pairs.push([i, j]);
+		i++;
+		j++;
+	} else if (table[i + 1][j] >= table[i][j + 1]) i++;
+	else j++;
+	return pairs;
+}
+
+//#endregion
+//#region src/reader.ts
+function isStandardSchema(reader) {
+	return typeof reader === "object" && reader !== null && "~standard" in reader && typeof reader["~standard"]?.validate === "function";
+}
+/**
+* Run a reader against a deserialized value. Never throws — a thrown parse
+* error or reported issues become `{ ok: false, issues }` so the caller can
+* build a single, legible failure message.
+*/
+async function read(reader, value) {
+	if (isStandardSchema(reader)) try {
+		const result = await reader["~standard"].validate(value);
+		if (result.issues && result.issues.length > 0) return {
+			ok: false,
+			issues: result.issues.map((issue) => formatIssue(issue.message, issue.path))
+		};
+		return {
+			ok: true,
+			value: result.value,
+			issues: []
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			issues: [errorMessage(error)]
+		};
+	}
+	try {
+		return {
+			ok: true,
+			value: reader(value),
+			issues: []
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			issues: [errorMessage(error)]
+		};
+	}
+}
+function formatIssue(message, path) {
+	if (Array.isArray(path) && path.length > 0) return `${path.map(String).join(".")}: ${message}`;
+	return message;
+}
+function errorMessage(error) {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+
+//#endregion
+//#region src/snapshot-storage.ts
+/**
+* Snapshot storage.
+*
+* A snapshot is just a file you commit: the serialized shape of a message,
+* reviewed once and from then on compared on every run. There is no broker, no
+* registry, no service to start — a format change shows up in a normal diff,
+* reviewed like any other code. This mirrors the "approved file" convention
+* (`<name>.approved.txt`) familiar from approval testing.
+*
+* By default the file lives in a `__contracts__` directory beside the test that
+* created it, resolved from the call stack so you do not have to thread paths
+* around. Override `dir` / `path` when you keep snapshots elsewhere.
+*/
+/** Set any of these (e.g. `AUTOTEL_CONTRACT_UPDATE=1`) to (re)write approved files. */
+const UPDATE_ENV_VARS = [
+	"AUTOTEL_CONTRACT_UPDATE",
+	"UPDATE_CONTRACTS",
+	"UPDATE_SNAPSHOTS"
+];
+function isUpdateMode(env = process.env) {
+	return UPDATE_ENV_VARS.some((name) => {
+		const value = env[name];
+		return value === "1" || value === "true";
+	});
+}
+const DEFAULT_DIR_NAME = "__contracts__";
+const APPROVED_SUFFIX = ".approved.txt";
+/** Resolve the absolute file path for a snapshot. */
+function resolveSnapshotPath(location) {
+	if (location.path) return node_path.default.isAbsolute(location.path) ? location.path : node_path.default.resolve(process.cwd(), location.path);
+	const dir = location.dir ?? defaultSnapshotDir();
+	return node_path.default.join(dir, `${sanitize(location.name)}${APPROVED_SUFFIX}`);
+}
+function sanitize(name) {
+	return name.replaceAll(/[^\w.@-]+/g, "_");
+}
+function readSnapshot(location) {
+	const filePath = resolveSnapshotPath(location);
+	if (!(0, node_fs.existsSync)(filePath)) return {
+		exists: false,
+		path: filePath
+	};
+	return {
+		exists: true,
+		content: (0, node_fs.readFileSync)(filePath, "utf8"),
+		path: filePath
+	};
+}
+function writeSnapshot(location, content) {
+	const filePath = resolveSnapshotPath(location);
+	(0, node_fs.mkdirSync)(node_path.default.dirname(filePath), { recursive: true });
+	(0, node_fs.writeFileSync)(filePath, content, "utf8");
+	return filePath;
+}
+/**
+* Best-effort `__contracts__` directory beside the calling test file, found by
+* walking the stack past this module and the contract internals. Falls back to
+* `<cwd>/__contracts__` when the caller cannot be determined (e.g. bundled).
+*/
+function defaultSnapshotDir() {
+	const callerFile = callerOutsidePackage();
+	const base = callerFile ? node_path.default.dirname(callerFile) : process.cwd();
+	return node_path.default.join(base, DEFAULT_DIR_NAME);
+}
+function callerOutsidePackage() {
+	const stack = (/* @__PURE__ */ new Error("stack probe")).stack;
+	if (!stack) return void 0;
+	const lines = stack.split("\n").slice(1);
+	for (const line of lines) {
+		const file = (line.match(/\((.*?):\d+:\d+\)/) ?? line.match(/at (.*?):\d+:\d+/))?.[1];
+		if (!file) continue;
+		if (file.includes("node:")) continue;
+		if (file.includes(`${node_path.default.join("autotel-message-contract", "src")}`)) continue;
+		if (file.includes(`${node_path.default.join("autotel-message-contract", "dist")}`)) continue;
+		if (file.includes("node_modules")) continue;
+		return file.startsWith("file://") ? fileUrlToPath(file) : file;
+	}
+}
+function fileUrlToPath(url) {
+	return decodeURIComponent(url.replace(/^file:\/\//, ""));
+}
+
+//#endregion
+//#region src/contract.ts
+/**
+* The message contract DSL.
+*
+* Every check starts from {@link messageContract} and reads as a sentence:
+*
+* ```ts
+* // Pin the serialized shape — fail when it drifts.
+* await messageContract()
+*   .given(new OrderPlaced(orderId, 'Alice', placedAt))
+*   .whenSerialized()
+*   .thenContractIsUnchanged();
+*
+* // Prove a newer reader still reads what an older writer produced.
+* await messageContract()
+*   .given(orderPlacedV1)
+*   .whenDeserializedAs(OrderPlacedV2)   // a Zod schema or parse fn
+*   .thenBackwardCompatible((v2) => expect(v2.coupon).toBeUndefined());
+* ```
+*
+* A **snapshot check** confirms a message still serializes exactly as approved,
+* so nothing reading it downstream breaks. A **compatibility check** confirms an
+* older and a newer version can still read each other's data. Both are ordinary
+* unit tests — no broker, no registry, no running service.
+*/
+/** Thrown when a contract check fails. Message is pre-formatted for a test runner. */
+var ContractViolationError = class extends Error {
+	name = "ContractViolationError";
+	constructor(message) {
+		super(message);
+	}
+};
+const SNAPSHOT_SOURCE = Symbol("autotel-message-contract.snapshot-source");
+/**
+* Point a compatibility check at a previously approved snapshot instead of a
+* live in-memory message instance.
+*/
+function approvedSnapshot(location) {
+	return {
+		[SNAPSHOT_SOURCE]: true,
+		location
+	};
+}
+function isApprovedSnapshotSource(value) {
+	return typeof value === "object" && value !== null && SNAPSHOT_SOURCE in value && value[SNAPSHOT_SOURCE] === true;
+}
+/** Start a contract check. */
+function messageContract(options = {}) {
+	return new GivenStep(options);
+}
+var GivenStep = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/** The message under contract. */
+	given(message) {
+		return new WhenStep(message, this.options);
+	}
+};
+var WhenStep = class {
+	message;
+	options;
+	constructor(message, options) {
+		this.message = message;
+		this.options = options;
+	}
+	/** Serialize the message; the next step pins or inspects the result. */
+	whenSerialized() {
+		if (isApprovedSnapshotSource(this.message)) throw new ContractViolationError("Cannot serialize an approved snapshot source. Use .whenDeserializedAs(...) to run a compatibility check, or pass a live message instance to .given(...).");
+		const serializer = this.options.serializer ?? require_serializer.defaultSerializer;
+		return new SnapshotStep(serializer.serialize(this.message), serializer, this.options);
+	}
+	/**
+	* Round-trip the message through a reader that models a *different version*
+	* (a Standard Schema such as Zod/Valibot, or a parse function). The next step
+	* asserts the versions stay compatible.
+	*/
+	whenDeserializedAs(reader) {
+		const serializer = this.options.serializer ?? require_serializer.defaultSerializer;
+		return new CompatibilityStep(this.message, reader, serializer, this.options);
+	}
+};
+var SnapshotStep = class {
+	serialized;
+	serializer;
+	options;
+	constructor(serialized, serializer, options) {
+		this.serialized = serialized;
+		this.serializer = serializer;
+		this.options = options;
+	}
+	/** The serialized bytes, for ad-hoc assertions outside the snapshot flow. */
+	get output() {
+		return this.serialized;
+	}
+	/**
+	* Compare the serialized output against the approved snapshot. On first run
+	* (or in update mode) it writes the approved file and passes; afterwards it
+	* fails with a diff when the shape drifts.
+	*/
+	thenContractIsUnchanged(snapshotName) {
+		const location = this.resolveLocation(snapshotName);
+		const existing = readSnapshot(location);
+		const update = this.options.update ?? isUpdateMode();
+		if (!existing.exists || update) {
+			writeSnapshot(location, this.serialized);
+			if (!existing.exists) return;
+			return;
+		}
+		if (existing.content !== this.serialized) throw new ContractViolationError(`Message contract drifted from its approved snapshot.\n  serializer: ${this.serializer.name}\n  snapshot:   ${existing.path}\n\n${lineDiff(existing.content ?? "", this.serialized)}\n\nIf this change is intentional, re-run with AUTOTEL_CONTRACT_UPDATE=1 to update the approved file, then review and commit it.`);
+	}
+	resolveLocation(snapshotName) {
+		if (snapshotName) return { name: snapshotName };
+		const configured = this.options.snapshot;
+		if (typeof configured === "string") return { name: configured };
+		if (configured) return configured;
+		throw new ContractViolationError("A snapshot name is required. Pass one to messageContract({ snapshot: 'OrderPlaced' }) or to thenContractIsUnchanged('OrderPlaced').");
+	}
+};
+var CompatibilityStep = class {
+	source;
+	reader;
+	serializer;
+	options;
+	constructor(source, reader, serializer, options) {
+		this.source = source;
+		this.reader = reader;
+		this.serializer = serializer;
+		this.options = options;
+	}
+	/**
+	* The reader models a **newer** version; confirm it still reads what an older
+	* writer produced (stored events, in-flight messages). Optionally assert on
+	* the upgraded value — e.g. that a newly-added field defaults sensibly.
+	*/
+	async thenBackwardCompatible(assert) {
+		return this.check("backward", assert);
+	}
+	/**
+	* The reader models an **older** version; confirm a consumer that has not
+	* upgraded yet still reads what the newer writer produces, so you can ship the
+	* new shape before every reader has caught up.
+	*/
+	async thenForwardCompatible(assert) {
+		return this.check("forward", assert);
+	}
+	async check(direction, assert) {
+		const serialized = this.resolveSourceSerialized();
+		const deserializedSource = this.serializer.deserialize(serialized);
+		const outcome = await read(this.reader, deserializedSource);
+		if (!outcome.ok) throw new ContractViolationError(`Not ${direction}-compatible: ${direction === "backward" ? "the newer reader" : "the older reader"} rejected a message ${direction === "backward" ? "an older writer" : "a newer writer"} produced.\n  serializer: ${this.serializer.name}\n  serialized: ${truncate(serialized)}\n  issues:\n${outcome.issues.map((m) => `    - ${m}`).join("\n")}`);
+		this.assertStructuralCompatibility(deserializedSource, this.serializer.deserialize(this.serializer.serialize(outcome.value)), direction, serialized);
+		if (assert) await assert(outcome.value);
+		return outcome.value;
+	}
+	resolveSourceSerialized() {
+		if (isApprovedSnapshotSource(this.source)) {
+			const existing = readSnapshot(this.resolveSnapshotLocation(this.source.location));
+			if (!existing.exists || existing.content === void 0) throw new ContractViolationError(`Cannot read approved snapshot for compatibility check.\n  snapshot: ${existing.path}\n\nRecord it first with .whenSerialized().thenContractIsUnchanged(), or point approvedSnapshot(...) at an existing file.`);
+			return existing.content;
+		}
+		return this.serializer.serialize(this.source);
+	}
+	resolveSnapshotLocation(location) {
+		if (typeof location === "string") return { name: location };
+		if (location) return location;
+		const configured = this.options.snapshot;
+		if (typeof configured === "string") return { name: configured };
+		if (configured) return configured;
+		throw new ContractViolationError("A snapshot location is required for approvedSnapshot(). Pass approvedSnapshot('OrderPlaced_v1') or configure messageContract({ snapshot: 'OrderPlaced_v1' }).");
+	}
+	assertStructuralCompatibility(sourceValue, targetValue, direction, serialized) {
+		const mismatches = [];
+		compareSharedStructure(sourceValue, targetValue, "$", mismatches);
+		if (mismatches.length === 0) return;
+		throw new ContractViolationError(`Not ${direction}-compatible: shared fields changed meaning across versions.\n  serializer: ${this.serializer.name}\n  serialized: ${truncate(serialized)}\n  mismatches:\n${mismatches.map((issue) => `    - ${issue}`).join("\n")}`);
+	}
+};
+function truncate(value, max = 400) {
+	return value.length > max ? `${value.slice(0, max)}… (${value.length} chars)` : value;
+}
+function compareSharedStructure(sourceValue, targetValue, path, mismatches) {
+	if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+		const sourceKeys = Object.keys(sourceValue);
+		const targetKeys = Object.keys(targetValue);
+		const sourceOnly = sourceKeys.filter((key) => !(key in targetValue));
+		const targetOnly = targetKeys.filter((key) => !(key in sourceValue));
+		if (sourceOnly.length > 0 && targetOnly.length > 0) {
+			mismatches.push(`${path}: structural incompatibility [source-only: ${sourceOnly.join(", ")}, target-only: ${targetOnly.join(", ")}]`);
+			return;
+		}
+		for (const key of sourceKeys.filter((candidate) => candidate in targetValue).toSorted()) compareSharedStructure(sourceValue[key], targetValue[key], joinPath(path, key), mismatches);
+		return;
+	}
+	if (Array.isArray(sourceValue) && Array.isArray(targetValue)) {
+		if (sourceValue.length !== targetValue.length) {
+			mismatches.push(`${path}: array length differs (${sourceValue.length} vs ${targetValue.length})`);
+			return;
+		}
+		for (const [index, sourceItem] of sourceValue.entries()) compareSharedStructure(sourceItem, targetValue[index], `${path}[${index}]`, mismatches);
+		return;
+	}
+	if (!deepEqual(sourceValue, targetValue)) mismatches.push(`${path}: value differs (${formatValue(sourceValue)} vs ${formatValue(targetValue)})`);
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function deepEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((value, index) => deepEqual(value, right[index]));
+	if (isPlainObject(left) && isPlainObject(right)) {
+		const leftKeys = Object.keys(left);
+		const rightKeys = Object.keys(right);
+		return leftKeys.length === rightKeys.length && leftKeys.every((key) => key in right && deepEqual(left[key], right[key]));
+	}
+	return false;
+}
+function formatValue(value) {
+	if (typeof value === "string") return JSON.stringify(value);
+	if (value === null || typeof value === "number" || typeof value === "boolean" || value === void 0) return String(value);
+	return JSON.stringify(value);
+}
+function joinPath(path, key) {
+	return path === "$" ? `$.${key}` : `${path}.${key}`;
+}
+
+//#endregion
+exports.ContractViolationError = ContractViolationError;
+exports.approvedSnapshot = approvedSnapshot;
+exports.defaultSerializer = require_serializer.defaultSerializer;
+exports.isUpdateMode = isUpdateMode;
+exports.jsonSerializer = require_serializer.jsonSerializer;
+exports.lineDiff = lineDiff;
+exports.messageContract = messageContract;
+exports.read = read;
+exports.readSnapshot = readSnapshot;
+exports.resolveSnapshotPath = resolveSnapshotPath;
+exports.writeSnapshot = writeSnapshot;
+//# sourceMappingURL=index.cjs.map