autotel-eventcatalog 1.0.0

package/src/stamp.test.ts

@@ -0,0 +1,283 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  stampCatalog,
+  buildStampBlock,
+  buildStampSummary,
+  STAMP_START,
+  STAMP_END,
+  STAMP_SUMMARY_SPEC,
+} from './stamp';
+import type { ArchitectureSnapshot, EventObservation } from './snapshot';
+
+function obs(overrides: Partial<EventObservation> = {}): EventObservation {
+  return {
+    name: 'order.placed',
+    observedCount: 12,
+    firstSeen: '2026-05-22T05:20:00.000Z',
+    lastSeen: '2026-05-22T05:23:50.024Z',
+    fieldPaths: ['orderId', 'customerId', 'items[].sku'],
+    sampleTraceIds: [],
+    producer: 'OrdersService',
+    channel: 'orders.events',
+    ...overrides,
+  };
+}
+
+function snap(events: ArchitectureSnapshot['events']): ArchitectureSnapshot {
+  return {
+    spec: 'autotel-architecture/v0.1.0',
+    generatedAt: '2026-05-22T05:24:00.000Z',
+    service: 'example',
+    events,
+  };
+}
+
+describe('buildStampBlock', () => {
+  it('includes volume, last-seen, producer, channel', () => {
+    const b = buildStampBlock(obs());
+    expect(b).toContain(STAMP_START);
+    expect(b).toContain(STAMP_END);
+    expect(b).toContain('**Volume**: 12 events');
+    expect(b).toContain('**Last seen**: 2026-05-22 05:23 UTC');
+    expect(b).toContain('**Producer**: OrdersService');
+    expect(b).toContain('**Channel**: `orders.events`');
+  });
+
+  it('lists field paths as inline code', () => {
+    const b = buildStampBlock(obs({ fieldPaths: ['a', 'b.c'] }));
+    expect(b).toContain('`a`, `b.c`');
+  });
+
+  it('omits sample-traces section when none observed', () => {
+    const b = buildStampBlock(obs({ sampleTraceIds: [] }));
+    expect(b).not.toContain('Sample traces');
+  });
+
+  it('includes sample-traces section when present', () => {
+    const b = buildStampBlock(obs({ sampleTraceIds: ['t1', 't2'] }));
+    expect(b).toContain('**Sample traces**: `t1`, `t2`');
+  });
+});
+
+describe('stampCatalog', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'autotel-stamp-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  async function writeEventFile(
+    catalogId: string,
+    body: string,
+  ): Promise<string> {
+    const evDir = join(
+      dir,
+      'domains',
+      'X',
+      'services',
+      'S',
+      'events',
+      catalogId,
+    );
+    await mkdir(evDir, { recursive: true });
+    const file = join(evDir, 'index.mdx');
+    const frontmatter = `---\nid: ${catalogId}\nversion: 1.0.0\n---\n\n`;
+    await writeFile(file, frontmatter + body, 'utf8');
+    return file;
+  }
+
+  it('inserts a stamp block before <Footer /> on first run', async () => {
+    const file = await writeEventFile(
+      'OrderPlaced',
+      '## Overview\n\nA description.\n\n<Footer />\n',
+    );
+
+    const result = await stampCatalog({
+      snapshot: snap({ 'order.placed': obs() }),
+      catalogPath: dir,
+    });
+
+    expect(result.updates).toHaveLength(1);
+    expect(result.updates[0]).toMatchObject({
+      catalogId: 'OrderPlaced',
+      action: 'insert',
+    });
+
+    const content = await readFile(file, 'utf8');
+    expect(content).toContain(STAMP_START);
+    expect(content).toContain('**Volume**: 12 events');
+    // Stamp should come before <Footer />
+    expect(content.indexOf(STAMP_START)).toBeLessThan(
+      content.indexOf('<Footer />'),
+    );
+  });
+
+  it('replaces the content between markers on subsequent runs', async () => {
+    const file = await writeEventFile(
+      'OrderPlaced',
+      `## Overview\n\n${STAMP_START}\n\n<div>old block</div>\n\n${STAMP_END}\n\n<Footer />\n`,
+    );
+
+    const result = await stampCatalog({
+      snapshot: snap({ 'order.placed': obs({ observedCount: 999 }) }),
+      catalogPath: dir,
+    });
+
+    expect(result.updates[0].action).toBe('replace');
+    const content = await readFile(file, 'utf8');
+    expect(content).not.toContain('old block');
+    expect(content).toContain('**Volume**: 999 events');
+    expect(content.match(new RegExp(STAMP_START, 'g'))!).toHaveLength(1);
+  });
+
+  it('skips events that have no matching catalog entry', async () => {
+    await writeEventFile('OrderPlaced', '## Overview\n\n<Footer />\n');
+
+    const result = await stampCatalog({
+      snapshot: snap({
+        'order.placed': obs(),
+        'mystery.event': obs({ name: 'mystery.event' }),
+      }),
+      catalogPath: dir,
+    });
+
+    expect(result.updates).toHaveLength(1);
+    expect(result.skips).toHaveLength(1);
+    expect(result.skips[0]).toMatchObject({
+      snapshotName: 'mystery.event',
+      reason: 'no-catalog-match',
+    });
+  });
+
+  it('appends at file end when no <Footer /> is present', async () => {
+    const file = await writeEventFile(
+      'OrderPlaced',
+      '## Overview\n\nJust prose, no footer.\n',
+    );
+
+    await stampCatalog({
+      snapshot: snap({ 'order.placed': obs() }),
+      catalogPath: dir,
+    });
+
+    const content = await readFile(file, 'utf8');
+    expect(content).toContain(STAMP_START);
+    expect(content).toContain('Just prose, no footer.');
+    expect(content.indexOf('Just prose, no footer.')).toBeLessThan(
+      content.indexOf(STAMP_START),
+    );
+  });
+
+  it('matches dotted snapshot names to PascalCase catalog ids', async () => {
+    await writeEventFile('OrderPlaced', '## o\n');
+    const result = await stampCatalog({
+      snapshot: snap({ 'order.placed': obs() }),
+      catalogPath: dir,
+    });
+    expect(result.updates[0]?.catalogId).toBe('OrderPlaced');
+  });
+
+  it('dryRun returns the plan without writing files', async () => {
+    const file = await writeEventFile('OrderPlaced', '## o\n');
+    const before = await readFile(file, 'utf8');
+
+    await stampCatalog({
+      snapshot: snap({ 'order.placed': obs() }),
+      catalogPath: dir,
+      dryRun: true,
+    });
+
+    const after = await readFile(file, 'utf8');
+    expect(after).toBe(before);
+  });
+
+  it('reports `changed: true` on the first stamp and `changed: false` on a no-op replace', async () => {
+    await writeEventFile('OrderPlaced', '## o\n\n<Footer />\n');
+    const fixedSnap = snap({ 'order.placed': obs({ observedCount: 100 }) });
+
+    const first = await stampCatalog({ snapshot: fixedSnap, catalogPath: dir });
+    expect(first.updates[0]).toMatchObject({ action: 'insert', changed: true });
+
+    // Re-running with the same data should be a no-op replace.
+    const second = await stampCatalog({
+      snapshot: fixedSnap,
+      catalogPath: dir,
+    });
+    expect(second.updates[0]).toMatchObject({
+      action: 'replace',
+      changed: false,
+    });
+  });
+});
+
+describe('buildStampSummary', () => {
+  it('rolls up inserts, replaces, skipped, and changed-files counts', () => {
+    const summary = buildStampSummary(
+      {
+        updates: [
+          {
+            catalogId: 'A',
+            snapshotName: 'a',
+            filePath: '/x/a.mdx',
+            action: 'insert',
+            changed: true,
+          },
+          {
+            catalogId: 'B',
+            snapshotName: 'b',
+            filePath: '/x/b.mdx',
+            action: 'replace',
+            changed: true,
+          },
+          {
+            catalogId: 'C',
+            snapshotName: 'c',
+            filePath: '/x/c.mdx',
+            action: 'replace',
+            changed: false,
+          },
+        ],
+        skips: [{ snapshotName: 'mystery', reason: 'no-catalog-match' }],
+      },
+      false,
+    );
+    expect(summary.spec).toBe(STAMP_SUMMARY_SPEC);
+    expect(summary.dryRun).toBe(false);
+    expect(summary.attempted).toBe(4); // 3 updates + 1 skip
+    expect(summary.skipped).toBe(1);
+    expect(summary.inserts).toBe(1);
+    expect(summary.replaces).toBe(2);
+    expect(summary.changedFiles).toBe(2);
+    expect(summary.hadChanges).toBe(true);
+  });
+
+  it('hadChanges is false when every update was a no-op', () => {
+    const summary = buildStampSummary(
+      {
+        updates: [
+          {
+            catalogId: 'A',
+            snapshotName: 'a',
+            filePath: '/x/a.mdx',
+            action: 'replace',
+            changed: false,
+          },
+        ],
+        skips: [],
+      },
+      false,
+    );
+    expect(summary.hadChanges).toBe(false);
+    expect(summary.changedFiles).toBe(0);
+  });
+
+  it('propagates dryRun into the summary', () => {
+    const summary = buildStampSummary({ updates: [], skips: [] }, true);
+    expect(summary.dryRun).toBe(true);
+  });
+});

