autotel-pact 0.2.0

package/src/audit.test.ts

@@ -0,0 +1,189 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { computeAuditMatrix, runAuditSync } from './audit.js';
+import type { InteractionLedgerEntry, PactFile } from './types.js';
+import { AUDIT_MATRIX_SPEC, LEDGER_ENTRY_SPEC } from './types.js';
+
+const NOW = new Date('2026-06-01T00:00:00.000Z');
+const DAY = 24 * 60 * 60 * 1000;
+
+function entry(overrides: Partial<InteractionLedgerEntry>): InteractionLedgerEntry {
+  return {
+    type: 'interaction',
+    spec: LEDGER_ENTRY_SPEC,
+    consumer: 'A',
+    provider: 'B',
+    interaction: 'evt',
+    states: [],
+    kind: 'message',
+    source: 'test',
+    role: 'consumer',
+    outcome: 'passed',
+    duration_ms: 1,
+    observed_at: NOW.toISOString(),
+    ...overrides,
+  };
+}
+
+describe('computeAuditMatrix', () => {
+  it('marks contracted-and-seen-in-test as OK', () => {
+    const m = computeAuditMatrix({
+      contracted: [{ consumer: 'A', provider: 'B', interaction: 'evt', kind: 'message' }],
+      ledger: [entry({})],
+      now: NOW,
+    });
+    expect(m.counts).toMatchObject({ contracted_and_test_seen: 1, contracted_not_test_seen: 0 });
+    expect(m.rows[0]).toMatchObject({ contracted: true, test_seen: true, observed: true });
+  });
+
+  it('flags contracted-but-not-seen-in-test (STALE)', () => {
+    const m = computeAuditMatrix({
+      contracted: [{ consumer: 'A', provider: 'B', interaction: 'evt', kind: 'message' }],
+      ledger: [],
+      now: NOW,
+    });
+    expect(m.counts.contracted_not_test_seen).toBe(1);
+    expect(m.rows[0]).toMatchObject({ contracted: true, test_seen: false });
+  });
+
+  it('flags seen-but-not-contracted', () => {
+    const m = computeAuditMatrix({
+      contracted: [],
+      ledger: [entry({})],
+      now: NOW,
+    });
+    expect(m.counts.test_or_prod_seen_not_contracted).toBe(1);
+    expect(m.rows[0]).toMatchObject({ contracted: false, test_seen: true });
+  });
+
+  it('tracks prod_seen separately from test_seen', () => {
+    const m = computeAuditMatrix({
+      contracted: [{ consumer: 'A', provider: 'B', interaction: 'evt', kind: 'message' }],
+      ledger: [entry({ source: 'production' })],
+      now: NOW,
+    });
+    expect(m.rows[0]).toMatchObject({
+      test_seen: false,
+      prod_seen: true,
+    });
+    expect(m.counts.contracted_not_test_seen).toBe(1);
+  });
+
+  it('sets provider_verified only for provider role passed entries', () => {
+    const m = computeAuditMatrix({
+      contracted: [{ consumer: 'A', provider: 'B', interaction: 'evt', kind: 'message' }],
+      ledger: [
+        entry({ role: 'provider', outcome: 'passed' }),
+      ],
+      now: NOW,
+    });
+    expect(m.rows[0]!.provider_verified).toBe(true);
+    expect(m.rows[0]!.test_seen).toBe(false);
+  });
+
+  it('ignores provider_verification_run for per-interaction columns', () => {
+    const m = computeAuditMatrix({
+      contracted: [{ consumer: 'A', provider: 'B', interaction: 'evt', kind: 'message' }],
+      ledger: [
+        {
+          type: 'provider_verification_run',
+          spec: LEDGER_ENTRY_SPEC,
+          consumer: 'A',
+          provider: 'B',
+          outcome: 'failed',
+          source: 'test',
+          role: 'provider',
+          observed_at: NOW.toISOString(),
+          error: 'setup failed',
+        },
+      ],
+      now: NOW,
+    });
+    expect(m.rows[0]!.provider_verified).toBe(false);
+    expect(m.verification_failures).toHaveLength(1);
+  });
+
+  it('applies broker_verified at pact-pair level', () => {
+    const m = computeAuditMatrix({
+      contracted: [
+        { consumer: 'A', provider: 'B', interaction: 'evt1', kind: 'message' },
+        { consumer: 'A', provider: 'B', interaction: 'evt2', kind: 'message' },
+      ],
+      ledger: [],
+      brokerVerifications: [
+        { consumer: 'A', provider: 'B', success: true, verifiedAt: NOW.toISOString() },
+      ],
+      now: NOW,
+    });
+    expect(m.rows.every((r) => r.broker_verified)).toBe(true);
+    expect(m.counts.broker_verified).toBe(2);
+  });
+
+  it('excludes ledger entries outside the window', () => {
+    const oldEntry = entry({
+      observed_at: new Date(NOW.getTime() - 20 * DAY).toISOString(),
+    });
+    const m = computeAuditMatrix({
+      contracted: [{ consumer: 'A', provider: 'B', interaction: 'evt', kind: 'message' }],
+      ledger: [oldEntry],
+      windowDays: 14,
+      now: NOW,
+    });
+    expect(m.counts.contracted_not_test_seen).toBe(1);
+  });
+
+  it('emits v0.2 audit matrix spec', () => {
+    const m = computeAuditMatrix({
+      contracted: [],
+      ledger: [],
+      now: NOW,
+    });
+    expect(m.spec).toBe(AUDIT_MATRIX_SPEC);
+  });
+});
+
+describe('runAuditSync (integration)', () => {
+  let workDir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    workDir = mkdtempSync(path.join(tmpdir(), 'autotel-pact-audit-'));
+    process.chdir(workDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(workDir, { recursive: true, force: true });
+  });
+
+  it('reads pacts and ledger from disk and produces a matrix', () => {
+    mkdirSync('pacts', { recursive: true });
+    const pact: PactFile = {
+      consumer: { name: 'OrderShipper' },
+      provider: { name: 'OrderService' },
+      messages: [
+        { description: 'an OrderCreated event' },
+        { description: 'an OrderCancelled event' },
+      ],
+    };
+    writeFileSync('pacts/OrderShipper-OrderService.json', JSON.stringify(pact));
+
+    mkdirSync('.autotel-pact', { recursive: true });
+    const observed = entry({
+      consumer: 'OrderShipper',
+      provider: 'OrderService',
+      interaction: 'an OrderCreated event',
+      observed_at: new Date().toISOString(),
+    });
+    writeFileSync('.autotel-pact/ledger-x.jsonl', JSON.stringify(observed) + '\n');
+
+    const m = runAuditSync({});
+
+    expect(m.counts.contracted).toBe(2);
+    expect(m.counts.contracted_and_test_seen).toBe(1);
+    expect(m.counts.contracted_not_test_seen).toBe(1);
+  });
+});

