autotel-pact 0.2.0

package/src/processor.ts

@@ -0,0 +1,191 @@
+import { appendLedgerEntryAsync, flushLedgerWrites, type LedgerOptions } from './ledger.js';
+import { PACT_ATTRS } from './attrs.js';
+import { LEDGER_ENTRY_SPEC, type InteractionLedgerEntry, type PactKind } from './types.js';
+
+/** Minimal ReadableSpan shape — avoids hard dependency on sdk-trace-base. */
+export interface ReadableSpanLike {
+  attributes: Record<string, unknown>;
+  spanContext(): { traceId: string; spanId: string };
+  /** OTel SpanStatus. code 2 = ERROR (see @opentelemetry/api SpanStatusCode). */
+  status?: { code: number; message?: string };
+}
+
+export interface SpanLike {
+  spanContext(): { traceId: string; spanId: string };
+}
+
+/** Opaque parent context — matches OTel SpanProcessor without a hard dependency. */
+export type OtelContext = unknown;
+
+export interface SpanProcessorLike {
+  onStart(span: SpanLike, parentContext: OtelContext): void;
+  onEnd(span: ReadableSpanLike): void;
+  shutdown(): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+
+export interface PactLedgerProcessorOptions extends LedgerOptions {
+  /** Max queued ledger writes before dropping (default 1024). */
+  maxQueueSize?: number;
+  onDrop?: (reason: 'queue_full') => void;
+  onWriteError?: (error: unknown) => void;
+  onWarn?: (message: string) => void;
+}
+
+const DEFAULT_MAX_QUEUE = 1024;
+const WARN_INTERVAL_MS = 60_000;
+
+type QueueItem = { entry: InteractionLedgerEntry; opts: LedgerOptions };
+
+function attrString(attrs: Record<string, unknown>, key: string): string | undefined {
+  const v = attrs[key];
+  if (typeof v === 'string' && v.length > 0) return v;
+  return undefined;
+}
+
+function attrStates(attrs: Record<string, unknown>): string[] {
+  const v = attrs[PACT_ATTRS.INTERACTION_STATES];
+  if (Array.isArray(v)) {
+    return v.filter((s): s is string => typeof s === 'string');
+  }
+  return [];
+}
+
+function ledgerEntryFromSpan(span: ReadableSpanLike): InteractionLedgerEntry | null {
+  const attrs = span.attributes;
+  const consumer = attrString(attrs, PACT_ATTRS.CONSUMER);
+  const provider = attrString(attrs, PACT_ATTRS.PROVIDER);
+  const description = attrString(attrs, PACT_ATTRS.INTERACTION_DESCRIPTION);
+  const interactionId = attrString(attrs, PACT_ATTRS.INTERACTION_ID);
+  if (!consumer || !provider || (!description && !interactionId)) {
+    return null;
+  }
+
+  const kindRaw = attrString(attrs, PACT_ATTRS.KIND);
+  const kind: PactKind = kindRaw === 'http' ? 'http' : 'message';
+  const ctx = span.spanContext();
+  // SpanStatusCode.ERROR === 2. Treat anything else (UNSET, OK) as passed.
+  const errored = span.status?.code === 2;
+
+  const entry: InteractionLedgerEntry = {
+    type: 'interaction',
+    spec: LEDGER_ENTRY_SPEC,
+    consumer,
+    provider,
+    interaction: description ?? interactionId!,
+    interaction_id: interactionId,
+    states: attrStates(attrs),
+    kind,
+    outcome: errored ? 'failed' : 'passed',
+    source: 'production',
+    role: 'consumer',
+    duration_ms: 0,
+    observed_at: new Date().toISOString(),
+    trace_id: ctx.traceId,
+    span_id: ctx.spanId,
+    run_id: process.env.AUTOTEL_PACT_RUN_ID,
+    git_sha: process.env.GIT_SHA ?? process.env.GITHUB_SHA,
+  };
+  if (errored && span.status?.message) {
+    entry.error = span.status.message;
+  }
+  return entry;
+}
+
+/**
+ * Records pact-tagged spans to the JSONL ledger. Bounded queue, drop-on-full, fail-open.
+ */
+export class PactLedgerSpanProcessor implements SpanProcessorLike {
+  private readonly opts: PactLedgerProcessorOptions;
+  private readonly maxQueue: number;
+  private pending: QueueItem[] = [];
+  private flushing = false;
+  private drops = 0;
+  private lastWarnAt = 0;
+
+  constructor(opts: PactLedgerProcessorOptions = {}) {
+    this.opts = opts;
+    this.maxQueue = opts.maxQueueSize ?? DEFAULT_MAX_QUEUE;
+  }
+
+  onStart(_span: SpanLike, _parentContext: OtelContext): void {
+    // no-op
+  }
+
+  onEnd(span: ReadableSpanLike): void {
+    try {
+      const entry = ledgerEntryFromSpan(span);
+      if (!entry) return;
+
+      if (this.pending.length >= this.maxQueue) {
+        // FIFO eviction: drop the oldest queued entry to keep the newest.
+        // Recent evidence is more valuable than backlog under sustained pressure.
+        this.pending.shift();
+        this.drops++;
+        this.opts.onDrop?.('queue_full');
+        this.maybeWarn(
+          `autotel-pact: dropped oldest queued ledger entry (queue full, max ${this.maxQueue}). ` +
+            `${this.drops} total drops.`,
+        );
+      }
+
+      this.pending.push({ entry, opts: this.opts });
+      queueMicrotask(() => {
+        void this.flush();
+      });
+    } catch (error) {
+      this.opts.onWriteError?.(error);
+    }
+  }
+
+  private maybeWarn(message: string): void {
+    const now = Date.now();
+    if (now - this.lastWarnAt < WARN_INTERVAL_MS) return;
+    this.lastWarnAt = now;
+    if (this.opts.onWarn) {
+      this.opts.onWarn(message);
+    } else {
+      console.warn(message);
+    }
+  }
+
+  private async flush(): Promise<void> {
+    if (this.flushing) return;
+    this.flushing = true;
+    try {
+      while (this.pending.length > 0) {
+        const item = this.pending.shift()!;
+        try {
+          await appendLedgerEntryAsync(item.entry, item.opts);
+        } catch (error) {
+          this.opts.onWriteError?.(error);
+          this.maybeWarn(
+            `autotel-pact: ledger write failed (fail-open): ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }
+    } finally {
+      this.flushing = false;
+      if (this.pending.length > 0) {
+        queueMicrotask(() => {
+          void this.flush();
+        });
+      }
+    }
+  }
+
+  async forceFlush(): Promise<void> {
+    await this.flush();
+    await flushLedgerWrites();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.forceFlush();
+  }
+}
+
+export function createPactLedgerProcessor(
+  opts: PactLedgerProcessorOptions = {},
+): PactLedgerSpanProcessor {
+  return new PactLedgerSpanProcessor(opts);
+}

package/src/tag.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { PACT_ATTRS } from './attrs.js';
+
+const getActiveSpanMock = vi.fn();
+
+vi.mock('autotel', () => ({
+  getActiveSpan: () => getActiveSpanMock(),
+}));
+
+let tagPactInteraction: typeof import('./tag.js').tagPactInteraction;
+
+beforeEach(async () => {
+  getActiveSpanMock.mockReset();
+  ({ tagPactInteraction } = await import('./tag.js'));
+});
+
+afterEach(() => {
+  vi.resetModules();
+});
+
+describe('tagPactInteraction', () => {
+  it('throws when no active span is present', () => {
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    getActiveSpanMock.mockReturnValue(undefined);
+    expect(() =>
+      tagPactInteraction({
+        consumer: 'A',
+        provider: 'B',
+        description: 'evt',
+        states: [],
+        kind: 'message',
+      }),
+    ).toThrowError(/requires an active span/);
+  });
+
+  it('stamps pact.* attributes on the active span', () => {
+    const setAttributes = vi.fn();
+    const setAttribute = vi.fn();
+    getActiveSpanMock.mockReturnValue({ setAttributes, setAttribute });
+
+    tagPactInteraction({
+      consumer: 'OrderShipper',
+      provider: 'OrderService',
+      description: 'an OrderCreated event',
+      states: ['order exists'],
+      kind: 'message',
+    });
+
+    expect(setAttributes).toHaveBeenCalledTimes(1);
+    const attrs = setAttributes.mock.calls[0]![0] as Record<string, unknown>;
+    expect(attrs[PACT_ATTRS.CONSUMER]).toBe('OrderShipper');
+    expect(attrs[PACT_ATTRS.PROVIDER]).toBe('OrderService');
+    expect(attrs[PACT_ATTRS.KIND]).toBe('message');
+  });
+
+  it('sets interaction_id when supplied', () => {
+    const setAttributes = vi.fn();
+    const setAttribute = vi.fn();
+    getActiveSpanMock.mockReturnValue({ setAttributes, setAttribute });
+
+    tagPactInteraction({
+      consumer: 'A',
+      provider: 'B',
+      description: 'evt',
+      states: [],
+      kind: 'message',
+      interactionId: 'iid-123',
+    });
+
+    expect(setAttribute).toHaveBeenCalledWith(PACT_ATTRS.INTERACTION_ID, 'iid-123');
+  });
+});

package/src/tag.ts

@@ -0,0 +1,21 @@
+import { getActiveSpan } from 'autotel';
+import { buildPactAttributes, PACT_ATTRS } from './attrs.js';
+import type { PactInteractionMeta } from './types.js';
+
+/**
+ * Stamp `pact.*` attributes on the active span for production observation.
+ * Requires an active span (wrap handlers with `trace()` first).
+ */
+export function tagPactInteraction(meta: PactInteractionMeta): void {
+  const span = getActiveSpan();
+  if (!span) {
+    throw new Error(
+      'autotel-pact: tagPactInteraction requires an active span. Wrap the handler with trace() first.',
+    );
+  }
+  const attrs = buildPactAttributes(meta);
+  span.setAttributes(attrs);
+  if (meta.interactionId) {
+    span.setAttribute(PACT_ATTRS.INTERACTION_ID, meta.interactionId);
+  }
+}

package/src/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Kind of contract interaction observed.
+ */
+export type PactKind = 'message' | 'http';
+
+export type PactOutcome = 'passed' | 'failed';
+
+export type LedgerSource = 'test' | 'production';
+export type LedgerRole = 'consumer' | 'provider';
+
+export const LEDGER_ENTRY_SPEC = 'autotel-pact-ledger-entry/v0.2.0';
+export const AUDIT_MATRIX_SPEC = 'autotel-pact-audit-matrix/v0.2.0';
+
+/**
+ * Metadata about a single Pact interaction, derived from the reified message
+ * plus the consumer/provider config. Stamped onto the span and the ledger entry.
+ */
+export interface PactInteractionMeta {
+  consumer: string;
+  provider: string;
+  description: string;
+  states: string[];
+  kind: PactKind;
+  interactionId?: string;
+}
+
+/**
+ * Per-interaction ledger evidence (consumer exercise, provider verify, or production tag).
+ */
+export interface InteractionLedgerEntry {
+  type?: 'interaction';
+  spec: typeof LEDGER_ENTRY_SPEC;
+  consumer: string;
+  provider: string;
+  interaction: string;
+  interaction_id?: string;
+  states: string[];
+  kind: PactKind;
+  outcome: PactOutcome;
+  source: LedgerSource;
+  role: LedgerRole;
+  duration_ms: number;
+  observed_at: string;
+  trace_id?: string;
+  span_id?: string;
+  run_id?: string;
+  git_sha?: string;
+  error?: string;
+}
+
+/**
+ * Run-level provider verification failure — does not imply per-interaction outcomes.
+ */
+export interface ProviderVerificationRunEntry {
+  type: 'provider_verification_run';
+  spec: typeof LEDGER_ENTRY_SPEC;
+  consumer: string;
+  provider: string;
+  outcome: 'failed';
+  source: LedgerSource;
+  role: 'provider';
+  observed_at: string;
+  error: string;
+  run_id?: string;
+  git_sha?: string;
+  trace_id?: string;
+  span_id?: string;
+}
+
+export type LedgerRecord = InteractionLedgerEntry | ProviderVerificationRunEntry;
+
+export function isInteractionLedgerEntry(
+  entry: LedgerRecord,
+): entry is InteractionLedgerEntry {
+  return entry.type !== 'provider_verification_run';
+}
+
+export function isProviderVerificationRun(
+  entry: LedgerRecord,
+): entry is ProviderVerificationRunEntry {
+  return entry.type === 'provider_verification_run';
+}
+
+/**
+ * Shape of a Pact contract file on disk (subset we read).
+ */
+export interface PactFile {
+  consumer: { name: string };
+  provider: { name: string };
+  messages?: Array<{
+    description: string;
+    providerStates?: Array<{ name: string }>;
+    metadata?: Record<string, unknown>;
+  }>;
+  interactions?: Array<{
+    description: string;
+    providerStates?: Array<{ name: string }>;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+export interface BrokerVerification {
+  consumer: string;
+  provider: string;
+  success: boolean;
+  verifiedAt?: string;
+  /**
+   * Populated when the broker could not be reached or returned a non-2xx
+   * response. Distinguishes "broker said the pact is not verified" (no error)
+   * from "we could not determine verification status" (error set).
+   */
+  error?: string;
+}
+
+/**
+ * One row in the audit matrix.
+ */
+export interface AuditRow {
+  consumer: string;
+  provider: string;
+  interaction: string;
+  interaction_id?: string;
+  kind: PactKind;
+  contracted: boolean;
+  /** Any interaction-level ledger hit in the window (test or production). */
+  observed: boolean;
+  test_seen: boolean;
+  prod_seen: boolean;
+  provider_verified: boolean;
+  broker_verified: boolean;
+  broker_verified_at?: string;
+  /** Set when the broker check failed (network error, non-2xx, parse error). */
+  broker_error?: string;
+  last_observed_at?: string;
+  last_outcome?: PactOutcome;
+}
+
+export interface AuditMatrix {
+  spec: typeof AUDIT_MATRIX_SPEC;
+  rows: AuditRow[];
+  counts: {
+    total: number;
+    /** Any contracted row. */
+    contracted: number;
+    /** Any row with test_seen OR prod_seen. */
+    observed: number;
+    /** Contracted AND seen in a consumer test. */
+    contracted_and_test_seen: number;
+    /** Contracted but not seen in a consumer test (stale confidence). */
+    contracted_not_test_seen: number;
+    /** Seen (test or production) without a matching contract (ungoverned flow). */
+    test_or_prod_seen_not_contracted: number;
+    test_seen: number;
+    prod_seen: number;
+    provider_verified: number;
+    broker_verified: number;
+  };
+  window_days: number;
+  generated_at: string;
+  verification_failures?: ProviderVerificationRunEntry[];
+}
+
+export interface PactInteractionKey {
+  consumer: string;
+  provider: string;
+  interaction: string;
+  kind: PactKind;
+  interactionId?: string;
+}

package/src/wrapper-http.test.ts

@@ -0,0 +1,133 @@
+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 { readLedger } from './ledger.js';
+import {
+  withHttpPactInteraction,
+  type HttpInteraction,
+  type HttpPactLike,
+} from './wrapper-http.js';
+
+class FakeHttpPact implements HttpPactLike {
+  opts = { consumer: 'Web', provider: 'Catalog' };
+  added: HttpInteraction[] = [];
+
+  constructor(private failTest = false) {}
+
+  addInteraction(interaction: HttpInteraction): this {
+    this.added.push(interaction);
+    return this;
+  }
+
+  async executeTest<T>(
+    testFn: (s: { url: string; port: number }) => Promise<T>,
+  ): Promise<T | undefined> {
+    if (this.failTest) throw new Error('mock server failed to start');
+    return testFn({ url: 'http://127.0.0.1:9999', port: 9999 });
+  }
+}
+
+const sampleInteraction: HttpInteraction = {
+  uponReceiving: 'get all products',
+  states: [{ description: 'products exist' }],
+  withRequest: { method: 'GET', path: '/products' },
+  willRespondWith: { status: 200, body: [] },
+};
+
+let workDir: string;
+let originalCwd: string;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  workDir = mkdtempSync(path.join(tmpdir(), 'autotel-pact-http-'));
+  process.chdir(workDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  rmSync(workDir, { recursive: true, force: true });
+});
+
+describe('withHttpPactInteraction', () => {
+  it('adds the interaction to the pact and records a passed entry', async () => {
+    const pact = new FakeHttpPact();
+    let saw: string | undefined;
+    await withHttpPactInteraction(
+      pact,
+      sampleInteraction,
+      async (server) => {
+        saw = server.url;
+      },
+      { runId: 'r-http-pass' },
+    );
+
+    expect(saw).toBe('http://127.0.0.1:9999');
+    expect(pact.added).toHaveLength(1);
+    expect(pact.added[0]!.uponReceiving).toBe('get all products');
+
+    const entries = readLedger({ runId: 'r-http-pass' });
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      consumer: 'Web',
+      provider: 'Catalog',
+      interaction: 'get all products',
+      states: ['products exist'],
+      kind: 'http',
+      outcome: 'passed',
+    });
+  });
+
+  it('records a failed entry when the test body throws', async () => {
+    const pact = new FakeHttpPact();
+    await expect(
+      withHttpPactInteraction(
+        pact,
+        sampleInteraction,
+        async () => {
+          throw new Error('assertion failed');
+        },
+        { runId: 'r-http-fail' },
+      ),
+    ).rejects.toThrow('assertion failed');
+
+    const entries = readLedger({ runId: 'r-http-fail' });
+    expect(entries[0]).toMatchObject({ outcome: 'failed', error: 'assertion failed' });
+  });
+
+  it('records a failed entry when pact.executeTest itself throws', async () => {
+    const pact = new FakeHttpPact(true);
+    await expect(
+      withHttpPactInteraction(pact, sampleInteraction, async () => {}, {
+        runId: 'r-http-exec-fail',
+      }),
+    ).rejects.toThrow('mock server failed to start');
+
+    const entries = readLedger({ runId: 'r-http-exec-fail' });
+    expect(entries[0]!.outcome).toBe('failed');
+  });
+
+  it('rejects interactionId on HTTP with a clear error (no metadata channel in PactV3)', async () => {
+    const pact = new FakeHttpPact();
+    await expect(
+      withHttpPactInteraction(pact, sampleInteraction, async () => {}, {
+        runId: 'r-http-iid',
+        interactionId: 'products.list.v1',
+      }),
+    ).rejects.toThrow(/interactionId.*not yet supported for HTTP/);
+  });
+
+  it('throws helpful error when consumer/provider cannot be resolved', async () => {
+    const bare: HttpPactLike = {
+      addInteraction: () => {},
+      async executeTest(fn) {
+        return fn({ url: 'http://localhost', port: 0 });
+      },
+    };
+    await expect(
+      withHttpPactInteraction(bare, sampleInteraction, async () => {}, {
+        runId: 'r-http-no-cfg',
+      }),
+    ).rejects.toThrow(/could not resolve consumer\/provider/);
+  });
+});