autotel-eventcatalog 1.0.0

package/src/diff.ts

@@ -0,0 +1,296 @@
+// Compute drift between an autotel architecture snapshot and an existing
+// EventCatalog. The diff is intentionally conservative: it reports only
+// existence and field-path drift. Type drift, value drift, and enum-value
+// checks are deferred — they need richer signal than v0 carries.
+
+import type { ArchitectureSnapshot } from './snapshot';
+import type { CatalogState } from './catalog';
+
+export type EventDrift = {
+  /** Event names observed in the snapshot but not present in the catalog. */
+  observedButUndocumented: string[];
+  /** Event names declared in the catalog but never observed in the snapshot. */
+  documentedButUnseen: string[];
+  /** Per-event field-path mismatches. */
+  fieldDrift: FieldDrift[];
+  /** Per-event field type mismatches against declared schema types. */
+  typeDrift: TypeDrift[];
+  /** Per-event enum/value mismatches against declared schema enums. */
+  valueDrift: ValueDrift[];
+};
+
+export type FieldDrift = {
+  event: string;
+  /** Field paths in the observed payload but not declared in the schema. */
+  extra: string[];
+  /** Field paths declared in the schema but never observed in a payload. */
+  missing: string[];
+};
+
+export type TypeDrift = {
+  event: string;
+  path: string;
+  declared: string[];
+  observed: string[];
+};
+
+export type ValueDrift = {
+  event: string;
+  path: string;
+  declared: unknown[];
+  observed: unknown[];
+};
+
+export type ServiceDrift = {
+  /** Producers in the snapshot but not present in the catalog as services. */
+  observedButUndocumented: string[];
+};
+
+export type ChannelDrift = {
+  /** Channels in the snapshot but not present in the catalog. */
+  observedButUndocumented: string[];
+};
+
+export type DriftReport = {
+  snapshotGeneratedAt: string;
+  snapshotService: string;
+  events: EventDrift;
+  services: ServiceDrift;
+  channels: ChannelDrift;
+};
+
+/** True if the report contains any drift worth surfacing in a PR check. */
+export function hasDrift(report: DriftReport): boolean {
+  const c = countDriftReport(report);
+  return c.total > 0;
+}
+
+/**
+ * Per-category counts for a DriftReport. Keeps the dashboard's hero meter,
+ * the CLI's summary-output, and the action's structured output all agreeing
+ * on what "N findings" means.
+ */
+export type DriftCounts = {
+  /** Total of all categories — what a dashboard "drift findings" badge shows. */
+  total: number;
+  observedButUndocumentedEvents: number;
+  documentedButUnseenEvents: number;
+  /** Number of distinct events with field-path drift entries. */
+  fieldDriftEvents: number;
+  /** Sum of every individual extra + missing path across all fieldDrift entries. */
+  fieldDriftPaths: number;
+  typeDriftPaths: number;
+  valueDriftPaths: number;
+  undocumentedServices: number;
+  undocumentedChannels: number;
+};
+
+export function countDriftReport(report: DriftReport): DriftCounts {
+  const typeDrift = report.events.typeDrift ?? [];
+  const valueDrift = report.events.valueDrift ?? [];
+  const fieldDriftEvents = report.events.fieldDrift.length;
+  const fieldDriftPaths = report.events.fieldDrift.reduce(
+    (sum, fd) => sum + fd.extra.length + fd.missing.length,
+    0,
+  );
+  const typeDriftPaths = typeDrift.length;
+  const valueDriftPaths = valueDrift.length;
+  const observedButUndocumentedEvents =
+    report.events.observedButUndocumented.length;
+  const documentedButUnseenEvents = report.events.documentedButUnseen.length;
+  const undocumentedServices = report.services.observedButUndocumented.length;
+  const undocumentedChannels = report.channels.observedButUndocumented.length;
+
+  return {
+    observedButUndocumentedEvents,
+    documentedButUnseenEvents,
+    fieldDriftEvents,
+    fieldDriftPaths,
+    typeDriftPaths,
+    valueDriftPaths,
+    undocumentedServices,
+    undocumentedChannels,
+    total:
+      observedButUndocumentedEvents +
+      documentedButUnseenEvents +
+      fieldDriftPaths +
+      typeDriftPaths +
+      valueDriftPaths +
+      undocumentedServices +
+      undocumentedChannels,
+  };
+}
+
+export function diffCatalogAgainstSnapshot(
+  snapshot: ArchitectureSnapshot,
+  catalog: CatalogState,
+): DriftReport {
+  const snapshotEvents = new Set(Object.keys(snapshot.events));
+  const catalogEventIds = new Set(catalog.events.keys());
+
+  // Catalog event IDs are PascalCase ("OrderPlaced") while track() names are
+  // dotted ("order.placed"). We compare on a normalised form so the same
+  // event isn't reported as both missing and extra.
+  const catalogEventByNormalised = new Map<string, string>();
+  for (const id of catalogEventIds) {
+    catalogEventByNormalised.set(normaliseEventId(id), id);
+  }
+
+  const observedButUndocumented: string[] = [];
+  const matchedCatalogIds = new Set<string>();
+  for (const name of snapshotEvents) {
+    const matched = catalogEventByNormalised.get(normaliseEventId(name));
+    if (matched) {
+      matchedCatalogIds.add(matched);
+    } else {
+      observedButUndocumented.push(name);
+    }
+  }
+
+  const documentedButUnseen: string[] = [];
+  for (const id of catalogEventIds) {
+    if (!matchedCatalogIds.has(id)) documentedButUnseen.push(id);
+  }
+
+  const fieldDrift: FieldDrift[] = [];
+  const typeDrift: TypeDrift[] = [];
+  const valueDrift: ValueDrift[] = [];
+  for (const [snapName, obs] of Object.entries(snapshot.events)) {
+    const catalogId = catalogEventByNormalised.get(normaliseEventId(snapName));
+    if (!catalogId) continue;
+    const eventDecl = catalog.events.get(catalogId);
+    const declared = eventDecl?.declaredFieldPaths;
+    if (!declared) continue;
+
+    const declaredSet = new Set(declared);
+    const observedSet = new Set(obs.fieldPaths);
+
+    const extra = obs.fieldPaths.filter((p) => !declaredSet.has(p));
+    const missing = declared.filter((p) => !observedSet.has(p));
+
+    if (extra.length > 0 || missing.length > 0) {
+      fieldDrift.push({ event: snapName, extra, missing });
+    }
+
+    const constraints = eventDecl?.declaredSchemaConstraints ?? {};
+    const stats =
+      (
+        obs as {
+          fieldStats?: Record<
+            string,
+            { types: string[]; sampleValues: unknown[] }
+          >;
+        }
+      ).fieldStats ?? {};
+    for (const [path, declaredConstraint] of Object.entries(constraints)) {
+      const observed = stats[path];
+      if (!observed) continue;
+      if (declaredConstraint.types && declaredConstraint.types.length > 0) {
+        // JSON Schema has `integer`; JavaScript has only `number`. Treat the
+        // two as compatible at the runtime-type level, then use sample values
+        // to flag the real signal (a non-integer value seen against an
+        // integer-only declaration).
+        const accepts = expandDeclaredTypes(declaredConstraint.types);
+        const badTypes = observed.types.filter((t: string) => !accepts.has(t));
+        const integerDeclared =
+          declaredConstraint.types.includes('integer') &&
+          !declaredConstraint.types.includes('number');
+        const nonIntegerSamples = integerDeclared
+          ? observed.sampleValues.filter(
+              (v: unknown) => typeof v === 'number' && !Number.isInteger(v),
+            )
+          : [];
+        if (badTypes.length > 0 || nonIntegerSamples.length > 0) {
+          typeDrift.push({
+            event: snapName,
+            path,
+            declared: declaredConstraint.types,
+            observed: [...new Set(observed.types)].toSorted(),
+          });
+        }
+      }
+      if (
+        declaredConstraint.enumValues &&
+        declaredConstraint.enumValues.length > 0 &&
+        observed.sampleValues.length > 0
+      ) {
+        const observedOutsideEnum = observed.sampleValues.filter(
+          (v: unknown) =>
+            !declaredConstraint.enumValues?.some((d) => Object.is(d, v)),
+        );
+        if (observedOutsideEnum.length > 0) {
+          valueDrift.push({
+            event: snapName,
+            path,
+            declared: declaredConstraint.enumValues,
+            observed: [...new Set(observedOutsideEnum)] as unknown[],
+          });
+        }
+      }
+    }
+  }
+
+  const snapshotServices = collectProducers(snapshot);
+  const catalogServiceIds = new Set(catalog.services.keys());
+  const undocumentedServices = [...snapshotServices].filter(
+    (id) => !catalogServiceIds.has(id),
+  );
+
+  const snapshotChannels = collectChannels(snapshot);
+  const catalogChannelIds = new Set(catalog.channels.keys());
+  const undocumentedChannels = [...snapshotChannels].filter(
+    (id) => !catalogChannelIds.has(id),
+  );
+
+  return {
+    snapshotGeneratedAt: snapshot.generatedAt,
+    snapshotService: snapshot.service,
+    events: {
+      observedButUndocumented: observedButUndocumented.sort(),
+      documentedButUnseen: documentedButUnseen.sort(),
+      fieldDrift: fieldDrift.sort((a, b) => a.event.localeCompare(b.event)),
+      typeDrift: typeDrift.sort((a, b) =>
+        `${a.event}.${a.path}`.localeCompare(`${b.event}.${b.path}`),
+      ),
+      valueDrift: valueDrift.sort((a, b) =>
+        `${a.event}.${a.path}`.localeCompare(`${b.event}.${b.path}`),
+      ),
+    },
+    services: { observedButUndocumented: undocumentedServices.sort() },
+    channels: { observedButUndocumented: undocumentedChannels.sort() },
+  };
+}
+
+/**
+ * Map declared JSON Schema types to the set of runtime types we accept at
+ * `typeof` level. JSON Schema's `integer` is a refinement of `number` (JS
+ * does not have a separate integer type), so we accept observed `number` for
+ * either declaration. The integer-vs-fractional distinction is then enforced
+ * separately against sample values.
+ */
+function expandDeclaredTypes(declared: string[]): Set<string> {
+  const accepts = new Set<string>(declared);
+  if (declared.includes('integer')) accepts.add('number');
+  return accepts;
+}
+
+function normaliseEventId(id: string): string {
+  // "order.placed" -> "orderplaced", "OrderPlaced" -> "orderplaced".
+  return id.toLowerCase().replaceAll(/[._\-\s]/g, '');
+}
+
+function collectProducers(snapshot: ArchitectureSnapshot): Set<string> {
+  const out = new Set<string>();
+  for (const obs of Object.values(snapshot.events)) {
+    if (obs.producer) out.add(obs.producer);
+  }
+  return out;
+}
+
+function collectChannels(snapshot: ArchitectureSnapshot): Set<string> {
+  const out = new Set<string>();
+  for (const obs of Object.values(snapshot.events)) {
+    if (obs.channel) out.add(obs.channel);
+  }
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+// autotel-eventcatalog
+//
+// Diff your autotel architecture snapshot against an EventCatalog and report
+// drift. Same shape as Pact, for event architectures.
+
+export { loadSnapshot } from './snapshot';
+export type { ArchitectureSnapshot, EventObservation } from './snapshot';
+
+export { readCatalogState, extractDeclaredFieldPaths } from './catalog';
+export type {
+  CatalogState,
+  CatalogEvent,
+  CatalogService,
+  CatalogChannel,
+} from './catalog';
+
+export { diffCatalogAgainstSnapshot, hasDrift, countDriftReport } from './diff';
+export type {
+  DriftReport,
+  EventDrift,
+  FieldDrift,
+  ServiceDrift,
+  ChannelDrift,
+  DriftCounts,
+} from './diff';
+
+export {
+  compareDriftReports,
+  countDriftEntries,
+  countDriftDelta,
+} from './diff-vs-base';
+export type { DriftDelta, DriftEntries } from './diff-vs-base';
+
+export {
+  renderMarkdown,
+  renderDeltaMarkdown,
+  renderTerminal,
+  renderDeltaTerminal,
+  renderJson,
+  REPORT_SPEC,
+  RENDERERS,
+  RENDERER_NAMES,
+  getRenderer,
+} from './report';
+export type {
+  JsonReport,
+  JsonReportEnvelope,
+  Renderer,
+  RendererName,
+} from './report';
+
+export { evaluatePolicy } from './policy';
+export type {
+  DriftPolicyMode,
+  PolicyEvaluationInput,
+  PolicyEvaluationResult,
+} from './policy';
+
+export {
+  stampCatalog,
+  buildStampBlock,
+  buildStampSummary,
+  STAMP_START,
+  STAMP_END,
+  STAMP_SUMMARY_SPEC,
+} from './stamp';
+export type {
+  StampOptions,
+  StampResult,
+  StampUpdate,
+  StampSkip,
+  StampSummary,
+} from './stamp';

package/src/policy.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { evaluatePolicy } from './policy';
+import type { DriftReport } from './diff';
+import type { DriftDelta } from './diff-vs-base';
+
+const cleanReport: DriftReport = {
+  snapshotGeneratedAt: '2026-05-21T18:04:00.000Z',
+  snapshotService: 'orders',
+  events: {
+    observedButUndocumented: [],
+    documentedButUnseen: [],
+    fieldDrift: [],
+  },
+  services: { observedButUndocumented: [] },
+  channels: { observedButUndocumented: [] },
+};
+
+function delta(hasNewDrift: boolean): DriftDelta {
+  return {
+    hasNewDrift,
+    introduced: {
+      events: {
+        observedButUndocumented: [],
+        documentedButUnseen: [],
+        fieldDrift: [],
+      },
+      services: { observedButUndocumented: [] },
+      channels: { observedButUndocumented: [] },
+    },
+    resolved: {
+      events: {
+        observedButUndocumented: [],
+        documentedButUnseen: [],
+        fieldDrift: [],
+      },
+      services: { observedButUndocumented: [] },
+      channels: { observedButUndocumented: [] },
+    },
+  };
+}
+
+describe('evaluatePolicy', () => {
+  it('fails in all mode when drift exists', () => {
+    const result = evaluatePolicy({
+      mode: 'all',
+      report: {
+        ...cleanReport,
+        events: {
+          ...cleanReport.events,
+          observedButUndocumented: ['order.cancelled'],
+        },
+      },
+    });
+    expect(result.shouldFail).toBe(true);
+    expect(result.reason).toMatch(/Drift detected/);
+  });
+
+  it('passes in all mode when drift does not exist', () => {
+    const result = evaluatePolicy({ mode: 'all', report: cleanReport });
+    expect(result.shouldFail).toBe(false);
+    expect(result.reason).toMatch(/No drift detected/);
+  });
+
+  it('fails in new-only mode when new drift exists', () => {
+    const result = evaluatePolicy({ mode: 'new-only', delta: delta(true) });
+    expect(result.shouldFail).toBe(true);
+    expect(result.reason).toMatch(/New drift introduced/);
+  });
+
+  it('passes in new-only mode when no new drift exists', () => {
+    const result = evaluatePolicy({ mode: 'new-only', delta: delta(false) });
+    expect(result.shouldFail).toBe(false);
+    expect(result.reason).toMatch(/No new drift/);
+  });
+});

package/src/policy.ts

@@ -0,0 +1,41 @@
+// Decide whether a drift outcome should fail a CI job.
+//
+// `policy` answers the gating question; it deliberately doesn't render or
+// print anything. `reason` carries a short, log-friendly explanation that
+// CLI / Action layers can surface in their exit messages.
+
+import type { DriftDelta } from './diff-vs-base';
+import type { DriftReport } from './diff';
+import { hasDrift } from './diff';
+
+export type DriftPolicyMode = 'all' | 'new-only';
+
+export type PolicyEvaluationInput =
+  | { mode: 'all'; report: DriftReport }
+  | { mode: 'new-only'; delta: DriftDelta };
+
+export type PolicyEvaluationResult = {
+  shouldFail: boolean;
+  reason: string;
+};
+
+export function evaluatePolicy(
+  input: PolicyEvaluationInput,
+): PolicyEvaluationResult {
+  if (input.mode === 'all') {
+    const shouldFail = hasDrift(input.report);
+    return {
+      shouldFail,
+      reason: shouldFail
+        ? 'Drift detected in current snapshot.'
+        : 'No drift detected.',
+    };
+  }
+  const shouldFail = input.delta.hasNewDrift;
+  return {
+    shouldFail,
+    reason: shouldFail
+      ? 'New drift introduced compared to baseline snapshot.'
+      : 'No new drift introduced compared to baseline snapshot.',
+  };
+}

package/src/renderers/index.ts

@@ -0,0 +1,35 @@
+// Registry of available renderers. The CLI dispatches `--format <name>`
+// through here; future renderers (sarif, slack, github-check-runs) drop in
+// by adding an entry to `RENDERERS`.
+
+import type { Renderer } from './types';
+import { markdownRenderer } from './markdown';
+import { terminalRenderer } from './terminal';
+import { jsonRenderer } from './json';
+
+export const RENDERERS: readonly Renderer[] = [
+  markdownRenderer,
+  terminalRenderer,
+  jsonRenderer,
+];
+
+export const RENDERER_NAMES = RENDERERS.map((r) => r.name);
+
+export function getRenderer(name: string): Renderer | undefined {
+  return RENDERERS.find((r) => r.name === name);
+}
+
+export type RendererName = (typeof RENDERER_NAMES)[number];
+
+// Re-export the individual functions for backwards compatibility — they have
+// been the public API since v0.1.0 and consumers may import them directly.
+
+export { renderMarkdown, renderDeltaMarkdown } from './markdown';
+export { renderTerminal, renderDeltaTerminal } from './terminal';
+export {
+  renderJson,
+  REPORT_SPEC,
+  type JsonReport,
+  type JsonReportEnvelope,
+} from './json';
+export { type Renderer } from './types';

package/src/renderers/json.ts

@@ -0,0 +1,33 @@
+// Versioned JSON envelope. Downstream tooling (dashboards, custom CI steps,
+// Slack bots) should read this rather than scraping the Markdown body. The
+// shape is governed by the published schema at
+// `schemas/drift-report-v0.2.0.json` and locked by golden contract tests.
+
+import type { DriftReport } from '../diff';
+import type { DriftDelta } from '../diff-vs-base';
+import type { Renderer } from './types';
+
+/**
+ * Versioned identifier baked into the JSON envelope. Bumping it is a
+ * breaking change for downstream consumers — add fields rather than rename.
+ */
+export const REPORT_SPEC = 'autotel-eventcatalog-report/v0.2.0' as const;
+
+export type JsonReport =
+  | { mode: 'all'; report: DriftReport }
+  | { mode: 'new-only'; delta: DriftDelta };
+
+export type JsonReportEnvelope = { spec: typeof REPORT_SPEC } & JsonReport;
+
+export function renderJson(data: JsonReport): string {
+  const envelope: JsonReportEnvelope = { spec: REPORT_SPEC, ...data };
+  return JSON.stringify(envelope, null, 2);
+}
+
+export const jsonRenderer: Renderer = {
+  name: 'json',
+  description:
+    'Versioned JSON envelope. Validate against schemas/drift-report-v0.2.0.json.',
+  renderReport: (report) => renderJson({ mode: 'all', report }),
+  renderDelta: (delta) => renderJson({ mode: 'new-only', delta }),
+};