package/src/audit.ts

@@ -0,0 +1,251 @@
+import path from 'node:path';
+import { fetchBrokerVerifications, type BrokerConfig } from './broker.js';
+import { readLedger, type LedgerOptions } from './ledger.js';
+import {
+  interactionsFromPactFile,
+  listPactFiles,
+  parsePactFile,
+} from './pact-file.js';
+import {
+  AUDIT_MATRIX_SPEC,
+  isInteractionLedgerEntry,
+  isProviderVerificationRun,
+  type AuditMatrix,
+  type AuditRow,
+  type BrokerVerification,
+  type InteractionLedgerEntry,
+  type LedgerRecord,
+  type PactInteractionKey,
+  type ProviderVerificationRunEntry,
+} from './types.js';
+
+export interface AuditOptions extends LedgerOptions {
+  pactsDir?: string;
+  windowDays?: number;
+  broker?: BrokerConfig;
+}
+
+const DEFAULT_PACTS_DIR = './pacts';
+const DEFAULT_WINDOW_DAYS = 14;
+
+export function keyOf(k: PactInteractionKey): string {
+  const identity = k.interactionId ?? k.interaction;
+  return `${k.consumer}::${k.provider}::${k.kind}::${identity}`;
+}
+
+function pairKey(consumer: string, provider: string): string {
+  return `${consumer}::${provider}`;
+}
+
+function inWindow(observedAt: string, cutoff: number): boolean {
+  const t = Date.parse(observedAt);
+  return Number.isFinite(t) && t >= cutoff;
+}
+
+/**
+ * Compute the audit matrix from pact files, ledger, and optional broker data.
+ */
+export function computeAuditMatrix(input: {
+  contracted: PactInteractionKey[];
+  ledger: LedgerRecord[];
+  brokerVerifications?: BrokerVerification[];
+  windowDays?: number;
+  now?: Date;
+}): AuditMatrix {
+  const windowDays = input.windowDays ?? DEFAULT_WINDOW_DAYS;
+  const now = input.now ?? new Date();
+  const cutoff = now.getTime() - windowDays * 24 * 60 * 60 * 1000;
+
+  const verificationFailures: ProviderVerificationRunEntry[] = [];
+  const recentInteractions: InteractionLedgerEntry[] = [];
+
+  for (const entry of input.ledger) {
+    if (!inWindow(entry.observed_at, cutoff)) continue;
+    if (isProviderVerificationRun(entry)) {
+      verificationFailures.push(entry);
+      continue;
+    }
+    if (isInteractionLedgerEntry(entry)) {
+      recentInteractions.push(entry);
+    }
+  }
+
+  const brokerByPair = new Map<string, BrokerVerification>();
+  for (const b of input.brokerVerifications ?? []) {
+    brokerByPair.set(pairKey(b.consumer, b.provider), b);
+  }
+
+  const testSeenByKey = new Map<string, InteractionLedgerEntry[]>();
+  const prodSeenByKey = new Map<string, InteractionLedgerEntry[]>();
+  const providerVerifiedByKey = new Map<string, InteractionLedgerEntry[]>();
+  const anyObservedByKey = new Map<string, InteractionLedgerEntry[]>();
+
+  for (const entry of recentInteractions) {
+    const k = keyOf({
+      consumer: entry.consumer,
+      provider: entry.provider,
+      interaction: entry.interaction,
+      kind: entry.kind,
+      interactionId: entry.interaction_id,
+    });
+
+    const push = (map: Map<string, InteractionLedgerEntry[]>) => {
+      const arr = map.get(k) ?? [];
+      arr.push(entry);
+      map.set(k, arr);
+    };
+
+    push(anyObservedByKey);
+
+    if (entry.source === 'test' && entry.role === 'consumer') {
+      push(testSeenByKey);
+    }
+    if (entry.source === 'production') {
+      push(prodSeenByKey);
+    }
+    if (entry.role === 'provider' && entry.outcome === 'passed') {
+      push(providerVerifiedByKey);
+    }
+  }
+
+  const contractedByKey = new Map<string, PactInteractionKey>();
+  for (const c of input.contracted) {
+    contractedByKey.set(keyOf(c), c);
+  }
+
+  const rows: AuditRow[] = [];
+
+  function pushRow(parts: PactInteractionKey, k: string, isContracted: boolean): void {
+    const testObs = testSeenByKey.get(k) ?? [];
+    const prodObs = prodSeenByKey.get(k) ?? [];
+    const providerObs = providerVerifiedByKey.get(k) ?? [];
+    const allObs = anyObservedByKey.get(k) ?? [];
+    const latest = allObs.toSorted((a, b) =>
+      b.observed_at.localeCompare(a.observed_at),
+    )[0];
+    const broker = brokerByPair.get(pairKey(parts.consumer, parts.provider));
+
+    rows.push({
+      consumer: parts.consumer,
+      provider: parts.provider,
+      interaction: parts.interaction,
+      interaction_id: parts.interactionId ?? latest?.interaction_id,
+      kind: parts.kind,
+      contracted: isContracted,
+      observed: testObs.length > 0 || prodObs.length > 0,
+      test_seen: testObs.length > 0,
+      prod_seen: prodObs.length > 0,
+      provider_verified: providerObs.length > 0,
+      broker_verified: broker?.success === true,
+      broker_verified_at: broker?.verifiedAt,
+      broker_error: broker?.error,
+      last_observed_at: latest?.observed_at,
+      last_outcome: latest?.outcome,
+    });
+  }
+
+  for (const [k, contracted] of contractedByKey) {
+    pushRow(contracted, k, true);
+  }
+  for (const [k, observations] of anyObservedByKey) {
+    if (contractedByKey.has(k)) continue;
+    const first = observations[0]!;
+    pushRow(
+      {
+        consumer: first.consumer,
+        provider: first.provider,
+        interaction: first.interaction,
+        kind: first.kind,
+        interactionId: first.interaction_id,
+      },
+      k,
+      false,
+    );
+  }
+
+  rows.sort((a, b) =>
+    a.consumer.localeCompare(b.consumer) ||
+    a.provider.localeCompare(b.provider) ||
+    a.interaction.localeCompare(b.interaction),
+  );
+
+  const counts = {
+    total: rows.length,
+    contracted: rows.filter((r) => r.contracted).length,
+    observed: rows.filter((r) => r.observed).length,
+    contracted_and_test_seen: rows.filter((r) => r.contracted && r.test_seen).length,
+    contracted_not_test_seen: rows.filter((r) => r.contracted && !r.test_seen).length,
+    test_or_prod_seen_not_contracted: rows.filter(
+      (r) => !r.contracted && (r.test_seen || r.prod_seen),
+    ).length,
+    test_seen: rows.filter((r) => r.test_seen).length,
+    prod_seen: rows.filter((r) => r.prod_seen).length,
+    provider_verified: rows.filter((r) => r.provider_verified).length,
+    broker_verified: rows.filter((r) => r.broker_verified).length,
+  };
+
+  const matrix: AuditMatrix = {
+    spec: AUDIT_MATRIX_SPEC,
+    rows,
+    counts,
+    window_days: windowDays,
+    generated_at: now.toISOString(),
+  };
+
+  if (verificationFailures.length > 0) {
+    matrix.verification_failures = verificationFailures;
+  }
+
+  return matrix;
+}
+
+export async function runAudit(opts: AuditOptions = {}): Promise<AuditMatrix> {
+  const pactsDir = path.resolve(process.cwd(), opts.pactsDir ?? DEFAULT_PACTS_DIR);
+  const contracted: PactInteractionKey[] = [];
+  const pairs = new Set<string>();
+
+  for (const file of listPactFiles(pactsDir)) {
+    const pact = parsePactFile(file);
+    if (!pact) continue;
+    const interactions = interactionsFromPactFile(pact);
+    contracted.push(...interactions);
+    const consumer = pact.consumer?.name;
+    const provider = pact.provider?.name;
+    if (consumer && provider) {
+      pairs.add(pairKey(consumer, provider));
+    }
+  }
+
+  const ledger = readLedger(opts);
+
+  let brokerVerifications: BrokerVerification[] | undefined;
+  if (opts.broker) {
+    brokerVerifications = await fetchBrokerVerifications(opts.broker, [...pairs].map((p) => {
+      const [consumer, provider] = p.split('::');
+      return { consumer: consumer!, provider: provider! };
+    }));
+  }
+
+  return computeAuditMatrix({
+    contracted,
+    ledger,
+    brokerVerifications,
+    windowDays: opts.windowDays,
+  });
+}
+
+/** Sync audit without broker (backward compatible for tests). */
+export function runAuditSync(opts: Omit<AuditOptions, 'broker'> = {}): AuditMatrix {
+  const pactsDir = path.resolve(process.cwd(), opts.pactsDir ?? DEFAULT_PACTS_DIR);
+  const contracted: PactInteractionKey[] = [];
+  for (const file of listPactFiles(pactsDir)) {
+    const pact = parsePactFile(file);
+    if (pact) contracted.push(...interactionsFromPactFile(pact));
+  }
+  const ledger = readLedger(opts);
+  return computeAuditMatrix({
+    contracted,
+    ledger,
+    windowDays: opts.windowDays,
+  });
+}

