autotel-eventcatalog 1.0.0

package/src/diff-vs-base.ts

@@ -0,0 +1,242 @@
+// Compare two drift reports (base branch vs PR head) and produce a "what
+// this PR introduces" view. Without this, a PR check fails forever on
+// pre-existing drift; with it, the check only fails on drift the PR is
+// responsible for.
+
+import type {
+  DriftReport,
+  FieldDrift,
+  DriftCounts,
+  TypeDrift,
+  ValueDrift,
+} from './diff';
+
+export type DriftDelta = {
+  /** Drift entries present in head but not in base. */
+  introduced: DriftEntries;
+  /** Drift entries present in base but not in head — the PR fixed these. */
+  resolved: DriftEntries;
+  /** True if `introduced` has any non-empty section. */
+  hasNewDrift: boolean;
+};
+
+export type DriftEntries = {
+  events: {
+    observedButUndocumented: string[];
+    documentedButUnseen: string[];
+    fieldDrift: FieldDrift[];
+    typeDrift: TypeDrift[];
+    valueDrift: ValueDrift[];
+  };
+  services: { observedButUndocumented: string[] };
+  channels: { observedButUndocumented: string[] };
+};
+
+export function compareDriftReports(
+  base: DriftReport,
+  head: DriftReport,
+): DriftDelta {
+  const introducedEvents = diffStringList(
+    base.events.observedButUndocumented,
+    head.events.observedButUndocumented,
+  );
+  const introducedMissing = diffStringList(
+    base.events.documentedButUnseen,
+    head.events.documentedButUnseen,
+  );
+  const introducedFieldDrift = diffFieldDrift(
+    base.events.fieldDrift,
+    head.events.fieldDrift,
+  );
+  const introducedServices = diffStringList(
+    base.services.observedButUndocumented,
+    head.services.observedButUndocumented,
+  );
+  const introducedChannels = diffStringList(
+    base.channels.observedButUndocumented,
+    head.channels.observedButUndocumented,
+  );
+
+  const introduced: DriftEntries = {
+    events: {
+      observedButUndocumented: introducedEvents.added,
+      documentedButUnseen: introducedMissing.added,
+      fieldDrift: introducedFieldDrift.added,
+      typeDrift: diffTypeDrift(
+        base.events.typeDrift ?? [],
+        head.events.typeDrift ?? [],
+      ).added,
+      valueDrift: diffValueDrift(
+        base.events.valueDrift ?? [],
+        head.events.valueDrift ?? [],
+      ).added,
+    },
+    services: { observedButUndocumented: introducedServices.added },
+    channels: { observedButUndocumented: introducedChannels.added },
+  };
+
+  const resolved: DriftEntries = {
+    events: {
+      observedButUndocumented: introducedEvents.removed,
+      documentedButUnseen: introducedMissing.removed,
+      fieldDrift: introducedFieldDrift.removed,
+      typeDrift: diffTypeDrift(
+        base.events.typeDrift ?? [],
+        head.events.typeDrift ?? [],
+      ).removed,
+      valueDrift: diffValueDrift(
+        base.events.valueDrift ?? [],
+        head.events.valueDrift ?? [],
+      ).removed,
+    },
+    services: { observedButUndocumented: introducedServices.removed },
+    channels: { observedButUndocumented: introducedChannels.removed },
+  };
+
+  const hasNewDrift =
+    introduced.events.observedButUndocumented.length > 0 ||
+    introduced.events.documentedButUnseen.length > 0 ||
+    introduced.events.fieldDrift.length > 0 ||
+    introduced.events.typeDrift.length > 0 ||
+    introduced.events.valueDrift.length > 0 ||
+    introduced.services.observedButUndocumented.length > 0 ||
+    introduced.channels.observedButUndocumented.length > 0;
+
+  return { introduced, resolved, hasNewDrift };
+}
+
+/**
+ * Per-category counts for one side of a DriftDelta (introduced or resolved).
+ * Same shape as DriftCounts so dashboards and CI can render the
+ * introduced/resolved sections with identical accounting.
+ */
+export function countDriftEntries(entries: DriftEntries): DriftCounts {
+  const fieldDriftEvents = entries.events.fieldDrift.length;
+  const fieldDriftPaths = entries.events.fieldDrift.reduce(
+    (sum, fd) => sum + fd.extra.length + fd.missing.length,
+    0,
+  );
+  const observedButUndocumentedEvents =
+    entries.events.observedButUndocumented.length;
+  const documentedButUnseenEvents = entries.events.documentedButUnseen.length;
+  const undocumentedServices = entries.services.observedButUndocumented.length;
+  const undocumentedChannels = entries.channels.observedButUndocumented.length;
+  const typeDriftPaths = (entries.events.typeDrift ?? []).length;
+  const valueDriftPaths = (entries.events.valueDrift ?? []).length;
+
+  return {
+    observedButUndocumentedEvents,
+    documentedButUnseenEvents,
+    fieldDriftEvents,
+    fieldDriftPaths,
+    typeDriftPaths,
+    valueDriftPaths,
+    undocumentedServices,
+    undocumentedChannels,
+    total:
+      observedButUndocumentedEvents +
+      documentedButUnseenEvents +
+      fieldDriftPaths +
+      typeDriftPaths +
+      valueDriftPaths +
+      undocumentedServices +
+      undocumentedChannels,
+  };
+}
+
+export function countDriftDelta(delta: DriftDelta): {
+  introduced: DriftCounts;
+  resolved: DriftCounts;
+} {
+  return {
+    introduced: countDriftEntries(delta.introduced),
+    resolved: countDriftEntries(delta.resolved),
+  };
+}
+
+function diffStringList(
+  base: string[],
+  head: string[],
+): { added: string[]; removed: string[] } {
+  const baseSet = new Set(base);
+  const headSet = new Set(head);
+  return {
+    added: head.filter((s) => !baseSet.has(s)).sort(),
+    removed: base.filter((s) => !headSet.has(s)).sort(),
+  };
+}
+
+function diffFieldDrift(
+  base: FieldDrift[],
+  head: FieldDrift[],
+): { added: FieldDrift[]; removed: FieldDrift[] } {
+  const baseByEvent = new Map(base.map((d) => [d.event, d]));
+  const headByEvent = new Map(head.map((d) => [d.event, d]));
+
+  const added: FieldDrift[] = [];
+  const removed: FieldDrift[] = [];
+
+  for (const [event, h] of headByEvent) {
+    const b = baseByEvent.get(event);
+    if (!b) {
+      // Entire event's field drift is new to head.
+      added.push(h);
+      continue;
+    }
+    const addedExtra = h.extra.filter((p) => !b.extra.includes(p));
+    const addedMissing = h.missing.filter((p) => !b.missing.includes(p));
+    if (addedExtra.length > 0 || addedMissing.length > 0) {
+      added.push({ event, extra: addedExtra, missing: addedMissing });
+    }
+  }
+
+  for (const [event, b] of baseByEvent) {
+    const h = headByEvent.get(event);
+    if (!h) {
+      removed.push(b);
+      continue;
+    }
+    const removedExtra = b.extra.filter((p) => !h.extra.includes(p));
+    const removedMissing = b.missing.filter((p) => !h.missing.includes(p));
+    if (removedExtra.length > 0 || removedMissing.length > 0) {
+      removed.push({ event, extra: removedExtra, missing: removedMissing });
+    }
+  }
+
+  return { added, removed };
+}
+
+function diffTypeDrift(
+  base: TypeDrift[],
+  head: TypeDrift[],
+): { added: TypeDrift[]; removed: TypeDrift[] } {
+  return diffStructuredByKey(base, head, (x) => `${x.event}::${x.path}`);
+}
+
+function diffValueDrift(
+  base: ValueDrift[],
+  head: ValueDrift[],
+): { added: ValueDrift[]; removed: ValueDrift[] } {
+  return diffStructuredByKey(base, head, (x) => `${x.event}::${x.path}`);
+}
+
+function diffStructuredByKey<T>(
+  base: T[],
+  head: T[],
+  keyOf: (v: T) => string,
+): { added: T[]; removed: T[] } {
+  const baseMap = new Map(base.map((v) => [keyOf(v), v]));
+  const headMap = new Map(head.map((v) => [keyOf(v), v]));
+  const added: T[] = [];
+  const removed: T[] = [];
+
+  for (const [k, hv] of headMap) {
+    const bv = baseMap.get(k);
+    if (!bv || JSON.stringify(bv) !== JSON.stringify(hv)) added.push(hv);
+  }
+  for (const [k, bv] of baseMap) {
+    const hv = headMap.get(k);
+    if (!hv || JSON.stringify(hv) !== JSON.stringify(bv)) removed.push(bv);
+  }
+  return { added, removed };
+}

