autotel-message-contract 0.1.0

package/src/contract.ts

@@ -0,0 +1,409 @@
+/**
+ * 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.
+ */
+import { lineDiff } from './diff.js';
+import { read, type Reader } from './reader.js';
+import {
+  defaultSerializer,
+  type MessageSerializer,
+} from './serializer.js';
+import {
+  isUpdateMode,
+  readSnapshot,
+  type SnapshotLocation,
+  writeSnapshot,
+} from './snapshot-storage.js';
+
+/** Thrown when a contract check fails. Message is pre-formatted for a test runner. */
+export class ContractViolationError extends Error {
+  override readonly name = 'ContractViolationError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export interface MessageContractOptions {
+  /** Serializer producing the bytes you ship. Defaults to deterministic JSON. */
+  serializer?: MessageSerializer<string>;
+  /**
+   * Where approved files live and what they are named. A bare string is used as
+   * the logical name; an object gives full control over `dir`/`path`.
+   */
+  snapshot?: string | SnapshotLocation;
+  /** Override update-mode detection (default reads env, e.g. AUTOTEL_CONTRACT_UPDATE=1). */
+  update?: boolean;
+}
+
+const SNAPSHOT_SOURCE = Symbol('autotel-message-contract.snapshot-source');
+
+export interface ApprovedSnapshotSource {
+  readonly [SNAPSHOT_SOURCE]: true;
+  readonly location?: string | SnapshotLocation;
+}
+
+/**
+ * Point a compatibility check at a previously approved snapshot instead of a
+ * live in-memory message instance.
+ */
+export function approvedSnapshot(
+  location?: string | SnapshotLocation,
+): ApprovedSnapshotSource {
+  return {
+    [SNAPSHOT_SOURCE]: true,
+    location,
+  };
+}
+
+function isApprovedSnapshotSource(value: unknown): value is ApprovedSnapshotSource {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    SNAPSHOT_SOURCE in value &&
+    (value as ApprovedSnapshotSource)[SNAPSHOT_SOURCE] === true
+  );
+}
+
+/** Start a contract check. */
+export function messageContract(options: MessageContractOptions = {}): GivenStep {
+  return new GivenStep(options);
+}
+
+class GivenStep {
+  constructor(private readonly options: MessageContractOptions) {}
+
+  /** The message under contract. */
+  given<T>(message: T | ApprovedSnapshotSource): WhenStep<T> {
+    return new WhenStep(message, this.options);
+  }
+}
+
+class WhenStep<T> {
+  constructor(
+    private readonly message: T | ApprovedSnapshotSource,
+    private readonly options: MessageContractOptions,
+  ) {}
+
+  /** Serialize the message; the next step pins or inspects the result. */
+  whenSerialized(): SnapshotStep {
+    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 ?? defaultSerializer;
+    const serialized = serializer.serialize(this.message);
+    return new SnapshotStep(serialized, 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<Output>(reader: Reader<Output>): CompatibilityStep<Output> {
+    const serializer = this.options.serializer ?? defaultSerializer;
+    return new CompatibilityStep(this.message, reader, serializer, this.options);
+  }
+}
+
+class SnapshotStep {
+  constructor(
+    private readonly serialized: string,
+    private readonly serializer: MessageSerializer<string>,
+    private readonly options: MessageContractOptions,
+  ) {}
+
+  /** The serialized bytes, for ad-hoc assertions outside the snapshot flow. */
+  get output(): string {
+    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?: string): void {
+    const location = this.resolveLocation(snapshotName);
+    const existing = readSnapshot(location);
+    const update = this.options.update ?? isUpdateMode();
+
+    if (!existing.exists || update) {
+      const path = writeSnapshot(location, this.serialized);
+      if (!existing.exists) {
+        // First run: record and pass, leaving the file to be reviewed/committed.
+        return;
+      }
+      // Update mode: rewrite and pass even if it changed.
+      void path;
+      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\n` +
+          `If this change is intentional, re-run with AUTOTEL_CONTRACT_UPDATE=1 ` +
+          `to update the approved file, then review and commit it.`,
+      );
+    }
+  }
+
+  private resolveLocation(snapshotName?: string): SnapshotLocation {
+    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').`,
+    );
+  }
+}
+
+class CompatibilityStep<Output> {
+  constructor(
+    private readonly source: unknown,
+    private readonly reader: Reader<Output>,
+    private readonly serializer: MessageSerializer<string>,
+    private readonly options: MessageContractOptions,
+  ) {}
+
+  /**
+   * 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?: (value: Output) => void | Promise<void>,
+  ): Promise<Output> {
+    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?: (value: Output) => void | Promise<void>,
+  ): Promise<Output> {
+    return this.check('forward', assert);
+  }
+
+  private async check(
+    direction: 'backward' | 'forward',
+    assert?: (value: Output) => void | Promise<void>,
+  ): Promise<Output> {
+    const serialized = this.resolveSourceSerialized();
+    const deserializedSource = this.serializer.deserialize(serialized);
+    const outcome = await read(this.reader, deserializedSource);
+
+    if (!outcome.ok) {
+      const writer = direction === 'backward' ? 'an older writer' : 'a newer writer';
+      const readerLabel =
+        direction === 'backward' ? 'the newer reader' : 'the older reader';
+      throw new ContractViolationError(
+        `Not ${direction}-compatible: ${readerLabel} rejected a message ${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 as Output);
+    return outcome.value as Output;
+  }
+
+  private resolveSourceSerialized(): string {
+    if (isApprovedSnapshotSource(this.source)) {
+      const location = this.resolveSnapshotLocation(this.source.location);
+      const existing = readSnapshot(location);
+      if (!existing.exists || existing.content === undefined) {
+        throw new ContractViolationError(
+          `Cannot read approved snapshot for compatibility check.\n` +
+            `  snapshot: ${existing.path}\n\n` +
+            `Record it first with .whenSerialized().thenContractIsUnchanged(), ` +
+            `or point approvedSnapshot(...) at an existing file.`,
+        );
+      }
+      return existing.content;
+    }
+    return this.serializer.serialize(this.source);
+  }
+
+  private resolveSnapshotLocation(
+    location?: string | SnapshotLocation,
+  ): SnapshotLocation {
+    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' }).`,
+    );
+  }
+
+  private assertStructuralCompatibility(
+    sourceValue: unknown,
+    targetValue: unknown,
+    direction: 'backward' | 'forward',
+    serialized: string,
+  ): void {
+    const mismatches: string[] = [];
+    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: string, max = 400): string {
+  return value.length > max ? `${value.slice(0, max)}… (${value.length} chars)` : value;
+}
+
+function compareSharedStructure(
+  sourceValue: unknown,
+  targetValue: unknown,
+  path: string,
+  mismatches: string[],
+): void {
+  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: unknown): value is Record<string, unknown> {
+  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: unknown, right: unknown): boolean {
+  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: unknown): string {
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (
+    value === null ||
+    typeof value === 'number' ||
+    typeof value === 'boolean' ||
+    value === undefined
+  ) {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
+function joinPath(path: string, key: string): string {
+  return path === '$' ? `$.${key}` : `${path}.${key}`;
+}
+
+export type {
+  GivenStep,
+  WhenStep,
+  SnapshotStep,
+  CompatibilityStep,
+};

package/src/diff.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+export function lineDiff(approved: string, actual: string): string {
+  const a = approved.split('\n');
+  const b = actual.split('\n');
+  const lcs = longestCommonSubsequence(a, b);
+
+  const out: string[] = [];
+  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: string[],
+  b: string[],
+): Array<[number, number]> {
+  const n = a.length;
+  const m = b.length;
+  const table: number[][] = 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: Array<[number, number]> = [];
+  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;
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * autotel-contract — brokerless message contract testing.
+ *
+ * Pin the serialized shape of the messages your code sends and stores (events,
+ * commands, queue payloads, HTTP bodies) and prove old and new versions stay
+ * compatible — as ordinary unit tests, with the contract committed as a file
+ * beside the test. No broker, no schema registry, nothing to run in Docker.
+ *
+ * @see {@link messageContract} for the snapshot + compatibility DSL.
+ */
+export {
+  messageContract,
+  ContractViolationError,
+  approvedSnapshot,
+} from './contract.js';
+export type {
+  ApprovedSnapshotSource,
+  MessageContractOptions,
+  GivenStep,
+  WhenStep,
+  SnapshotStep,
+  CompatibilityStep,
+} from './contract.js';
+
+export {
+  defaultSerializer,
+  jsonSerializer,
+} from './serializer.js';
+export type {
+  MessageSerializer,
+  JsonSerializerOptions,
+} from './serializer.js';
+
+export { read } from './reader.js';
+export type {
+  Reader,
+  ParseFn,
+  StandardSchemaLike,
+  ReadOutcome,
+} from './reader.js';
+
+export {
+  isUpdateMode,
+  resolveSnapshotPath,
+  readSnapshot,
+  writeSnapshot,
+} from './snapshot-storage.js';
+export type {
+  SnapshotLocation,
+  ReadSnapshotResult,
+} from './snapshot-storage.js';
+
+export { lineDiff } from './diff.js';

package/src/reader.ts

@@ -0,0 +1,105 @@
+/**
+ * Readers — the "as this version" side of a compatibility check.
+ *
+ * In a JVM contract library you write `whenDeserializedAs(NewType.class)` and
+ * reflection does the rest. TypeScript types are erased at runtime, so there is
+ * no class to hand over. Instead you describe the *reader*: the thing that
+ * accepts a deserialized value and either produces a typed result or rejects
+ * it. Two shapes are accepted, in order of how most TS codebases already model
+ * a message version:
+ *
+ *  1. A **Standard Schema** (Zod ≥3.24, Valibot, ArkType, …) — anything exposing
+ *     the `~standard` interface. This is the recommended form: the schema is the
+ *     version, and it already lives next to your message type.
+ *  2. A plain **parse function** `(value) => T` that throws on incompatible input.
+ *
+ * A reader that accepts the value proves compatibility; a reader that throws or
+ * reports issues proves the versions have drifted apart.
+ */
+
+/** The subset of the Standard Schema v1 interface we rely on. */
+export interface StandardSchemaLike<Output = unknown> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) =>
+      | StandardResult<Output>
+      | Promise<StandardResult<Output>>;
+  };
+}
+
+interface StandardResult<Output> {
+  value?: Output;
+  issues?: ReadonlyArray<{ readonly message: string; readonly path?: unknown }>;
+}
+
+/** A bare parse function: returns the typed value or throws. */
+export type ParseFn<Output = unknown> = (value: unknown) => Output;
+
+/** Either accepted reader form. */
+export type Reader<Output = unknown> =
+  | StandardSchemaLike<Output>
+  | ParseFn<Output>;
+
+function isStandardSchema(reader: Reader): reader is StandardSchemaLike {
+  return (
+    typeof reader === 'object' &&
+    reader !== null &&
+    '~standard' in reader &&
+    typeof (reader as StandardSchemaLike)['~standard']?.validate === 'function'
+  );
+}
+
+export interface ReadOutcome<Output = unknown> {
+  ok: boolean;
+  /** Present when `ok`. */
+  value?: Output;
+  /** Human-readable reasons the reader rejected the value. */
+  issues: string[];
+}
+
+/**
+ * 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.
+ */
+export async function read<Output>(
+  reader: Reader<Output>,
+  value: unknown,
+): Promise<ReadOutcome<Output>> {
+  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 as Output, issues: [] };
+    } catch (error) {
+      return { ok: false, issues: [errorMessage(error)] };
+    }
+  }
+
+  try {
+    const parsed = (reader as ParseFn<Output>)(value);
+    return { ok: true, value: parsed, issues: [] };
+  } catch (error) {
+    return { ok: false, issues: [errorMessage(error)] };
+  }
+}
+
+function formatIssue(message: string, path: unknown): string {
+  if (Array.isArray(path) && path.length > 0) {
+    return `${path.map(String).join('.')}: ${message}`;
+  }
+  return message;
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}

