autotel-eventcatalog 1.0.0

package/src/renderers/markdown.ts

@@ -0,0 +1,223 @@
+// GitHub-flavoured Markdown — the default. Used directly as the body of
+// the sticky PR comment posted by the bundled action.
+
+import type { DriftReport, FieldDrift } from '../diff';
+import { hasDrift } from '../diff';
+import type { DriftDelta, DriftEntries } from '../diff-vs-base';
+import type { Renderer } from './types';
+
+export function renderMarkdown(report: DriftReport): string {
+  const lines: string[] = [
+    '# Architecture drift report',
+    '',
+    `_Snapshot from \`${report.snapshotService}\` at ${report.snapshotGeneratedAt}_`,
+    '',
+  ];
+
+  if (!hasDrift(report)) {
+    lines.push('No drift detected. Catalog and runtime agree.', '');
+    return lines.join('\n');
+  }
+
+  if (report.events.observedButUndocumented.length > 0) {
+    lines.push(
+      '## Events observed but undocumented',
+      '',
+      'These event names appear in the snapshot but no matching entry',
+      'exists in the catalog. Add them or stop emitting them.',
+      '',
+    );
+    for (const name of report.events.observedButUndocumented) {
+      lines.push(`- \`${name}\``);
+    }
+    lines.push('');
+  }
+
+  if (report.events.documentedButUnseen.length > 0) {
+    lines.push(
+      '## Events documented but never observed',
+      '',
+      'These events exist in the catalog but no payload was captured.',
+      'Either the tests do not exercise this event, or it has been removed.',
+      '',
+    );
+    for (const name of report.events.documentedButUnseen) {
+      lines.push(`- \`${name}\``);
+    }
+    lines.push('');
+  }
+
+  if (report.events.fieldDrift.length > 0) {
+    lines.push('## Field-path drift', '');
+    for (const drift of report.events.fieldDrift) {
+      lines.push(`### \`${drift.event}\``, '');
+      if (drift.extra.length > 0) {
+        lines.push(
+          '**Extra fields in payloads (not in declared schema):**',
+          '',
+        );
+        for (const p of drift.extra) lines.push(`- \`${p}\``);
+        lines.push('');
+      }
+      if (drift.missing.length > 0) {
+        lines.push('**Fields declared but never observed:**', '');
+        for (const p of drift.missing) lines.push(`- \`${p}\``);
+        lines.push('');
+      }
+    }
+  }
+
+  if ((report.events.typeDrift ?? []).length > 0) {
+    lines.push('## Type drift', '');
+    for (const drift of report.events.typeDrift ?? []) {
+      lines.push(
+        `- \`${drift.event}\` \`${drift.path}\``,
+        `  declared: \`${drift.declared.join(' | ')}\`, observed: \`${drift.observed.join(' | ')}\``,
+      );
+    }
+    lines.push('');
+  }
+
+  if ((report.events.valueDrift ?? []).length > 0) {
+    lines.push('## Value drift', '');
+    for (const drift of report.events.valueDrift ?? []) {
+      lines.push(
+        `- \`${drift.event}\` \`${drift.path}\``,
+        `  declared enum: \`${drift.declared.map((v) => JSON.stringify(v)).join(', ')}\`, observed: \`${drift.observed.map((v) => JSON.stringify(v)).join(', ')}\``,
+      );
+    }
+    lines.push('');
+  }
+
+  if (report.services.observedButUndocumented.length > 0) {
+    lines.push('## Services observed but undocumented', '');
+    for (const id of report.services.observedButUndocumented) {
+      lines.push(`- \`${id}\``);
+    }
+    lines.push('');
+  }
+
+  if (report.channels.observedButUndocumented.length > 0) {
+    lines.push('## Channels observed but undocumented', '');
+    for (const id of report.channels.observedButUndocumented) {
+      lines.push(`- \`${id}\``);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Render the diff-of-diffs as a PR-comment-friendly markdown block. Sections
+ * appear only when they have content, so a clean PR produces a tight message.
+ */
+export function renderDeltaMarkdown(delta: DriftDelta): string {
+  const lines: string[] = [
+    '# Architecture drift — what this change introduces',
+    '',
+  ];
+
+  if (!delta.hasNewDrift) {
+    const fixedAny = entriesHasContent(delta.resolved);
+    if (fixedAny) {
+      lines.push('No new drift. The changes below resolve existing drift:', '');
+      renderEntries(delta.resolved, lines, { sign: '−' });
+    } else {
+      lines.push('No new drift detected. Catalog and runtime agree.');
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('This change introduces drift:', '');
+  renderEntries(delta.introduced, lines, { sign: '+' });
+
+  if (entriesHasContent(delta.resolved)) {
+    lines.push('', '### Resolved by this change', '');
+    renderEntries(delta.resolved, lines, { sign: '−' });
+  }
+
+  return lines.join('\n');
+}
+
+function entriesHasContent(e: DriftEntries): boolean {
+  return (
+    e.events.observedButUndocumented.length > 0 ||
+    e.events.documentedButUnseen.length > 0 ||
+    e.events.fieldDrift.length > 0 ||
+    (e.events.typeDrift ?? []).length > 0 ||
+    (e.events.valueDrift ?? []).length > 0 ||
+    e.services.observedButUndocumented.length > 0 ||
+    e.channels.observedButUndocumented.length > 0
+  );
+}
+
+function renderEntries(
+  entries: DriftEntries,
+  out: string[],
+  options: { sign: '+' | '−' },
+): void {
+  if (entries.events.observedButUndocumented.length > 0) {
+    out.push('**Events observed but undocumented**', '');
+    for (const n of entries.events.observedButUndocumented) {
+      out.push(`- \`${n}\``);
+    }
+    out.push('');
+  }
+  if (entries.events.documentedButUnseen.length > 0) {
+    out.push('**Events documented but never observed**', '');
+    for (const n of entries.events.documentedButUnseen) {
+      out.push(`- \`${n}\``);
+    }
+    out.push('');
+  }
+  for (const fd of entries.events.fieldDrift) {
+    out.push(`**Field drift on \`${fd.event}\`**`, '');
+    for (const p of fd.extra) out.push(`- ${options.sign} \`${p}\` (extra)`);
+    for (const p of fd.missing)
+      out.push(`- ${options.sign} \`${p}\` (missing)`);
+    out.push('');
+  }
+  for (const td of entries.events.typeDrift ?? []) {
+    out.push(
+      `**Type drift on \`${td.event}\` \`${td.path}\`**`,
+      '',
+      `- ${options.sign} declared \`${td.declared.join(' | ')}\`, observed \`${td.observed.join(' | ')}\``,
+      '',
+    );
+  }
+  for (const vd of entries.events.valueDrift ?? []) {
+    out.push(
+      `**Value drift on \`${vd.event}\` \`${vd.path}\`**`,
+      '',
+      `- ${options.sign} declared enum \`${vd.declared.map((v) => JSON.stringify(v)).join(', ')}\`, observed \`${vd.observed.map((v) => JSON.stringify(v)).join(', ')}\``,
+      '',
+    );
+  }
+  if (entries.services.observedButUndocumented.length > 0) {
+    out.push('**Services observed but undocumented**', '');
+    for (const id of entries.services.observedButUndocumented) {
+      out.push(`- \`${id}\``);
+    }
+    out.push('');
+  }
+  if (entries.channels.observedButUndocumented.length > 0) {
+    out.push('**Channels observed but undocumented**', '');
+    for (const id of entries.channels.observedButUndocumented) {
+      out.push(`- \`${id}\``);
+    }
+    out.push('');
+  }
+  // FieldDrift import kept for typing of the for..of above; reference here so
+  // the import isn't flagged as unused by some linter configurations.
+  void (null as unknown as FieldDrift);
+}
+
+export const markdownRenderer: Renderer = {
+  name: 'markdown',
+  description:
+    'GitHub-flavoured Markdown (default). Suitable for sticky PR comments.',
+  renderReport: renderMarkdown,
+  renderDelta: renderDeltaMarkdown,
+};

package/src/renderers/renderers.test.ts

@@ -0,0 +1,79 @@
+// Tests for the renderer registry (the adapter shape). Per-renderer
+// behavioural tests live in ../report.test.ts.
+
+import { describe, it, expect } from 'vitest';
+import { RENDERERS, RENDERER_NAMES, getRenderer } from './index';
+import type { DriftReport } from '../diff';
+import type { DriftDelta } from '../diff-vs-base';
+
+const emptyReport: DriftReport = {
+  snapshotGeneratedAt: '2026-05-22T00:00:00.000Z',
+  snapshotService: 'fixture',
+  events: {
+    observedButUndocumented: [],
+    documentedButUnseen: [],
+    fieldDrift: [],
+  },
+  services: { observedButUndocumented: [] },
+  channels: { observedButUndocumented: [] },
+};
+
+const cleanDelta: DriftDelta = {
+  hasNewDrift: false,
+  introduced: emptyReport.events && {
+    events: {
+      observedButUndocumented: [],
+      documentedButUnseen: [],
+      fieldDrift: [],
+    },
+    services: { observedButUndocumented: [] },
+    channels: { observedButUndocumented: [] },
+  },
+  resolved: {
+    events: {
+      observedButUndocumented: [],
+      documentedButUnseen: [],
+      fieldDrift: [],
+    },
+    services: { observedButUndocumented: [] },
+    channels: { observedButUndocumented: [] },
+  },
+};
+
+describe('renderer registry', () => {
+  it('ships at least the three built-in renderers', () => {
+    expect(RENDERER_NAMES).toEqual(
+      expect.arrayContaining(['markdown', 'terminal', 'json']),
+    );
+  });
+
+  it('every renderer has a name, description, and both render functions', () => {
+    for (const r of RENDERERS) {
+      expect(typeof r.name).toBe('string');
+      expect(r.name.length).toBeGreaterThan(0);
+      expect(typeof r.description).toBe('string');
+      expect(typeof r.renderReport).toBe('function');
+      expect(typeof r.renderDelta).toBe('function');
+    }
+  });
+
+  it('every renderer produces a non-empty string for both shapes', () => {
+    for (const r of RENDERERS) {
+      const reportOutput = r.renderReport(emptyReport);
+      const deltaOutput = r.renderDelta(cleanDelta);
+      expect(reportOutput.length).toBeGreaterThan(0);
+      expect(deltaOutput.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('getRenderer looks up by name', () => {
+    expect(getRenderer('markdown')?.name).toBe('markdown');
+    expect(getRenderer('json')?.name).toBe('json');
+    expect(getRenderer('terminal')?.name).toBe('terminal');
+  });
+
+  it('getRenderer returns undefined for unknown names', () => {
+    expect(getRenderer('sarif')).toBeUndefined();
+    expect(getRenderer('')).toBeUndefined();
+  });
+});

package/src/renderers/terminal.ts

@@ -0,0 +1,30 @@
+// Plain-text rendering — for terminals, log files, Slack messages, anywhere
+// markdown decorations would render as noise. Reuses the markdown renderer
+// and strips heading marks, inline code backticks, and bold emphasis.
+
+import type { DriftReport } from '../diff';
+import type { DriftDelta } from '../diff-vs-base';
+import { renderMarkdown, renderDeltaMarkdown } from './markdown';
+import type { Renderer } from './types';
+
+export function renderTerminal(report: DriftReport): string {
+  return stripMarkdownDecorations(renderMarkdown(report));
+}
+
+export function renderDeltaTerminal(delta: DriftDelta): string {
+  return stripMarkdownDecorations(renderDeltaMarkdown(delta));
+}
+
+function stripMarkdownDecorations(md: string): string {
+  return md
+    .replaceAll(/^#+\s+/gm, '')
+    .replaceAll('`', '')
+    .replaceAll(/\*\*([^*]+)\*\*/g, '$1');
+}
+
+export const terminalRenderer: Renderer = {
+  name: 'terminal',
+  description: 'Plain text. Same content as markdown, decorations stripped.',
+  renderReport: renderTerminal,
+  renderDelta: renderDeltaTerminal,
+};

package/src/renderers/types.ts

@@ -0,0 +1,26 @@
+// Renderers are pluggable adapters that turn a drift result into output text.
+// The core domain (diff / diff-vs-base / policy) is renderer-agnostic; new
+// output targets (SARIF, GitHub Check Runs API, Slack-flavoured markdown) plug
+// in here without touching the core.
+//
+// Two render shapes:
+//   - `RenderReport`   for full reports (mode === 'all')
+//   - `RenderDelta`    for diff-of-diffs (mode === 'new-only')
+//
+// A `Renderer` implements both — most renderers can share helpers between the
+// two — so the registry can dispatch by `(mode, format)` without branches.
+
+import type { DriftReport } from '../diff';
+import type { DriftDelta } from '../diff-vs-base';
+
+export type RenderReport = (report: DriftReport) => string;
+export type RenderDelta = (delta: DriftDelta) => string;
+
+export interface Renderer {
+  /** Short name used by the CLI's `--format` flag. */
+  readonly name: string;
+  /** One-line human description shown in CLI help and the README. */
+  readonly description: string;
+  readonly renderReport: RenderReport;
+  readonly renderDelta: RenderDelta;
+}

package/src/report.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect } from 'vitest';
+import {
+  renderMarkdown,
+  renderJson,
+  renderTerminal,
+  renderDeltaTerminal,
+  REPORT_SPEC,
+} from './report';
+import type { DriftReport } from './diff';
+import type { DriftDelta } from './diff-vs-base';
+
+const emptyReport: DriftReport = {
+  snapshotGeneratedAt: '2026-05-21T18:04:00.000Z',
+  snapshotService: 'orders',
+  events: {
+    observedButUndocumented: [],
+    documentedButUnseen: [],
+    fieldDrift: [],
+  },
+  services: { observedButUndocumented: [] },
+  channels: { observedButUndocumented: [] },
+};
+
+describe('renderMarkdown', () => {
+  it('renders a clean report when there is no drift', () => {
+    const md = renderMarkdown(emptyReport);
+    expect(md).toContain('No drift detected');
+    expect(md).toContain('orders');
+    expect(md).toContain('2026-05-21T18:04:00.000Z');
+  });
+
+  it('renders each drift section under a clear heading', () => {
+    const md = renderMarkdown({
+      ...emptyReport,
+      events: {
+        observedButUndocumented: ['order.cancelled'],
+        documentedButUnseen: ['LegacyEvent'],
+        fieldDrift: [
+          {
+            event: 'recommendation.generated',
+            extra: ['personalization_seed'],
+            missing: ['recommendations[].reason'],
+          },
+        ],
+      },
+      services: { observedButUndocumented: ['GhostService'] },
+      channels: { observedButUndocumented: ['rogue.events'] },
+    });
+
+    expect(md).toContain('## Events observed but undocumented');
+    expect(md).toContain('`order.cancelled`');
+    expect(md).toContain('## Events documented but never observed');
+    expect(md).toContain('`LegacyEvent`');
+    expect(md).toContain('## Field-path drift');
+    expect(md).toContain('### `recommendation.generated`');
+    expect(md).toContain('`personalization_seed`');
+    expect(md).toContain('`recommendations[].reason`');
+    expect(md).toContain('## Services observed but undocumented');
+    expect(md).toContain('`GhostService`');
+    expect(md).toContain('## Channels observed but undocumented');
+    expect(md).toContain('`rogue.events`');
+  });
+});
+
+describe('renderJson', () => {
+  it('renders a machine-readable all-mode payload', () => {
+    const json = renderJson({ mode: 'all', report: emptyReport });
+    const parsed = JSON.parse(json) as {
+      spec: string;
+      mode: string;
+      report: DriftReport;
+    };
+    expect(parsed.spec).toBe(REPORT_SPEC);
+    expect(parsed.mode).toBe('all');
+    expect(parsed.report.snapshotService).toBe('orders');
+  });
+
+  it('stamps the spec marker on every envelope shape', () => {
+    const allJson = JSON.parse(
+      renderJson({ mode: 'all', report: emptyReport }),
+    );
+    const deltaJson = JSON.parse(
+      renderJson({
+        mode: 'new-only',
+        delta: {
+          hasNewDrift: false,
+          introduced: {
+            events: {
+              observedButUndocumented: [],
+              documentedButUnseen: [],
+              fieldDrift: [],
+            },
+            services: { observedButUndocumented: [] },
+            channels: { observedButUndocumented: [] },
+          },
+          resolved: {
+            events: {
+              observedButUndocumented: [],
+              documentedButUnseen: [],
+              fieldDrift: [],
+            },
+            services: { observedButUndocumented: [] },
+            channels: { observedButUndocumented: [] },
+          },
+        },
+      }),
+    );
+    expect(allJson.spec).toBe(REPORT_SPEC);
+    expect(deltaJson.spec).toBe(REPORT_SPEC);
+  });
+});
+
+const driftyReport: DriftReport = {
+  ...emptyReport,
+  events: {
+    observedButUndocumented: ['order.cancelled'],
+    documentedButUnseen: ['LegacyEvent'],
+    fieldDrift: [
+      {
+        event: 'recommendation.generated',
+        extra: ['personalization_seed'],
+        missing: ['recommendations[].reason'],
+      },
+    ],
+  },
+};
+
+describe('renderTerminal', () => {
+  it('preserves structure but strips markdown decorations', () => {
+    const text = renderTerminal(driftyReport);
+    // Section heads survive, but the leading '#' marks are gone.
+    expect(text).not.toMatch(/^#/m);
+    expect(text).toContain('Events observed but undocumented');
+    expect(text).toContain('Field-path drift');
+    // No backticks around event/field names.
+    expect(text).not.toContain('`order.cancelled`');
+    expect(text).toContain('order.cancelled');
+    expect(text).toContain('personalization_seed');
+    // No ** bold marks.
+    expect(text).not.toMatch(/\*\*/);
+  });
+
+  it('renders cleanly when there is no drift', () => {
+    const text = renderTerminal(emptyReport);
+    expect(text).toContain('No drift detected');
+    expect(text).not.toContain('#');
+    expect(text).not.toMatch(/\*\*/);
+  });
+});
+
+describe('renderDeltaTerminal', () => {
+  const noNewDrift: DriftDelta = {
+    hasNewDrift: false,
+    introduced: {
+      events: {
+        observedButUndocumented: [],
+        documentedButUnseen: [],
+        fieldDrift: [],
+      },
+      services: { observedButUndocumented: [] },
+      channels: { observedButUndocumented: [] },
+    },
+    resolved: {
+      events: {
+        observedButUndocumented: [],
+        documentedButUnseen: [],
+        fieldDrift: [],
+      },
+      services: { observedButUndocumented: [] },
+      channels: { observedButUndocumented: [] },
+    },
+  };
+  const newDrift: DriftDelta = {
+    hasNewDrift: true,
+    introduced: {
+      events: {
+        observedButUndocumented: ['order.cancelled'],
+        documentedButUnseen: [],
+        fieldDrift: [],
+      },
+      services: { observedButUndocumented: [] },
+      channels: { observedButUndocumented: [] },
+    },
+    resolved: {
+      events: {
+        observedButUndocumented: [],
+        documentedButUnseen: [],
+        fieldDrift: [],
+      },
+      services: { observedButUndocumented: [] },
+      channels: { observedButUndocumented: [] },
+    },
+  };
+
+  it('strips markdown for delta-style output', () => {
+    const text = renderDeltaTerminal(newDrift);
+    expect(text).toContain('order.cancelled');
+    expect(text).not.toMatch(/\*\*|`|^#/m);
+  });
+
+  it('renders cleanly when there is no new drift', () => {
+    const text = renderDeltaTerminal(noNewDrift);
+    expect(text).toContain('No new drift detected');
+  });
+});

package/src/report.ts

@@ -0,0 +1,27 @@
+// Backwards-compatible re-export of the renderer surface.
+//
+// The actual implementations live in `./renderers/<name>.ts` — see the
+// Renderer adapter pattern there. This module exists so any consumer (or
+// internal test) that imports from `'./report'` continues to work.
+//
+// New renderers should be added under `./renderers/` and registered in
+// `./renderers/index.ts`; do not add new exports here.
+
+export {
+  renderMarkdown,
+  renderDeltaMarkdown,
+  renderTerminal,
+  renderDeltaTerminal,
+  renderJson,
+  REPORT_SPEC,
+  RENDERERS,
+  RENDERER_NAMES,
+  getRenderer,
+} from './renderers/index';
+
+export type {
+  Renderer,
+  RendererName,
+  JsonReport,
+  JsonReportEnvelope,
+} from './renderers/index';

package/src/snapshot.ts

@@ -0,0 +1,25 @@
+// Re-export the snapshot types from autotel-subscribers and provide a
+// convenience loader. Keeping the types defined in one place makes the
+// contract between subscriber and generator unambiguous.
+
+import { readFile } from 'node:fs/promises';
+
+export type {
+  ArchitectureSnapshot,
+  EventObservation,
+} from 'autotel-subscribers/architecture-snapshot';
+
+import type { ArchitectureSnapshot } from 'autotel-subscribers/architecture-snapshot';
+
+export async function loadSnapshot(
+  path: string,
+): Promise<ArchitectureSnapshot> {
+  const raw = await readFile(path, 'utf8');
+  const parsed = JSON.parse(raw) as ArchitectureSnapshot;
+  if (!parsed?.spec?.startsWith('autotel-architecture/')) {
+    throw new Error(
+      `Not an autotel architecture snapshot (missing spec marker): ${path}`,
+    );
+  }
+  return parsed;
+}