autotel-eventcatalog 1.0.0

package/dist/cli.js

@@ -0,0 +1,1065 @@
+#!/usr/bin/env node
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import utils from '@eventcatalog/sdk';
+
+async function loadSnapshot(path) {
+  const raw = await readFile(path, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed?.spec?.startsWith("autotel-architecture/")) {
+    throw new Error(
+      `Not an autotel architecture snapshot (missing spec marker): ${path}`
+    );
+  }
+  return parsed;
+}
+async function readCatalogState(catalogPath) {
+  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 = {
+    events: /* @__PURE__ */ new Map(),
+    services: /* @__PURE__ */ new Map(),
+    channels: /* @__PURE__ */ new Map()
+  };
+  const resolveFilePath = async (id, version) => {
+    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;
+}
+function extractDeclaredFieldPaths(schema, prefix = "") {
+  const out = /* @__PURE__ */ new Set();
+  walkSchema(schema, prefix, out);
+  return [...out].toSorted();
+}
+function walkSchema(schema, prefix, out) {
+  if (!schema || typeof schema !== "object") return;
+  const s = schema;
+  if (s.properties && typeof s.properties === "object") {
+    for (const [key, sub] of Object.entries(
+      s.properties
+    )) {
+      const path = prefix === "" ? key : `${prefix}.${key}`;
+      out.add(path);
+      walkSchema(sub, path, out);
+    }
+  }
+  if (s.items) {
+    const arrayPrefix = prefix + "[]";
+    walkSchema(s.items, arrayPrefix, out);
+  }
+}
+function extractDeclaredSchemaConstraints(schema, prefix = "") {
+  const out = /* @__PURE__ */ new Map();
+  walkSchemaConstraints(schema, prefix, out);
+  const obj = {};
+  for (const [path, c] of out) obj[path] = c;
+  return obj;
+}
+function walkSchemaConstraints(schema, prefix, out) {
+  if (!schema || typeof schema !== "object") return;
+  const s = schema;
+  const typeVal = s.type;
+  const enumVal = s.enum;
+  if (prefix !== "" && (typeVal !== void 0 || enumVal !== void 0)) {
+    const types = toTypeArray(typeVal);
+    const enumValues = Array.isArray(enumVal) ? [...enumVal] : void 0;
+    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
+    )) {
+      const path = prefix === "" ? key : `${prefix}.${key}`;
+      walkSchemaConstraints(sub, path, out);
+    }
+  }
+  if (s.items) {
+    const arrayPrefix = prefix + "[]";
+    walkSchemaConstraints(s.items, arrayPrefix, out);
+  }
+}
+function toTypeArray(typeVal) {
+  if (typeof typeVal === "string") return [typeVal];
+  if (Array.isArray(typeVal)) {
+    return typeVal.filter((t) => typeof t === "string").toSorted();
+  }
+  return [];
+}
+
+// src/diff.ts
+function hasDrift(report) {
+  const c = countDriftReport(report);
+  return c.total > 0;
+}
+function countDriftReport(report) {
+  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
+  };
+}
+function diffCatalogAgainstSnapshot(snapshot, catalog) {
+  const snapshotEvents = new Set(Object.keys(snapshot.events));
+  const catalogEventIds = new Set(catalog.events.keys());
+  const catalogEventByNormalised = /* @__PURE__ */ new Map();
+  for (const id of catalogEventIds) {
+    catalogEventByNormalised.set(normaliseEventId(id), id);
+  }
+  const observedButUndocumented = [];
+  const matchedCatalogIds = /* @__PURE__ */ new Set();
+  for (const name of snapshotEvents) {
+    const matched = catalogEventByNormalised.get(normaliseEventId(name));
+    if (matched) {
+      matchedCatalogIds.add(matched);
+    } else {
+      observedButUndocumented.push(name);
+    }
+  }
+  const documentedButUnseen = [];
+  for (const id of catalogEventIds) {
+    if (!matchedCatalogIds.has(id)) documentedButUnseen.push(id);
+  }
+  const fieldDrift = [];
+  const typeDrift = [];
+  const 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.fieldStats ?? {};
+    for (const [path, declaredConstraint] of Object.entries(constraints)) {
+      const observed = stats[path];
+      if (!observed) continue;
+      if (declaredConstraint.types && declaredConstraint.types.length > 0) {
+        const accepts = expandDeclaredTypes(declaredConstraint.types);
+        const badTypes = observed.types.filter((t) => !accepts.has(t));
+        const integerDeclared = declaredConstraint.types.includes("integer") && !declaredConstraint.types.includes("number");
+        const nonIntegerSamples = integerDeclared ? observed.sampleValues.filter(
+          (v) => 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) => !declaredConstraint.enumValues?.some((d) => Object.is(d, v))
+        );
+        if (observedOutsideEnum.length > 0) {
+          valueDrift.push({
+            event: snapName,
+            path,
+            declared: declaredConstraint.enumValues,
+            observed: [...new Set(observedOutsideEnum)]
+          });
+        }
+      }
+    }
+  }
+  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() }
+  };
+}
+function expandDeclaredTypes(declared) {
+  const accepts = new Set(declared);
+  if (declared.includes("integer")) accepts.add("number");
+  return accepts;
+}
+function normaliseEventId(id) {
+  return id.toLowerCase().replaceAll(/[._\-\s]/g, "");
+}
+function collectProducers(snapshot) {
+  const out = /* @__PURE__ */ new Set();
+  for (const obs of Object.values(snapshot.events)) {
+    if (obs.producer) out.add(obs.producer);
+  }
+  return out;
+}
+function collectChannels(snapshot) {
+  const out = /* @__PURE__ */ new Set();
+  for (const obs of Object.values(snapshot.events)) {
+    if (obs.channel) out.add(obs.channel);
+  }
+  return out;
+}
+
+// src/diff-vs-base.ts
+function compareDriftReports(base, head) {
+  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 = {
+    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 = {
+    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 };
+}
+function countDriftEntries(entries) {
+  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
+  };
+}
+function diffStringList(base, head) {
+  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, head) {
+  const baseByEvent = new Map(base.map((d) => [d.event, d]));
+  const headByEvent = new Map(head.map((d) => [d.event, d]));
+  const added = [];
+  const removed = [];
+  for (const [event, h] of headByEvent) {
+    const b = baseByEvent.get(event);
+    if (!b) {
+      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, head) {
+  return diffStructuredByKey(base, head, (x) => `${x.event}::${x.path}`);
+}
+function diffValueDrift(base, head) {
+  return diffStructuredByKey(base, head, (x) => `${x.event}::${x.path}`);
+}
+function diffStructuredByKey(base, head, keyOf) {
+  const baseMap = new Map(base.map((v) => [keyOf(v), v]));
+  const headMap = new Map(head.map((v) => [keyOf(v), v]));
+  const added = [];
+  const removed = [];
+  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 };
+}
+
+// src/renderers/markdown.ts
+function renderMarkdown(report) {
+  const lines = [
+    "# 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");
+}
+function renderDeltaMarkdown(delta) {
+  const lines = [
+    "# Architecture drift \u2014 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: "\u2212" });
+    } 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: "\u2212" });
+  }
+  return lines.join("\n");
+}
+function entriesHasContent(e) {
+  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, out, options) {
+  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("");
+  }
+}
+var markdownRenderer = {
+  name: "markdown",
+  description: "GitHub-flavoured Markdown (default). Suitable for sticky PR comments.",
+  renderReport: renderMarkdown,
+  renderDelta: renderDeltaMarkdown
+};
+
+// src/renderers/terminal.ts
+function renderTerminal(report) {
+  return stripMarkdownDecorations(renderMarkdown(report));
+}
+function renderDeltaTerminal(delta) {
+  return stripMarkdownDecorations(renderDeltaMarkdown(delta));
+}
+function stripMarkdownDecorations(md) {
+  return md.replaceAll(/^#+\s+/gm, "").replaceAll("`", "").replaceAll(/\*\*([^*]+)\*\*/g, "$1");
+}
+var terminalRenderer = {
+  name: "terminal",
+  description: "Plain text. Same content as markdown, decorations stripped.",
+  renderReport: renderTerminal,
+  renderDelta: renderDeltaTerminal
+};
+
+// src/renderers/json.ts
+var REPORT_SPEC = "autotel-eventcatalog-report/v0.2.0";
+function renderJson(data) {
+  const envelope = { spec: REPORT_SPEC, ...data };
+  return JSON.stringify(envelope, null, 2);
+}
+var jsonRenderer = {
+  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 })
+};
+
+// src/renderers/index.ts
+var RENDERERS = [
+  markdownRenderer,
+  terminalRenderer,
+  jsonRenderer
+];
+var RENDERER_NAMES = RENDERERS.map((r) => r.name);
+function getRenderer(name) {
+  return RENDERERS.find((r) => r.name === name);
+}
+
+// src/policy.ts
+function evaluatePolicy(input) {
+  if (input.mode === "all") {
+    const shouldFail2 = hasDrift(input.report);
+    return {
+      shouldFail: shouldFail2,
+      reason: shouldFail2 ? "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."
+  };
+}
+var STAMP_START = "<!-- autotel:stamp-start -->";
+var STAMP_END = "<!-- autotel:stamp-end -->";
+async function stampCatalog(opts) {
+  const { snapshot, catalogPath, dryRun = false } = opts;
+  const catalog = await readCatalogState(catalogPath);
+  const catalogByNormalised = /* @__PURE__ */ new Map();
+  for (const [id, ev] of catalog.events) {
+    catalogByNormalised.set(normaliseEventId2(id), {
+      id,
+      filePath: ev.filePath
+    });
+  }
+  const updates = [];
+  const skips = [];
+  for (const [name, obs] of Object.entries(snapshot.events)) {
+    const match = catalogByNormalised.get(normaliseEventId2(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 };
+}
+function buildStampBlock(obs) {
+  const lines = [
+    STAMP_START,
+    "",
+    '<div class="evidence-callout">',
+    "<strong>Observed in autotel snapshot</strong>",
+    ""
+  ];
+  const facts = [];
+  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(" \xB7 "));
+  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, block, dryRun) {
+  const content = await readFile(filePath, "utf8");
+  const startIdx = content.indexOf(STAMP_START);
+  const endIdx = content.indexOf(STAMP_END);
+  let next;
+  let action;
+  if (startIdx !== -1 && endIdx > startIdx) {
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + STAMP_END.length);
+    next = before + block + after;
+    action = "replace";
+  } else {
+    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 };
+}
+var STAMP_SUMMARY_SPEC = "autotel-eventcatalog-stamp-summary/v0.1.0";
+function buildStampSummary(result, dryRun) {
+  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 normaliseEventId2(id) {
+  return id.toLowerCase().replaceAll(/[._\-\s]/g, "");
+}
+function formatTimestamp(iso) {
+  const d = new Date(iso);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())} UTC`;
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command !== "drift" && command !== "stamp") {
+    usage();
+    process.exit(2);
+  }
+  if (command === "stamp") {
+    return parseStampArgs(rest);
+  }
+  return parseDriftArgs(rest);
+}
+function parseDriftArgs(rest) {
+  let snapshot;
+  let baseSnapshot;
+  let catalog;
+  let output;
+  let summaryOutput;
+  let failOnDrift = false;
+  let policy;
+  let format = "markdown";
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const next = rest[i + 1];
+    switch (arg) {
+      case "--snapshot": {
+        snapshot = next;
+        i++;
+        break;
+      }
+      case "--base-snapshot": {
+        baseSnapshot = next;
+        i++;
+        break;
+      }
+      case "--catalog": {
+        catalog = next;
+        i++;
+        break;
+      }
+      case "--output": {
+        output = next;
+        i++;
+        break;
+      }
+      case "--summary-output": {
+        summaryOutput = next;
+        i++;
+        break;
+      }
+      case "--fail-on-drift": {
+        failOnDrift = true;
+        break;
+      }
+      case "--policy": {
+        if (next !== "all" && next !== "new-only") {
+          process.stderr.write(
+            `Invalid --policy value: ${next}. Use 'all' or 'new-only'.
+`
+          );
+          process.exit(2);
+        }
+        policy = next;
+        i++;
+        break;
+      }
+      case "--format": {
+        if (!getRenderer(next)) {
+          process.stderr.write(
+            `Invalid --format value: ${next}. Available renderers: ${RENDERER_NAMES.join(", ")}.
+`
+          );
+          process.exit(2);
+        }
+        format = next;
+        i++;
+        break;
+      }
+      case "-h":
+      case "--help": {
+        usage();
+        process.exit(0);
+        break;
+      }
+      default: {
+        process.stderr.write(`Unknown argument: ${arg}
+`);
+        usage();
+        process.exit(2);
+      }
+    }
+  }
+  if (!snapshot || !catalog) {
+    process.stderr.write("Both --snapshot and --catalog are required.\n");
+    usage();
+    process.exit(2);
+  }
+  if (policy === "new-only" && !baseSnapshot) {
+    process.stderr.write("--policy new-only requires --base-snapshot.\n");
+    process.exit(2);
+  }
+  return {
+    command: "drift",
+    snapshot: resolve(snapshot),
+    baseSnapshot: baseSnapshot ? resolve(baseSnapshot) : void 0,
+    catalog: resolve(catalog),
+    output: output ? resolve(output) : void 0,
+    summaryOutput: summaryOutput ? resolve(summaryOutput) : void 0,
+    failOnDrift,
+    policy,
+    format
+  };
+}
+function parseStampArgs(rest) {
+  let snapshot;
+  let catalog;
+  let dryRun = false;
+  let summaryOutput;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const next = rest[i + 1];
+    switch (arg) {
+      case "--snapshot": {
+        snapshot = next;
+        i++;
+        break;
+      }
+      case "--catalog": {
+        catalog = next;
+        i++;
+        break;
+      }
+      case "--dry-run": {
+        dryRun = true;
+        break;
+      }
+      case "--summary-output": {
+        summaryOutput = next;
+        i++;
+        break;
+      }
+      case "-h":
+      case "--help": {
+        usage();
+        process.exit(0);
+        break;
+      }
+      default: {
+        process.stderr.write(`Unknown argument: ${arg}
+`);
+        usage();
+        process.exit(2);
+      }
+    }
+  }
+  if (!snapshot || !catalog) {
+    process.stderr.write(
+      "Both --snapshot and --catalog are required for stamp.\n"
+    );
+    usage();
+    process.exit(2);
+  }
+  return {
+    command: "stamp",
+    snapshot: resolve(snapshot),
+    catalog: resolve(catalog),
+    dryRun,
+    summaryOutput: summaryOutput ? resolve(summaryOutput) : void 0
+  };
+}
+function usage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  autotel-eventcatalog drift --snapshot <path> --catalog <path> [options]",
+      "  autotel-eventcatalog stamp --snapshot <path> --catalog <path> [--dry-run]",
+      "",
+      "drift options:",
+      "  --snapshot <path>        Path to the autotel architecture snapshot JSON",
+      "  --base-snapshot <path>   Path to a baseline snapshot (typically PR base branch).",
+      "  --catalog <path>         Path to the EventCatalog root",
+      "  --output <path>          Write the report to this file",
+      "  --summary-output <path>  Write a machine-readable drift summary JSON file",
+      "  --policy <mode>          Drift fail policy: 'all' | 'new-only'",
+      `  --format <kind>          Output format: ${RENDERER_NAMES.join(" | ")}`,
+      "  --fail-on-drift          Exit non-zero when policy marks drift as failing",
+      "",
+      "stamp options:",
+      "  --snapshot <path>        Architecture snapshot JSON",
+      "  --catalog <path>         EventCatalog root",
+      "  --dry-run                Print the update plan without writing files",
+      "  --summary-output <path>  Write a machine-readable stamp summary JSON file",
+      "",
+      "  -h, --help               Show this help",
+      ""
+    ].join("\n")
+  );
+}
+async function runDrift(args) {
+  const headSnapshot = await loadSnapshot(args.snapshot);
+  const catalog = await readCatalogState(args.catalog);
+  const headReport = diffCatalogAgainstSnapshot(headSnapshot, catalog);
+  const delta = args.baseSnapshot ? compareDriftReports(
+    diffCatalogAgainstSnapshot(
+      await loadSnapshot(args.baseSnapshot),
+      catalog
+    ),
+    headReport
+  ) : void 0;
+  const effectivePolicy = args.policy ?? (delta ? "new-only" : "all");
+  const policyResult = effectivePolicy === "new-only" && delta ? evaluatePolicy({ mode: "new-only", delta }) : evaluatePolicy({ mode: "all", report: headReport });
+  const renderer = getRenderer(args.format);
+  if (!renderer) {
+    process.stderr.write(`Unknown renderer: ${args.format}
+`);
+    process.exit(2);
+  }
+  const output = effectivePolicy === "new-only" && delta ? renderer.renderDelta(delta) : renderer.renderReport(headReport);
+  process.stdout.write(output);
+  if (!output.endsWith("\n")) process.stdout.write("\n");
+  if (args.output) {
+    await mkdir(dirname(args.output), { recursive: true });
+    await writeFile(args.output, output, "utf8");
+    process.stderr.write(`
+Wrote drift report: ${args.output}
+`);
+  }
+  const summary = buildSummary(
+    effectivePolicy,
+    headReport,
+    delta,
+    policyResult
+  );
+  if (args.summaryOutput) {
+    await mkdir(dirname(args.summaryOutput), { recursive: true });
+    await writeFile(
+      args.summaryOutput,
+      JSON.stringify(summary, null, 2),
+      "utf8"
+    );
+    process.stderr.write(`Wrote drift summary: ${args.summaryOutput}
+`);
+  }
+  process.stderr.write(`
+${policyResult.reason}
+`);
+  if (args.failOnDrift && policyResult.shouldFail) {
+    process.exit(1);
+  }
+}
+var DRIFT_SUMMARY_SPEC = "autotel-eventcatalog-drift-summary/v0.2.0";
+function buildSummary(mode, headReport, delta, policyResult) {
+  const counts = mode === "new-only" && delta ? countDriftEntries(delta.introduced) : countDriftReport(headReport);
+  return {
+    spec: DRIFT_SUMMARY_SPEC,
+    mode,
+    shouldFail: policyResult.shouldFail,
+    reason: policyResult.reason,
+    counts
+  };
+}
+async function runStamp(args) {
+  const snapshot = await loadSnapshot(args.snapshot);
+  const result = await stampCatalog({
+    snapshot,
+    catalogPath: args.catalog,
+    dryRun: args.dryRun
+  });
+  for (const upd of result.updates) {
+    const verb = args.dryRun ? `would ${upd.action}` : upd.changed ? upd.action : "unchanged";
+    process.stdout.write(`${verb} ${upd.catalogId} -> ${upd.filePath}
+`);
+  }
+  for (const skip of result.skips) {
+    process.stdout.write(`skip ${skip.snapshotName} (${skip.reason})
+`);
+  }
+  const summary = buildStampSummary(result, args.dryRun);
+  process.stderr.write(
+    `
+${summary.changedFiles} changed, ${summary.replaces} replaces, ${summary.inserts} inserts, ${summary.skipped} skipped${args.dryRun ? " (dry run)" : ""}
+`
+  );
+  if (args.summaryOutput) {
+    await mkdir(dirname(args.summaryOutput), { recursive: true });
+    await writeFile(
+      args.summaryOutput,
+      JSON.stringify(summary, null, 2),
+      "utf8"
+    );
+    process.stderr.write(`Wrote stamp summary: ${args.summaryOutput}
+`);
+  }
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.command === "stamp") {
+    await runStamp(args);
+    return;
+  }
+  await runDrift(args);
+}
+main().catch((error) => {
+  process.stderr.write(`autotel-eventcatalog: ${error.message}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map