package/src/serializer.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { jsonSerializer } from './serializer.js';
+
+describe('jsonSerializer', () => {
+  it('sorts object keys deterministically by default', () => {
+    const s = jsonSerializer({ indent: 0 });
+    expect(s.serialize({ b: 1, a: 2 })).toBe(s.serialize({ a: 2, b: 1 }));
+    expect(s.serialize({ b: 1, a: 2 })).toBe('{"a":2,"b":1}');
+  });
+
+  it('sorts keys recursively', () => {
+    const s = jsonSerializer({ indent: 0 });
+    expect(s.serialize({ z: { y: 1, x: 2 } })).toBe('{"z":{"x":2,"y":1}}');
+  });
+
+  it('preserves array order', () => {
+    const s = jsonSerializer({ indent: 0 });
+    expect(s.serialize([3, 1, 2])).toBe('[3,1,2]');
+  });
+
+  it('can preserve key order when asked', () => {
+    const s = jsonSerializer({ indent: 0, sortKeys: false });
+    expect(s.serialize({ b: 1, a: 2 })).toBe('{"b":1,"a":2}');
+  });
+
+  it('round-trips through deserialize', () => {
+    const s = jsonSerializer();
+    const value = { orderId: 'ord-1', items: [{ sku: 'x', qty: 2 }] };
+    expect(s.deserialize(s.serialize(value))).toEqual(value);
+  });
+});