autotel-eventcatalog 1.0.0

package/src/catalog.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { extractDeclaredFieldPaths } from './catalog';
+
+describe('extractDeclaredFieldPaths', () => {
+  it('extracts scalar properties', () => {
+    expect(
+      extractDeclaredFieldPaths({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string' },
+          totalCents: { type: 'integer' },
+        },
+      }),
+    ).toEqual(['orderId', 'totalCents']);
+  });
+
+  it('collapses array items under `[]`', () => {
+    expect(
+      extractDeclaredFieldPaths({
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                sku: { type: 'string' },
+                quantity: { type: 'integer' },
+              },
+            },
+          },
+        },
+      }),
+    ).toEqual(['items', 'items[].quantity', 'items[].sku']);
+  });
+
+  it('walks nested objects', () => {
+    expect(
+      extractDeclaredFieldPaths({
+        type: 'object',
+        properties: {
+          usage: {
+            type: 'object',
+            properties: {
+              promptTokens: { type: 'integer' },
+              completionTokens: { type: 'integer' },
+            },
+          },
+        },
+      }),
+    ).toEqual(['usage', 'usage.completionTokens', 'usage.promptTokens']);
+  });
+
+  it('returns an empty list for non-object schemas', () => {
+    expect(extractDeclaredFieldPaths({ type: 'string' })).toEqual([]);
+    expect(extractDeclaredFieldPaths(null)).toEqual([]);
+    expect(extractDeclaredFieldPaths()).toEqual([]);
+  });
+});
+
+// Path classification and frontmatter parsing now live in @eventcatalog/sdk
+// (since v2.21); the cross-platform path tests that used to live here are
+// covered by the SDK's own test suite.

package/src/catalog.ts