package/src/stamp.ts

@@ -0,0 +1,232 @@
+// Stamp an architecture snapshot into a catalog's event mdx files.
+//
+// For each event in the snapshot that matches an event in the catalog (by
+// normalised name), the stamp command writes an evidence block between
+// `<!-- autotel:stamp-start -->` and `<!-- autotel:stamp-end -->` markers.
+// Subsequent runs replace the content between the markers idempotently, so
+// re-stamping is safe to run on every commit / in CI.
+//
+// If the markers do not yet exist in a file, they are inserted at the most
+// natural place: just before the `<Footer />` component if present, else
+// just before the closing `</...>` tag of the last visible content, else
+// appended to the file.
+
+import { readFile, writeFile } from 'node:fs/promises';
+import type { ArchitectureSnapshot, EventObservation } from './snapshot';
+import { readCatalogState } from './catalog';
+
+export const STAMP_START = '<!-- autotel:stamp-start -->';
+export const STAMP_END = '<!-- autotel:stamp-end -->';
+
+export interface StampOptions {
+  /** Loaded snapshot, OR pass `loadSnapshot(path)` from the caller. */
+  snapshot: ArchitectureSnapshot;
+  /** Catalog root (the directory containing eventcatalog.config.*). */
+  catalogPath: string;
+  /** If true, do not write files — just return the diff plan. */
+  dryRun?: boolean;
+  /** Override "now" for deterministic tests. */
+  now?: () => Date;
+}
+
+export type StampUpdate = {
+  /** Catalog event id, e.g. `OrderPlaced`. */
+  catalogId: string;
+  /** Snapshot event name, e.g. `order.placed`. */
+  snapshotName: string;
+  /** Absolute path to the mdx file that was (or would be) updated. */
+  filePath: string;
+  /** Was this an insert (no prior markers) or a replace? */
+  action: 'insert' | 'replace';
+  /**
+   * True if the proposed content differs from what's on disk. False when a
+   * replace would write byte-identical content — meaning no real change.
+   * Used by `--summary-output` so CI can answer "did this PR need stamping?"
+   * without diffing files.
+   */
+  changed: boolean;
+};
+
+export type StampSkip = {
+  snapshotName: string;
+  reason: 'no-catalog-match';
+};
+
+export type StampResult = {
+  updates: StampUpdate[];
+  skips: StampSkip[];
+};
+
+export async function stampCatalog(opts: StampOptions): Promise<StampResult> {
+  const { snapshot, catalogPath, dryRun = false } = opts;
+  const catalog = await readCatalogState(catalogPath);
+
+  const catalogByNormalised = new Map<
+    string,
+    { id: string; filePath: string }
+  >();
+  for (const [id, ev] of catalog.events) {
+    catalogByNormalised.set(normaliseEventId(id), {
+      id,
+      filePath: ev.filePath,
+    });
+  }
+
+  const updates: StampUpdate[] = [];
+  const skips: StampSkip[] = [];
+
+  for (const [name, obs] of Object.entries(snapshot.events)) {
+    const match = catalogByNormalised.get(normaliseEventId(name));
+    if (!match) {
+      skips.push({ snapshotName: name, reason: 'no-catalog-match' });
+      continue;
+    }
+
+    const block = buildStampBlock(obs);
+    const { action, changed } = await stampFile(match.filePath, block, dryRun);
+
+    updates.push({
+      catalogId: match.id,
+      snapshotName: name,
+      filePath: match.filePath,
+      action,
+      changed,
+    });
+  }
+
+  return { updates, skips };
+}
+
+/**
+ * Render the evidence block. Designed to be readable in raw mdx AND visually
+ * distinct when rendered by EventCatalog (uses the existing
+ * `.evidence-callout` class, plus a small header label).
+ */
+export function buildStampBlock(obs: EventObservation): string {
+  const lines: string[] = [
+    STAMP_START,
+    '',
+    '<div class="evidence-callout">',
+    '<strong>Observed in autotel snapshot</strong>',
+    '',
+  ];
+  const facts: string[] = [];
+  facts.push(`**Volume**: ${obs.observedCount.toLocaleString()} events`);
+  facts.push(`**Last seen**: ${formatTimestamp(obs.lastSeen)}`);
+  if (obs.producer) facts.push(`**Producer**: ${obs.producer}`);
+  if (obs.channel) facts.push(`**Channel**: \`${obs.channel}\``);
+  lines.push(facts.join(' · '));
+  if (obs.fieldPaths.length > 0) {
+    lines.push('');
+    lines.push(
+      `**Field paths observed**: ${obs.fieldPaths.map((p) => `\`${p}\``).join(', ')}`,
+    );
+  }
+  if (obs.sampleTraceIds.length > 0) {
+    lines.push('');
+    lines.push(
+      `**Sample traces**: ${obs.sampleTraceIds.map((t) => `\`${t}\``).join(', ')}`,
+    );
+  }
+  lines.push('</div>', '', STAMP_END);
+
+  return lines.join('\n');
+}
+
+async function stampFile(
+  filePath: string,
+  block: string,
+  dryRun: boolean,
+): Promise<{ action: 'insert' | 'replace'; changed: boolean }> {
+  const content = await readFile(filePath, 'utf8');
+
+  const startIdx = content.indexOf(STAMP_START);
+  const endIdx = content.indexOf(STAMP_END);
+
+  let next: string;
+  let action: 'insert' | 'replace';
+
+  if (startIdx !== -1 && endIdx > startIdx) {
+    // Replace existing block (including markers).
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + STAMP_END.length);
+    next = before + block + after;
+    action = 'replace';
+  } else {
+    // Insert. Prefer just before <Footer /> if present, else append.
+    const footerIdx = content.search(/<Footer\s*\/>/);
+    const insertion = '\n\n' + block + '\n';
+    next =
+      footerIdx >= 0
+        ? content.slice(0, footerIdx) +
+          insertion +
+          '\n' +
+          content.slice(footerIdx)
+        : content.replace(/\s*$/, '') + insertion;
+    action = 'insert';
+  }
+
+  const changed = next !== content;
+  if (!dryRun && changed) {
+    await writeFile(filePath, next, 'utf8');
+  }
+  return { action, changed };
+}
+
+/** Versioned identifier for the stamp summary JSON file. */
+export const STAMP_SUMMARY_SPEC =
+  'autotel-eventcatalog-stamp-summary/v0.1.0' as const;
+
+export type StampSummary = {
+  spec: typeof STAMP_SUMMARY_SPEC;
+  dryRun: boolean;
+  /** Total snapshot events the stamp run considered (matched + skipped). */
+  attempted: number;
+  /** Skipped events (no catalog match). */
+  skipped: number;
+  /** Matched events that resulted in an insert action. */
+  inserts: number;
+  /** Matched events that resulted in a replace action. */
+  replaces: number;
+  /** Number of files whose content actually changed (or would change in dry-run). */
+  changedFiles: number;
+  /**
+   * True when the run produced (or would produce) any real change. CI can
+   * gate on this: "if the committed catalog is stamped, this should be
+   * false after running stamp; if not, the PR forgot to re-stamp."
+   */
+  hadChanges: boolean;
+};
+
+export function buildStampSummary(
+  result: StampResult,
+  dryRun: boolean,
+): StampSummary {
+  const inserts = result.updates.filter((u) => u.action === 'insert').length;
+  const replaces = result.updates.filter((u) => u.action === 'replace').length;
+  const changedFiles = result.updates.filter((u) => u.changed).length;
+  return {
+    spec: STAMP_SUMMARY_SPEC,
+    dryRun,
+    attempted: result.updates.length + result.skips.length,
+    skipped: result.skips.length,
+    inserts,
+    replaces,
+    changedFiles,
+    hadChanges: changedFiles > 0,
+  };
+}
+
+function normaliseEventId(id: string): string {
+  return id.toLowerCase().replaceAll(/[._\-\s]/g, '');
+}
+
+function formatTimestamp(iso: string): string {
+  // 2026-05-22T05:23:50.024Z → 2026-05-22 05:23 UTC
+  const d = new Date(iso);
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return (
+    `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ` +
+    `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())} UTC`
+  );
+}