autotel-pact 0.2.0

package/src/ledger-normalize.ts

@@ -0,0 +1,82 @@
+import {
+  LEDGER_ENTRY_SPEC,
+  type InteractionLedgerEntry,
+  type LedgerRecord,
+  type ProviderVerificationRunEntry,
+} from './types.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Validate a parsed JSONL line and return a typed ledger record.
+ * Rejects anything that does not match the current v0.2 spec.
+ */
+export function normalizeLedgerRecord(parsed: unknown): LedgerRecord | null {
+  if (!isRecord(parsed) || parsed.spec !== LEDGER_ENTRY_SPEC) return null;
+
+  const { consumer, provider, observed_at } = parsed;
+  if (
+    typeof consumer !== 'string' ||
+    typeof provider !== 'string' ||
+    typeof observed_at !== 'string'
+  ) {
+    return null;
+  }
+
+  if (parsed.type === 'provider_verification_run') {
+    if (typeof parsed.error !== 'string') return null;
+    const entry: ProviderVerificationRunEntry = {
+      type: 'provider_verification_run',
+      spec: LEDGER_ENTRY_SPEC,
+      consumer,
+      provider,
+      outcome: 'failed',
+      source: parsed.source === 'production' ? 'production' : 'test',
+      role: 'provider',
+      observed_at,
+      error: parsed.error,
+    };
+    if (typeof parsed.run_id === 'string') entry.run_id = parsed.run_id;
+    if (typeof parsed.git_sha === 'string') entry.git_sha = parsed.git_sha;
+    if (typeof parsed.trace_id === 'string') entry.trace_id = parsed.trace_id;
+    if (typeof parsed.span_id === 'string') entry.span_id = parsed.span_id;
+    return entry;
+  }
+
+  if (typeof parsed.interaction !== 'string') return null;
+
+  const states = Array.isArray(parsed.states)
+    ? parsed.states.filter((s): s is string => typeof s === 'string')
+    : [];
+
+  const entry: InteractionLedgerEntry = {
+    type: 'interaction',
+    spec: LEDGER_ENTRY_SPEC,
+    consumer,
+    provider,
+    interaction: parsed.interaction,
+    states,
+    kind: parsed.kind === 'http' ? 'http' : 'message',
+    outcome: parsed.outcome === 'failed' ? 'failed' : 'passed',
+    source: parsed.source === 'production' ? 'production' : 'test',
+    role: parsed.role === 'provider' ? 'provider' : 'consumer',
+    duration_ms:
+      typeof parsed.duration_ms === 'number' && parsed.duration_ms >= 0
+        ? parsed.duration_ms
+        : 0,
+    observed_at,
+  };
+
+  if (typeof parsed.interaction_id === 'string' && parsed.interaction_id.length > 0) {
+    entry.interaction_id = parsed.interaction_id;
+  }
+  if (typeof parsed.trace_id === 'string') entry.trace_id = parsed.trace_id;
+  if (typeof parsed.span_id === 'string') entry.span_id = parsed.span_id;
+  if (typeof parsed.run_id === 'string') entry.run_id = parsed.run_id;
+  if (typeof parsed.git_sha === 'string') entry.git_sha = parsed.git_sha;
+  if (typeof parsed.error === 'string') entry.error = parsed.error;
+
+  return entry;
+}

package/src/ledger.test.ts