@@ -0,0 +1,169 @@
+// Read the current state of an EventCatalog using @eventcatalog/sdk. We
+// re-use SDK types (`Event`, `Service`, `Channel`) verbatim and only add the
+// two fields the SDK doesn't expose: the resolved on-disk `filePath`, and the
+// dotted field-path + schema-constraint extractions our drift diff consumes.
+// Inventing our own catalog types would silently drift from the SDK as it
+// evolves.
+
+import utils from '@eventcatalog/sdk';
+import type { Channel, Event, Service } from '@eventcatalog/sdk';
+
+export type SchemaConstraint = {
+  types?: string[];
+  enumValues?: unknown[];
+};
+
+export type CatalogEvent = Event & {
+  /** Absolute path to the event's `index.mdx`, resolved via SDK. */
+  filePath: string;
+  /** Field paths declared in the event's JSON Schema (if present). */
+  declaredFieldPaths?: string[];
+  declaredSchemaConstraints?: Record<string, SchemaConstraint>;
+};
+
+export type CatalogService = Service & {
+  filePath: string;
+};
+
+export type CatalogChannel = Channel & {
+  filePath: string;
+};
+
+export type CatalogState = {
+  events: Map<string, CatalogEvent>;
+  services: Map<string, CatalogService>;
+  channels: Map<string, CatalogChannel>;
+};
+
+export async function readCatalogState(
+  catalogPath: string,
+): Promise<CatalogState> {
+  const sdk = utils(catalogPath);
+
+  const [events, services, channels] = await Promise.all([
+    sdk.getEvents({ latestOnly: true, attachSchema: true }),
+    sdk.getServices({ latestOnly: true }),
+    sdk.getChannels({ latestOnly: true }),
+  ]);
+
+  const state: CatalogState = {
+    events: new Map(),
+    services: new Map(),
+    channels: new Map(),
+  };
+
+  // SDK quirk (as of 2.21.2): unlike the other helpers, `getResourcePath` is
+  // not curried with `catalogDir`, so we pass the catalog path explicitly.
+  const resolveFilePath = async (id: string, version?: string) => {
+    const paths = await sdk.getResourcePath(catalogPath, id, version);
+    return paths?.fullPath ?? '';
+  };
+
+  for (const e of events ?? []) {
+    const filePath = await resolveFilePath(e.id, e.version);
+    const schemaExtractions = e.schema
+      ? {
+          declaredFieldPaths: extractDeclaredFieldPaths(e.schema),
+          declaredSchemaConstraints: extractDeclaredSchemaConstraints(e.schema),
+        }
+      : {};
+    state.events.set(e.id, { ...e, filePath, ...schemaExtractions });
+  }
+
+  for (const s of services ?? []) {
+    const filePath = await resolveFilePath(s.id, s.version);
+    state.services.set(s.id, { ...s, filePath });
+  }
+
+  for (const c of channels ?? []) {
+    const filePath = await resolveFilePath(c.id, c.version);
+    state.channels.set(c.id, { ...c, filePath });
+  }
+
+  return state;
+}
+
+/**
+ * Extract field paths from a JSON Schema. Mirrors the dotted-path convention
+ * used by the snapshot subscriber: arrays collapse to `[]`, nested objects
+ * use `.`. We walk `properties` (objects) and `items` (arrays).
+ */
+export function extractDeclaredFieldPaths(
+  schema: unknown,
+  prefix = '',
+): string[] {
+  const out = new Set<string>();
+  walkSchema(schema, prefix, out);
+  return [...out].toSorted();
+}
+
+function walkSchema(schema: unknown, prefix: string, out: Set<string>): void {
+  if (!schema || typeof schema !== 'object') return;
+  const s = schema as Record<string, unknown>;
+
+  if (s.properties && typeof s.properties === 'object') {
+    for (const [key, sub] of Object.entries(
+      s.properties as Record<string, unknown>,
+    )) {
+      const path = prefix === '' ? key : `${prefix}.${key}`;
+      out.add(path);
+      walkSchema(sub, path, out);
+    }
+  }
+
+  if (s.items) {
+    const arrayPrefix = prefix + '[]';
+    walkSchema(s.items, arrayPrefix, out);
+  }
+}
+
+export function extractDeclaredSchemaConstraints(
+  schema: unknown,
+  prefix = '',
+): Record<string, SchemaConstraint> {
+  const out = new Map<string, SchemaConstraint>();
+  walkSchemaConstraints(schema, prefix, out);
+  const obj: Record<string, SchemaConstraint> = {};
+  for (const [path, c] of out) obj[path] = c;
+  return obj;
+}
+
+function walkSchemaConstraints(
+  schema: unknown,
+  prefix: string,
+  out: Map<string, SchemaConstraint>,
+): void {
+  if (!schema || typeof schema !== 'object') return;
+  const s = schema as Record<string, unknown>;
+  const typeVal = s.type;
+  const enumVal = s.enum;
+  if (prefix !== '' && (typeVal !== undefined || enumVal !== undefined)) {
+    const types = toTypeArray(typeVal);
+    const enumValues = Array.isArray(enumVal) ? [...enumVal] : undefined;
+    out.set(prefix, {
+      ...(types.length > 0 ? { types } : {}),
+      ...(enumValues ? { enumValues } : {}),
+    });
+  }
+
+  if (s.properties && typeof s.properties === 'object') {
+    for (const [key, sub] of Object.entries(
+      s.properties as Record<string, unknown>,
+    )) {
+      const path = prefix === '' ? key : `${prefix}.${key}`;
+      walkSchemaConstraints(sub, path, out);
+    }
+  }
+  if (s.items) {
+    const arrayPrefix = prefix + '[]';
+    walkSchemaConstraints(s.items, arrayPrefix, out);
+  }
+}
+
+function toTypeArray(typeVal: unknown): string[] {
+  if (typeof typeVal === 'string') return [typeVal];
+  if (Array.isArray(typeVal)) {
+    return typeVal.filter((t): t is string => typeof t === 'string').toSorted();
+  }
+  return [];
+}

package/src/cli.e2e.test.ts