package/src/diff.test.ts

@@ -0,0 +1,384 @@
+import { describe, it, expect } from 'vitest';
+import { diffCatalogAgainstSnapshot, hasDrift, countDriftReport } from './diff';
+import type { ArchitectureSnapshot } from './snapshot';
+import type { CatalogState } from './catalog';
+
+function snap(events: ArchitectureSnapshot['events']): ArchitectureSnapshot {
+  return {
+    spec: 'autotel-architecture/v0.1.0',
+    generatedAt: '2026-05-21T18:04:00.000Z',
+    service: 'example-eventcatalog',
+    events,
+  };
+}
+
+function catalog(opts: {
+  events?: Array<{
+    id: string;
+    declaredFieldPaths?: string[];
+    declaredSchemaConstraints?: Record<
+      string,
+      { types?: string[]; enumValues?: unknown[] }
+    >;
+  }>;
+  services?: string[];
+  channels?: string[];
+}): CatalogState {
+  return {
+    events: new Map(
+      (opts.events ?? []).map((e) => [
+        e.id,
+        {
+          id: e.id,
+          filePath: `mock/${e.id}.mdx`,
+          declaredFieldPaths: e.declaredFieldPaths,
+          declaredSchemaConstraints: e.declaredSchemaConstraints,
+        },
+      ]),
+    ),
+    services: new Map(
+      (opts.services ?? []).map((id) => [
+        id,
+        { id, filePath: `mock/${id}.mdx` },
+      ]),
+    ),
+    channels: new Map(
+      (opts.channels ?? []).map((id) => [
+        id,
+        { id, filePath: `mock/${id}.mdx` },
+      ]),
+    ),
+  };
+}
+
+const baseObservation = {
+  observedCount: 5,
+  firstSeen: '2026-05-21T18:00:00.000Z',
+  lastSeen: '2026-05-21T18:04:00.000Z',
+  sampleTraceIds: [],
+};
+
+describe('diffCatalogAgainstSnapshot — event existence', () => {
+  it('matches dotted snapshot names to PascalCase catalog ids', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: ['orderId'],
+        },
+      }),
+      catalog({ events: [{ id: 'OrderPlaced' }] }),
+    );
+
+    expect(report.events.observedButUndocumented).toEqual([]);
+    expect(report.events.documentedButUnseen).toEqual([]);
+  });
+
+  it('reports events in the snapshot that have no catalog entry', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: [],
+        },
+        'order.cancelled': {
+          ...baseObservation,
+          name: 'order.cancelled',
+          fieldPaths: [],
+        },
+      }),
+      catalog({ events: [{ id: 'OrderPlaced' }] }),
+    );
+
+    expect(report.events.observedButUndocumented).toEqual(['order.cancelled']);
+  });
+
+  it('reports catalog entries that the snapshot never observed', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: [],
+        },
+      }),
+      catalog({ events: [{ id: 'OrderPlaced' }, { id: 'PaymentCaptured' }] }),
+    );
+
+    expect(report.events.documentedButUnseen).toEqual(['PaymentCaptured']);
+  });
+});
+
+describe('diffCatalogAgainstSnapshot — field drift', () => {
+  it('reports extra field paths in the observed payload', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'recommendation.generated': {
+          ...baseObservation,
+          name: 'recommendation.generated',
+          fieldPaths: ['orderId', 'model', 'personalization_seed'],
+        },
+      }),
+      catalog({
+        events: [
+          {
+            id: 'RecommendationGenerated',
+            declaredFieldPaths: ['orderId', 'model'],
+          },
+        ],
+      }),
+    );
+
+    expect(report.events.fieldDrift).toEqual([
+      {
+        event: 'recommendation.generated',
+        extra: ['personalization_seed'],
+        missing: [],
+      },
+    ]);
+  });
+
+  it('reports declared field paths that were never observed', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: ['orderId'],
+        },
+      }),
+      catalog({
+        events: [
+          {
+            id: 'OrderPlaced',
+            declaredFieldPaths: ['orderId', 'customerId', 'totalCents'],
+          },
+        ],
+      }),
+    );
+
+    expect(report.events.fieldDrift).toEqual([
+      {
+        event: 'order.placed',
+        extra: [],
+        missing: ['customerId', 'totalCents'],
+      },
+    ]);
+  });
+
+  it('skips events without a declared schema', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: ['orderId', 'extra'],
+        },
+      }),
+      catalog({ events: [{ id: 'OrderPlaced' }] }),
+    );
+
+    expect(report.events.fieldDrift).toEqual([]);
+  });
+});
+
+describe('diffCatalogAgainstSnapshot — type/value drift', () => {
+  it('reports type drift and enum value drift against declared schema constraints', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: ['amountCents', 'status'],
+          fieldStats: {
+            amountCents: {
+              types: ['string'],
+              sampleValues: ['1299'],
+            },
+            status: {
+              types: ['string'],
+              sampleValues: ['placed'],
+            },
+          },
+        },
+      }),
+      catalog({
+        events: [
+          {
+            id: 'OrderPlaced',
+            declaredFieldPaths: ['amountCents', 'status'],
+            declaredSchemaConstraints: {
+              amountCents: { types: ['number'] },
+              status: { types: ['string'], enumValues: ['pending', 'paid'] },
+            },
+          },
+        ],
+      }),
+    );
+
+    expect(report.events.typeDrift).toEqual([
+      {
+        event: 'order.placed',
+        path: 'amountCents',
+        declared: ['number'],
+        observed: ['string'],
+      },
+    ]);
+    expect(report.events.valueDrift).toEqual([
+      {
+        event: 'order.placed',
+        path: 'status',
+        declared: ['pending', 'paid'],
+        observed: ['placed'],
+      },
+    ]);
+  });
+});
+
+describe('diffCatalogAgainstSnapshot — services and channels', () => {
+  it('reports producers that are not declared as services', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: [],
+          producer: 'OrdersService',
+        },
+        'payment.captured': {
+          ...baseObservation,
+          name: 'payment.captured',
+          fieldPaths: [],
+          producer: 'GhostService',
+        },
+      }),
+      catalog({
+        events: [{ id: 'OrderPlaced' }, { id: 'PaymentCaptured' }],
+        services: ['OrdersService'],
+      }),
+    );
+
+    expect(report.services.observedButUndocumented).toEqual(['GhostService']);
+  });
+
+  it('reports channels that are not declared in the catalog', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'order.placed': {
+          ...baseObservation,
+          name: 'order.placed',
+          fieldPaths: [],
+          channel: 'orders.events',
+        },
+        'payment.captured': {
+          ...baseObservation,
+          name: 'payment.captured',
+          fieldPaths: [],
+          channel: 'rogue.events',
+        },
+      }),
+      catalog({
+        events: [{ id: 'OrderPlaced' }, { id: 'PaymentCaptured' }],
+        channels: ['orders.events'],
+      }),
+    );
+
+    expect(report.channels.observedButUndocumented).toEqual(['rogue.events']);
+  });
+});
+
+describe('hasDrift', () => {
+  it('returns false when every category is empty', () => {
+    const report = diffCatalogAgainstSnapshot(snap({}), catalog({}));
+    expect(hasDrift(report)).toBe(false);
+  });
+
+  it('returns true when any category has drift', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'new.event': { ...baseObservation, name: 'new.event', fieldPaths: [] },
+      }),
+      catalog({}),
+    );
+    expect(hasDrift(report)).toBe(true);
+  });
+});
+
+describe('countDriftReport', () => {
+  it('zero everywhere on a clean report', () => {
+    const c = countDriftReport(
+      diffCatalogAgainstSnapshot(snap({}), catalog({})),
+    );
+    expect(c.total).toBe(0);
+    expect(c.observedButUndocumentedEvents).toBe(0);
+    expect(c.documentedButUnseenEvents).toBe(0);
+    expect(c.fieldDriftEvents).toBe(0);
+    expect(c.fieldDriftPaths).toBe(0);
+    expect(c.undocumentedServices).toBe(0);
+    expect(c.undocumentedChannels).toBe(0);
+  });
+
+  it('distinguishes fieldDrift events from fieldDrift paths', () => {
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'recommendation.generated': {
+          ...baseObservation,
+          name: 'recommendation.generated',
+          fieldPaths: ['a', 'b', 'c'],
+        },
+      }),
+      catalog({
+        events: [
+          {
+            id: 'RecommendationGenerated',
+            declaredFieldPaths: ['a', 'd'], // observed: a,b,c → extras b,c; declared: a,d → missing d
+          },
+        ],
+      }),
+    );
+    const c = countDriftReport(report);
+    expect(c.fieldDriftEvents).toBe(1); // one event with drift
+    expect(c.fieldDriftPaths).toBe(3); // b extra + c extra + d missing
+    expect(c.total).toBe(3); // only field drift contributes
+  });
+
+  it('total matches the dashboard `countDrift` semantics', () => {
+    // Hand-build a report with one item in every category so total has
+    // an unambiguous expected value.
+    const report = diffCatalogAgainstSnapshot(
+      snap({
+        'a.new': {
+          ...baseObservation,
+          name: 'a.new',
+          fieldPaths: ['x'],
+          producer: 'NewService',
+          channel: 'new.events',
+        },
+        'b.match': {
+          ...baseObservation,
+          name: 'b.match',
+          fieldPaths: ['z', 'q'],
+        },
+      }),
+      catalog({
+        events: [
+          { id: 'BMatch', declaredFieldPaths: ['z', 'p'] }, // extra q, missing p
+          { id: 'LegacyEvent' }, // documented but unseen
+        ],
+        services: [],
+        channels: [],
+      }),
+    );
+    const c = countDriftReport(report);
+    // 1 observed-but-undoc (a.new) + 1 doc-but-unseen (LegacyEvent)
+    //   + 2 field paths (q extra, p missing) + 1 service + 1 channel
+    expect(c.total).toBe(6);
+    expect(c.observedButUndocumentedEvents).toBe(1);
+    expect(c.documentedButUnseenEvents).toBe(1);
+    expect(c.fieldDriftPaths).toBe(2);
+    expect(c.undocumentedServices).toBe(1);
+    expect(c.undocumentedChannels).toBe(1);
+  });
+});