package/src/auto-wrap.test.ts

@@ -0,0 +1,149 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { installAutoWrap } from './auto-wrap.js';
+import { readLedger } from './ledger.js';
+
+// We can't reuse the patched-once prototypes between tests cleanly —
+// monkey-patching is by design a one-shot operation. So each test defines
+// its own fresh fake classes, then installs the auto-wrap against them.
+
+function makeFakeMessagePact() {
+  return class FakeMessageConsumerPact {
+    config = { consumer: 'A', provider: 'B' };
+    async verify(handler: (m: unknown) => Promise<unknown>): Promise<unknown> {
+      return handler({
+        contents: { x: 1 },
+        description: 'an evt',
+        providerStates: [{ name: 'state-x' }],
+      });
+    }
+  };
+}
+
+function makeFakePactV3() {
+  return class FakePactV3 {
+    opts = { consumer: 'Web', provider: 'Catalog' };
+    added: Array<{ uponReceiving: string; states?: Array<{ description: string }> }> = [];
+    addInteraction(interaction: {
+      uponReceiving: string;
+      states?: Array<{ description: string }>;
+    }) {
+      this.added.push(interaction);
+      return this;
+    }
+    async executeTest<T>(
+      fn: (s: { url: string; port: number }) => Promise<T>,
+    ): Promise<T | undefined> {
+      return fn({ url: 'http://localhost', port: 0 });
+    }
+  };
+}
+
+let workDir: string;
+let originalCwd: string;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  workDir = mkdtempSync(path.join(tmpdir(), 'autotel-pact-auto-'));
+  process.chdir(workDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  rmSync(workDir, { recursive: true, force: true });
+  delete process.env.AUTOTEL_PACT_RUN_ID;
+});
+
+describe('auto-wrap', () => {
+  it('patches MessageConsumerPact.prototype.verify to emit a ledger entry', async () => {
+    process.env.AUTOTEL_PACT_RUN_ID = 'r-auto-msg';
+    const Pact = makeFakeMessagePact();
+    installAutoWrap({
+      MessageConsumerPact: Pact as unknown as { prototype: Record<string | symbol, unknown> },
+    });
+
+    const pact = new Pact();
+    await pact.verify(async () => 'handled');
+
+    const entries = readLedger({ runId: 'r-auto-msg' });
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      consumer: 'A',
+      provider: 'B',
+      interaction: 'an evt',
+      states: ['state-x'],
+      kind: 'message',
+      outcome: 'passed',
+    });
+  });
+
+  it('patches PactV3 so addInteraction + executeTest emits ledger entries', async () => {
+    process.env.AUTOTEL_PACT_RUN_ID = 'r-auto-http';
+    const Pact = makeFakePactV3();
+    installAutoWrap({
+      PactV3: Pact as unknown as { prototype: Record<string | symbol, unknown> },
+    });
+
+    const pact = new Pact();
+    pact.addInteraction({
+      uponReceiving: 'get widgets',
+      states: [{ description: 'widgets exist' }],
+    });
+    await pact.executeTest(async () => {});
+
+    const entries = readLedger({ runId: 'r-auto-http' });
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      consumer: 'Web',
+      provider: 'Catalog',
+      interaction: 'get widgets',
+      states: ['widgets exist'],
+      kind: 'http',
+      outcome: 'passed',
+    });
+  });
+
+  it('records failed outcome when the test body throws', async () => {
+    process.env.AUTOTEL_PACT_RUN_ID = 'r-auto-fail';
+    const Pact = makeFakePactV3();
+    installAutoWrap({
+      PactV3: Pact as unknown as { prototype: Record<string | symbol, unknown> },
+    });
+
+    const pact = new Pact();
+    pact.addInteraction({ uponReceiving: 'broken' });
+
+    await expect(
+      pact.executeTest(async () => {
+        throw new Error('assertion failed');
+      }),
+    ).rejects.toThrow('assertion failed');
+
+    const entries = readLedger({ runId: 'r-auto-fail' });
+    expect(entries[0]).toMatchObject({ outcome: 'failed', error: 'assertion failed' });
+  });
+
+  it('is idempotent — installing twice on the same prototype does not double-wrap', async () => {
+    process.env.AUTOTEL_PACT_RUN_ID = 'r-auto-idem';
+    const Pact = makeFakeMessagePact();
+    installAutoWrap({
+      MessageConsumerPact: Pact as unknown as { prototype: Record<string | symbol, unknown> },
+    });
+    installAutoWrap({
+      MessageConsumerPact: Pact as unknown as { prototype: Record<string | symbol, unknown> },
+    });
+
+    const pact = new Pact();
+    await pact.verify(async () => {});
+
+    const entries = readLedger({ runId: 'r-auto-idem' });
+    expect(entries).toHaveLength(1); // not 2
+  });
+
+  it('skips patching when no recognised ctors are present in the module', () => {
+    // Empty module is a successful no-op — nothing crashes, nothing patched.
+    expect(installAutoWrap({})).toBe(true);
+  });
+});