@@ -0,0 +1,310 @@
+// End-to-end tests for the CLI dispatcher. These run the compiled
+// dist/cli.js as a subprocess against fixture inputs — the same shape a
+// CI step or a user shell would invoke.
+//
+// Unit tests in cli.ts would test each branch in isolation; these tests
+// verify the wiring between branches and exit codes. They catch the bug
+// class fixed in PR ("the action invoked the CLI without --fail-on-drift,
+// so exit code stayed 0 regardless of drift").
+//
+// Requires `dist/cli.js` to exist (run `pnpm build` first). The
+// `pnpm test:e2e` script does this for you.
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { ARCHITECTURE_SNAPSHOT_SPEC } from 'autotel-subscribers/architecture-snapshot';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI = join(HERE, '..', 'dist', 'cli.js');
+
+type CliResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+function runCli(args: string[]): CliResult {
+  const result = spawnSync('node', [CLI, ...args], { encoding: 'utf8' });
+  return {
+    exitCode: result.status ?? -1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/** Tiny fixture builder — a snapshot file + a minimal catalog tree. */
+function buildFixture(opts: {
+  /** Snapshot events keyed by event name. */
+  events: Record<
+    string,
+    {
+      fields: string[];
+      producer?: string;
+      channel?: string;
+    }
+  >;
+  /** Catalog events to write as <root>/events/<id>/index.mdx files. */
+  catalogEvents: Array<{ id: string; declaredFields?: string[] }>;
+}): { snapshotPath: string; catalogPath: string; root: string } {
+  const root = mkdtempSync(join(tmpdir(), 'autotel-cli-e2e-'));
+  const catalogPath = join(root, 'catalog');
+  mkdirSync(catalogPath, { recursive: true });
+
+  const snapshot = {
+    spec: ARCHITECTURE_SNAPSHOT_SPEC,
+    generatedAt: '2026-05-22T00:00:00.000Z',
+    service: 'fixture',
+    events: Object.fromEntries(
+      Object.entries(opts.events).map(([name, e]) => [
+        name,
+        {
+          name,
+          observedCount: 3,
+          firstSeen: '2026-05-22T00:00:00.000Z',
+          lastSeen: '2026-05-22T00:00:00.000Z',
+          fieldPaths: e.fields,
+          sampleTraceIds: [],
+          ...(e.producer ? { producer: e.producer } : {}),
+          ...(e.channel ? { channel: e.channel } : {}),
+        },
+      ]),
+    ),
+  };
+  const snapshotPath = join(root, 'snapshot.json');
+  writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
+
+  for (const ev of opts.catalogEvents) {
+    const dir = join(catalogPath, 'events', ev.id);
+    mkdirSync(dir, { recursive: true });
+    const frontmatter = ev.declaredFields
+      ? `---\nid: ${ev.id}\nversion: 1.0.0\nschemaPath: schema.json\n---\n`
+      : `---\nid: ${ev.id}\nversion: 1.0.0\n---\n`;
+    writeFileSync(join(dir, 'index.mdx'), frontmatter + '\n## Overview\n');
+    if (ev.declaredFields) {
+      const schema = {
+        type: 'object',
+        properties: Object.fromEntries(
+          ev.declaredFields.map((f) => [f, { type: 'string' }]),
+        ),
+      };
+      writeFileSync(join(dir, 'schema.json'), JSON.stringify(schema, null, 2));
+    }
+  }
+
+  return { snapshotPath, catalogPath, root };
+}
+
+beforeAll(() => {
+  if (!existsSync(CLI)) {
+    throw new Error(
+      `CLI not built: ${CLI}\nRun \`pnpm build\` before \`pnpm test:e2e\`.`,
+    );
+  }
+});
+
+describe('cli e2e — drift', () => {
+  it('exits 0 with --fail-on-drift when catalog and runtime agree', () => {
+    const { snapshotPath, catalogPath } = buildFixture({
+      events: { 'order.placed': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced', declaredFields: ['orderId'] }],
+    });
+    const res = runCli([
+      'drift',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--fail-on-drift',
+    ]);
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toContain('No drift detected');
+    expect(res.stderr).toContain('No drift detected');
+  });
+
+  it('exits 1 with --fail-on-drift when drift exists', () => {
+    const { snapshotPath, catalogPath } = buildFixture({
+      events: { 'order.cancelled': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+    const res = runCli([
+      'drift',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--fail-on-drift',
+    ]);
+    expect(res.exitCode).toBe(1);
+    expect(res.stdout).toContain('Architecture drift report');
+    expect(res.stderr).toMatch(/Drift detected/);
+  });
+
+  it('exits 0 WITHOUT --fail-on-drift even when drift exists', () => {
+    const { snapshotPath, catalogPath } = buildFixture({
+      events: { 'order.cancelled': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+    const res = runCli([
+      'drift',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+    ]);
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toContain('Architecture drift report');
+    // Drift outcome line is still printed to stderr — the gating just doesn't fire.
+    expect(res.stderr).toMatch(/Drift detected/);
+  });
+
+  it('exits 2 when --policy new-only is set without --base-snapshot', () => {
+    const { snapshotPath, catalogPath } = buildFixture({
+      events: { 'order.placed': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+    const res = runCli([
+      'drift',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--policy',
+      'new-only',
+    ]);
+    expect(res.exitCode).toBe(2);
+    expect(res.stderr).toContain('--policy new-only requires --base-snapshot');
+  });
+
+  it('outputs versioned JSON when --format json is set', () => {
+    const { snapshotPath, catalogPath } = buildFixture({
+      events: { 'order.placed': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+    const res = runCli([
+      'drift',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--format',
+      'json',
+    ]);
+    expect(res.exitCode).toBe(0);
+    const parsed = JSON.parse(res.stdout);
+    expect(parsed.spec).toBe('autotel-eventcatalog-report/v0.2.0');
+    expect(parsed.mode).toBe('all');
+    expect(parsed.report.snapshotService).toBe('fixture');
+  });
+
+  it('errors clearly when given an unknown flag', () => {
+    const { snapshotPath, catalogPath } = buildFixture({
+      events: { 'order.placed': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+    const res = runCli([
+      'drift',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--made-up-flag',
+    ]);
+    expect(res.exitCode).toBe(2);
+    expect(res.stderr).toContain('Unknown argument');
+  });
+});
+
+describe('cli e2e — stamp', () => {
+  it('dry-run leaves files untouched', () => {
+    const { snapshotPath, catalogPath } = buildFixture({
+      events: { 'order.placed': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+    const res = runCli([
+      'stamp',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--dry-run',
+    ]);
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toMatch(/would insert OrderPlaced/);
+  });
+
+  it('writes a versioned summary JSON when --summary-output is given', () => {
+    const { snapshotPath, catalogPath, root } = buildFixture({
+      events: { 'order.placed': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+    const summaryPath = join(root, 'stamp-summary.json');
+
+    const res = runCli([
+      'stamp',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--summary-output',
+      summaryPath,
+    ]);
+    expect(res.exitCode).toBe(0);
+
+    const summary = JSON.parse(readFileSync(summaryPath, 'utf8'));
+    expect(summary.spec).toBe('autotel-eventcatalog-stamp-summary/v0.1.0');
+    expect(summary.hadChanges).toBe(true);
+    expect(summary.inserts).toBe(1);
+    expect(summary.changedFiles).toBe(1);
+  });
+
+  it('summary.hadChanges is false when re-stamping is a no-op', () => {
+    const { snapshotPath, catalogPath, root } = buildFixture({
+      events: { 'order.placed': { fields: ['orderId'] } },
+      catalogEvents: [{ id: 'OrderPlaced' }],
+    });
+
+    // First stamp writes the block.
+    runCli(['stamp', '--snapshot', snapshotPath, '--catalog', catalogPath]);
+
+    // Second stamp with identical input is a no-op.
+    const summaryPath = join(root, 'stamp-summary-2.json');
+    const res = runCli([
+      'stamp',
+      '--snapshot',
+      snapshotPath,
+      '--catalog',
+      catalogPath,
+      '--summary-output',
+      summaryPath,
+    ]);
+    expect(res.exitCode).toBe(0);
+    const summary = JSON.parse(readFileSync(summaryPath, 'utf8'));
+    expect(summary.hadChanges).toBe(false);
+    expect(summary.changedFiles).toBe(0);
+    expect(summary.replaces).toBe(1);
+  });
+});
+
+describe('cli e2e — top-level', () => {
+  it('exits 2 with usage on no command', () => {
+    const res = runCli([]);
+    expect(res.exitCode).toBe(2);
+    expect(res.stderr).toContain('Usage');
+  });
+
+  it('exits 2 on unknown command', () => {
+    const res = runCli(['rumpus']);
+    expect(res.exitCode).toBe(2);
+    expect(res.stderr).toContain('Usage');
+  });
+});