@@ -0,0 +1,92 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { appendLedgerEntry, ledgerPath, readLedger } from './ledger.js';
+import { isInteractionLedgerEntry, type InteractionLedgerEntry } from './types.js';
+
+let workDir: string;
+let originalCwd: string;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  workDir = mkdtempSync(path.join(tmpdir(), 'autotel-pact-test-'));
+  process.chdir(workDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  rmSync(workDir, { recursive: true, force: true });
+  delete process.env.AUTOTEL_PACT_RUN_ID;
+  delete process.env.AUTOTEL_PACT_LEDGER_DIR;
+});
+
+import { LEDGER_ENTRY_SPEC } from './types.js';
+
+function sampleEntry(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: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe('ledger', () => {
+  it('writes JSONL entries that round-trip via readLedger', () => {
+    const opts = { runId: 'r1' };
+    appendLedgerEntry(sampleEntry({ interaction: 'one' }), opts);
+    appendLedgerEntry(sampleEntry({ interaction: 'two' }), opts);
+
+    const entries = readLedger(opts);
+    expect(entries).toHaveLength(2);
+    expect(entries.map((e) => (isInteractionLedgerEntry(e) ? e.interaction : ''))).toEqual([
+      'one',
+      'two',
+    ]);
+  });
+
+  it('skips malformed lines silently', () => {
+    const opts = { runId: 'r2' };
+    appendLedgerEntry(sampleEntry({ interaction: 'good' }), opts);
+    const path = ledgerPath(opts);
+    // simulate corruption
+    const { appendFileSync } = require('node:fs');
+    appendFileSync(path, 'not-json\n', 'utf8');
+
+    const entries = readLedger(opts);
+    expect(entries).toHaveLength(1);
+    expect(isInteractionLedgerEntry(entries[0]!) && entries[0].interaction).toBe('good');
+  });
+
+  it('reads multiple ledger files in the directory', () => {
+    appendLedgerEntry(sampleEntry({ interaction: 'a' }), { runId: 'r-a' });
+    appendLedgerEntry(sampleEntry({ interaction: 'b' }), { runId: 'r-b' });
+
+    const entries = readLedger({});
+    expect(
+      entries
+        .map((e) => (isInteractionLedgerEntry(e) ? e.interaction : ''))
+        .toSorted(),
+    ).toEqual(['a', 'b']);
+  });
+
+  it('returns an empty array when the ledger directory does not exist', () => {
+    expect(readLedger({ dir: '.does-not-exist' })).toEqual([]);
+  });
+
+  it('honours AUTOTEL_PACT_RUN_ID', () => {
+    process.env.AUTOTEL_PACT_RUN_ID = 'env-run';
+    const path = ledgerPath({});
+    expect(path).toMatch(/ledger-env-run\.jsonl$/);
+  });
+});

package/src/ledger.ts

@@ -0,0 +1,156 @@
+import {
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  existsSync,
+} from 'node:fs';
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeLedgerRecord } from './ledger-normalize.js';
+import { LEDGER_ENTRY_SPEC, type LedgerRecord } from './types.js';
+
+export interface LedgerOptions {
+  dir?: string;
+  runId?: string;
+}
+
+const DEFAULT_DIR = '.autotel-pact';
+
+function resolveLedgerDir(opts: LedgerOptions = {}): string {
+  return path.resolve(process.cwd(), opts.dir ?? process.env.AUTOTEL_PACT_LEDGER_DIR ?? DEFAULT_DIR);
+}
+
+function resolveRunId(opts: LedgerOptions = {}): string {
+  const explicit = opts.runId ?? process.env.AUTOTEL_PACT_RUN_ID;
+  if (explicit) return explicit;
+  return `local-${new Date().toISOString().replaceAll(/[:.]/g, '-')}`;
+}
+
+export function ledgerPath(opts: LedgerOptions = {}): string {
+  const dir = resolveLedgerDir(opts);
+  return path.join(dir, `ledger-${resolveRunId(opts)}.jsonl`);
+}
+
+function writeLine(filePath: string, entry: LedgerRecord): void {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  appendFileSync(filePath, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+/**
+ * Append a ledger record synchronously (tests and consumer wrappers).
+ */
+export function appendLedgerEntry(
+  entry: LedgerRecord,
+  opts: LedgerOptions = {},
+): void {
+  const filePath = ledgerPath(opts);
+  const normalized: LedgerRecord =
+    entry.type === 'provider_verification_run'
+      ? entry
+      : { ...entry, spec: LEDGER_ENTRY_SPEC, type: 'interaction' as const };
+  writeLine(filePath, normalized);
+}
+
+export function appendProviderVerificationFailure(
+  entry: Omit<
+    import('./types.js').ProviderVerificationRunEntry,
+    'type' | 'spec' | 'outcome' | 'role'
+  > & { error: string },
+  opts: LedgerOptions = {},
+): void {
+  appendLedgerEntry(
+    {
+      type: 'provider_verification_run',
+      spec: LEDGER_ENTRY_SPEC,
+      outcome: 'failed',
+      role: 'provider',
+      source: entry.source ?? 'test',
+      consumer: entry.consumer,
+      provider: entry.provider,
+      observed_at: entry.observed_at,
+      error: entry.error,
+      run_id: entry.run_id,
+      git_sha: entry.git_sha,
+      trace_id: entry.trace_id,
+      span_id: entry.span_id,
+    },
+    opts,
+  );
+}
+
+/**
+ * Read all ledger files and return normalized records.
+ */
+export function readLedger(opts: LedgerOptions = {}): LedgerRecord[] {
+  const dir = resolveLedgerDir(opts);
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+  const entries: LedgerRecord[] = [];
+  for (const file of files) {
+    const text = readFileSync(path.join(dir, file), 'utf8');
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const normalized = normalizeLedgerRecord(JSON.parse(line));
+        if (normalized) entries.push(normalized);
+      } catch {
+        // skip malformed lines
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * Serialized async writes for production span processor.
+ * Bounded by a producer-side backpressure threshold: once `pendingWrites`
+ * reaches `MAX_PENDING_WRITES`, new callers await drainage before queueing,
+ * so memory cannot grow unbounded under sustained pressure.
+ */
+const MAX_PENDING_WRITES = 4096;
+let asyncWriteChain: Promise<void> = Promise.resolve();
+let pendingWrites = 0;
+
+export async function appendLedgerEntryAsync(
+  entry: LedgerRecord,
+  opts: LedgerOptions = {},
+): Promise<void> {
+  if (pendingWrites >= MAX_PENDING_WRITES) {
+    await asyncWriteChain;
+  }
+
+  const filePath = ledgerPath(opts);
+  const normalized: LedgerRecord =
+    entry.type === 'provider_verification_run'
+      ? entry
+      : { ...entry, spec: LEDGER_ENTRY_SPEC, type: 'interaction' as const };
+  const line = JSON.stringify(normalized);
+
+  pendingWrites++;
+  const run = asyncWriteChain.then(async () => {
+    try {
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await appendFile(filePath, line + '\n', 'utf8');
+    } finally {
+      pendingWrites--;
+    }
+  });
+  asyncWriteChain = run.catch(() => {});
+  return run;
+}
+
+export async function flushLedgerWrites(): Promise<void> {
+  await asyncWriteChain;
+}
+
+/** @internal Reset async chain between tests. */
+export function resetLedgerWriteChainForTests(): void {
+  asyncWriteChain = Promise.resolve();
+  pendingWrites = 0;
+}
+
+/** @internal Expose pending write count for tests. */
+export function pendingLedgerWriteCount(): number {
+  return pendingWrites;
+}

package/src/pact-file.test.ts

@@ -0,0 +1,124 @@
+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 {
+  extractInteractionId,
+  interactionsFromPactFile,
+  listPactFiles,
+  parsePactFile,
+} from './pact-file.js';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'autotel-pact-file-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('listPactFiles', () => {
+  it('returns [] for missing directory', () => {
+    expect(listPactFiles(path.join(dir, 'does-not-exist'))).toEqual([]);
+  });
+
+  it('lists json files in a flat directory', () => {
+    writeFileSync(path.join(dir, 'a.json'), '{}');
+    writeFileSync(path.join(dir, 'b.json'), '{}');
+    writeFileSync(path.join(dir, 'ignore.txt'), 'no');
+    const files = listPactFiles(dir).map((f) => path.basename(f)).toSorted();
+    expect(files).toEqual(['a.json', 'b.json']);
+  });
+
+  it('recurses into nested directories', () => {
+    mkdirSync(path.join(dir, 'nested'));
+    writeFileSync(path.join(dir, 'nested', 'c.json'), '{}');
+    writeFileSync(path.join(dir, 'top.json'), '{}');
+    const files = listPactFiles(dir).map((f) => path.basename(f)).toSorted();
+    expect(files).toEqual(['c.json', 'top.json']);
+  });
+});
+
+describe('parsePactFile', () => {
+  it('returns parsed object for valid JSON', () => {
+    const file = path.join(dir, 'p.json');
+    writeFileSync(file, JSON.stringify({ consumer: { name: 'A' }, provider: { name: 'B' } }));
+    expect(parsePactFile(file)?.consumer.name).toBe('A');
+  });
+
+  it('returns null for malformed JSON', () => {
+    const file = path.join(dir, 'bad.json');
+    writeFileSync(file, '{ this is not json');
+    expect(parsePactFile(file)).toBeNull();
+  });
+
+  it('returns null for missing file', () => {
+    expect(parsePactFile(path.join(dir, 'nope.json'))).toBeNull();
+  });
+});
+
+describe('interactionsFromPactFile', () => {
+  it('extracts message interactions', () => {
+    const keys = interactionsFromPactFile({
+      consumer: { name: 'A' },
+      provider: { name: 'B' },
+      messages: [
+        { description: 'evt1', providerStates: [{ name: 'state' }] },
+        { description: 'evt2' },
+      ],
+    });
+    expect(keys).toEqual([
+      { consumer: 'A', provider: 'B', interaction: 'evt1', kind: 'message', interactionId: undefined },
+      { consumer: 'A', provider: 'B', interaction: 'evt2', kind: 'message', interactionId: undefined },
+    ]);
+  });
+
+  it('extracts http interactions', () => {
+    const keys = interactionsFromPactFile({
+      consumer: { name: 'A' },
+      provider: { name: 'B' },
+      interactions: [{ description: 'GET /orders' }],
+    });
+    expect(keys).toEqual([
+      { consumer: 'A', provider: 'B', interaction: 'GET /orders', kind: 'http', interactionId: undefined },
+    ]);
+  });
+
+  it('returns [] when consumer or provider missing', () => {
+    expect(
+      interactionsFromPactFile({
+        consumer: { name: '' },
+        provider: { name: 'B' },
+        messages: [{ description: 'x' }],
+      }),
+    ).toEqual([]);
+  });
+
+  it('picks up interactionId from metadata', () => {
+    const keys = interactionsFromPactFile({
+      consumer: { name: 'A' },
+      provider: { name: 'B' },
+      messages: [
+        { description: 'evt', metadata: { interactionId: 'iid-1' } },
+      ],
+    });
+    expect(keys[0]?.interactionId).toBe('iid-1');
+  });
+});
+
+describe('extractInteractionId', () => {
+  it('accepts snake_case and camelCase', () => {
+    expect(extractInteractionId({ interaction_id: 'snake' })).toBe('snake');
+    expect(extractInteractionId({ interactionId: 'camel' })).toBe('camel');
+  });
+
+  it('returns undefined for non-string or empty', () => {
+    expect(extractInteractionId({})).toBeUndefined();
+    expect(extractInteractionId({ interactionId: '' })).toBeUndefined();
+    expect(extractInteractionId({ interactionId: 42 })).toBeUndefined();
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    expect(extractInteractionId(undefined)).toBeUndefined();
+  });
+});

package/src/pact-file.ts

@@ -0,0 +1,65 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { PactFile, PactInteractionKey } from './types.js';
+
+/**
+ * Walk a directory and return absolute paths of all *.json pact files.
+ */
+export function listPactFiles(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listPactFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.json')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+export function extractInteractionId(
+  metadata: Record<string, unknown> | undefined,
+): string | undefined {
+  if (!metadata) return undefined;
+  const id = metadata.interactionId ?? metadata.interaction_id;
+  return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+
+/**
+ * Extract interaction tuples declared in a pact file.
+ */
+export function interactionsFromPactFile(pact: PactFile): PactInteractionKey[] {
+  const consumer = pact.consumer?.name;
+  const provider = pact.provider?.name;
+  if (!consumer || !provider) return [];
+  const keys: PactInteractionKey[] = [];
+  for (const m of pact.messages ?? []) {
+    keys.push({
+      consumer,
+      provider,
+      interaction: m.description,
+      kind: 'message',
+      interactionId: extractInteractionId(m.metadata),
+    });
+  }
+  for (const i of pact.interactions ?? []) {
+    keys.push({
+      consumer,
+      provider,
+      interaction: i.description,
+      kind: 'http',
+      interactionId: extractInteractionId(i.metadata),
+    });
+  }
+  return keys;
+}
+
+export function parsePactFile(filePath: string): PactFile | null {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8')) as PactFile;
+  } catch {
+    return null;
+  }
+}

package/src/processor.test.ts

@@ -0,0 +1,90 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { PACT_ATTRS } from './attrs.js';
+import { flushLedgerWrites, readLedger, resetLedgerWriteChainForTests } from './ledger.js';
+import { PactLedgerSpanProcessor } from './processor.js';
+
+let workDir: string;
+let originalCwd: string;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  workDir = mkdtempSync(path.join(tmpdir(), 'autotel-pact-proc-'));
+  process.chdir(workDir);
+  resetLedgerWriteChainForTests();
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  rmSync(workDir, { recursive: true, force: true });
+});
+
+function fakeSpan(attrs: Record<string, unknown>) {
+  return {
+    attributes: attrs,
+    spanContext: () => ({ traceId: 't1', spanId: 's1' }),
+  };
+}
+
+describe('PactLedgerSpanProcessor', () => {
+  it('writes production ledger entries for pact-tagged spans', async () => {
+    const proc = new PactLedgerSpanProcessor({ runId: 'prod-1' });
+    proc.onEnd(
+      fakeSpan({
+        [PACT_ATTRS.CONSUMER]: 'A',
+        [PACT_ATTRS.PROVIDER]: 'B',
+        [PACT_ATTRS.INTERACTION_DESCRIPTION]: 'evt',
+        [PACT_ATTRS.KIND]: 'message',
+      }),
+    );
+    await proc.forceFlush();
+
+    const entries = readLedger({ runId: 'prod-1' });
+    expect(entries).toHaveLength(1);
+    if (entries[0]!.type === 'provider_verification_run') throw new Error('expected interaction');
+    expect(entries[0]).toMatchObject({
+      source: 'production',
+      role: 'consumer',
+      interaction: 'evt',
+    });
+  });
+
+  it('does not throw when ledger write fails', async () => {
+    const proc = new PactLedgerSpanProcessor({
+      runId: 'x',
+      dir: '/\0invalid',
+      onWriteError: vi.fn(),
+    });
+    expect(() =>
+      proc.onEnd(
+        fakeSpan({
+          [PACT_ATTRS.CONSUMER]: 'A',
+          [PACT_ATTRS.PROVIDER]: 'B',
+          [PACT_ATTRS.INTERACTION_DESCRIPTION]: 'evt',
+        }),
+      ),
+    ).not.toThrow();
+    await proc.forceFlush();
+  });
+
+  it('drops oldest when queue is full', async () => {
+    const onDrop = vi.fn();
+    const proc = new PactLedgerSpanProcessor({
+      runId: 'drop',
+      maxQueueSize: 1,
+      onDrop,
+      onWarn: () => {},
+    });
+    const span = fakeSpan({
+      [PACT_ATTRS.CONSUMER]: 'A',
+      [PACT_ATTRS.PROVIDER]: 'B',
+      [PACT_ATTRS.INTERACTION_DESCRIPTION]: 'evt',
+    });
+    proc.onEnd(span);
+    proc.onEnd(span);
+    await proc.forceFlush();
+    expect(onDrop).toHaveBeenCalled();
+  });
+});