autotel-eventcatalog 1.0.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "autotel-eventcatalog",
+  "version": "1.0.0",
+  "description": "Diff your autotel architecture snapshot against an EventCatalog and report drift. Same model as Pact, for event architectures.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.cjs"
+    }
+  },
+  "bin": {
+    "autotel-eventcatalog": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "schemas",
+    "docs",
+    "action.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --exclude **/*.e2e.test.ts",
+    "test:e2e": "pnpm build && vitest run cli.e2e",
+    "test:watch": "vitest --exclude **/*.e2e.test.ts",
+    "clean": "rimraf dist",
+    "format": "prettier --write .",
+    "format:check": "prettier --check src/**/*.ts",
+    "quality": "pnpm type-check && pnpm test && pnpm test:e2e && pnpm lint && pnpm format:check"
+  },
+  "keywords": [
+    "eventcatalog",
+    "opentelemetry",
+    "autotel",
+    "observability",
+    "architecture",
+    "drift",
+    "contract-testing"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jagreehal/autotel.git",
+    "directory": "packages/autotel-eventcatalog"
+  },
+  "peerDependencies": {
+    "autotel-subscribers": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "autotel-subscribers": "workspace:*",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "dependencies": {
+    "@eventcatalog/sdk": "^2.21.2"
+  }
+}

package/schemas/README.md

@@ -0,0 +1,44 @@
+# Published JSON Schemas
+
+These files are the **public contract** for `autotel-eventcatalog`'s JSON
+output. Downstream tooling (your own GitHub Actions, dashboards, Slack
+bots, CI scripts) should validate against them.
+
+| File                                                       | Emitted by                      | `spec:` value                               |
+| ---------------------------------------------------------- | ------------------------------- | ------------------------------------------- |
+| [`drift-report-v0.1.0.json`](./drift-report-v0.1.0.json)   | `drift --format json`           | `autotel-eventcatalog-report/v0.1.0`        |
+| [`drift-summary-v0.1.0.json`](./drift-summary-v0.1.0.json) | `drift --summary-output <path>` | `autotel-eventcatalog-drift-summary/v0.1.0` |
+| [`stamp-summary-v0.1.0.json`](./stamp-summary-v0.1.0.json) | `stamp --summary-output <path>` | `autotel-eventcatalog-stamp-summary/v0.1.0` |
+
+For consumption examples and the version policy, see
+[`docs/CONTRACT.md`](../docs/CONTRACT.md).
+
+## Version policy in one sentence
+
+The version segment in each schema's `$id` (`v0.1.0`) follows semver.
+**Minor** bumps add optional fields; **major** bumps break shape. The
+`spec:` field on every emitted envelope is your one-way gate against
+unknown majors.
+
+## Validation example
+
+These schemas use only standard JSON Schema 2020-12 features, so any
+mainstream validator works:
+
+```typescript
+import Ajv from 'ajv';
+import schema from 'autotel-eventcatalog/schemas/drift-summary-v0.1.0.json';
+
+const ajv = new Ajv();
+const validate = ajv.compile(schema);
+
+if (!validate(parsedJson)) {
+  throw new Error(`Invalid drift summary: ${ajv.errorsText(validate.errors)}`);
+}
+```
+
+## Why these live in the package, not on a CDN
+
+So that the schema version you validate against is always exactly the
+version your CLI emitted. `npm` is the source of truth; pin the package
+version and the schemas are pinned with it.

package/schemas/drift-report-v0.1.0.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://autotel.dev/schemas/eventcatalog/drift-report/v0.1.0.json",
+  "title": "Autotel EventCatalog Drift Report v0.1.0",
+  "description": "JSON output of `autotel-eventcatalog drift --format json`. Wraps a DriftReport (mode: all) or a DriftDelta (mode: new-only) in a versioned envelope.",
+  "type": "object",
+  "required": ["spec", "mode"],
+  "oneOf": [
+    {
+      "required": ["spec", "mode", "report"],
+      "properties": {
+        "spec": { "const": "autotel-eventcatalog-report/v0.1.0" },
+        "mode": { "const": "all" },
+        "report": { "$ref": "#/$defs/DriftReport" }
+      }
+    },
+    {
+      "required": ["spec", "mode", "delta"],
+      "properties": {
+        "spec": { "const": "autotel-eventcatalog-report/v0.1.0" },
+        "mode": { "const": "new-only" },
+        "delta": { "$ref": "#/$defs/DriftDelta" }
+      }
+    }
+  ],
+  "$defs": {
+    "FieldDrift": {
+      "type": "object",
+      "required": ["event", "extra", "missing"],
+      "properties": {
+        "event": { "type": "string" },
+        "extra": { "type": "array", "items": { "type": "string" } },
+        "missing": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "DriftEntries": {
+      "type": "object",
+      "required": ["events", "services", "channels"],
+      "properties": {
+        "events": {
+          "type": "object",
+          "required": [
+            "observedButUndocumented",
+            "documentedButUnseen",
+            "fieldDrift"
+          ],
+          "properties": {
+            "observedButUndocumented": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "documentedButUnseen": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "fieldDrift": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/FieldDrift" }
+            }
+          }
+        },
+        "services": {
+          "type": "object",
+          "required": ["observedButUndocumented"],
+          "properties": {
+            "observedButUndocumented": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "channels": {
+          "type": "object",
+          "required": ["observedButUndocumented"],
+          "properties": {
+            "observedButUndocumented": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "DriftReport": {
+      "allOf": [
+        { "$ref": "#/$defs/DriftEntries" },
+        {
+          "type": "object",
+          "required": ["snapshotGeneratedAt", "snapshotService"],
+          "properties": {
+            "snapshotGeneratedAt": { "type": "string" },
+            "snapshotService": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "DriftDelta": {
+      "type": "object",
+      "required": ["introduced", "resolved", "hasNewDrift"],
+      "properties": {
+        "introduced": { "$ref": "#/$defs/DriftEntries" },
+        "resolved": { "$ref": "#/$defs/DriftEntries" },
+        "hasNewDrift": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/drift-report-v0.2.0.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://autotel.dev/schemas/eventcatalog/drift-report/v0.2.0.json",
+  "title": "Autotel EventCatalog Drift Report v0.2.0",
+  "description": "JSON output of `autotel-eventcatalog drift --format json`. Wraps a DriftReport (mode: all) or a DriftDelta (mode: new-only) in a versioned envelope.",
+  "type": "object",
+  "required": ["spec", "mode"],
+  "oneOf": [
+    {
+      "required": ["spec", "mode", "report"],
+      "properties": {
+        "spec": { "const": "autotel-eventcatalog-report/v0.2.0" },
+        "mode": { "const": "all" },
+        "report": { "$ref": "#/$defs/DriftReport" }
+      }
+    },
+    {
+      "required": ["spec", "mode", "delta"],
+      "properties": {
+        "spec": { "const": "autotel-eventcatalog-report/v0.2.0" },
+        "mode": { "const": "new-only" },
+        "delta": { "$ref": "#/$defs/DriftDelta" }
+      }
+    }
+  ],
+  "$defs": {
+    "FieldDrift": {
+      "type": "object",
+      "required": ["event", "extra", "missing"],
+      "properties": {
+        "event": { "type": "string" },
+        "extra": { "type": "array", "items": { "type": "string" } },
+        "missing": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "TypeDrift": {
+      "type": "object",
+      "required": ["event", "path", "declared", "observed"],
+      "properties": {
+        "event": { "type": "string" },
+        "path": { "type": "string" },
+        "declared": { "type": "array", "items": { "type": "string" } },
+        "observed": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "ValueDrift": {
+      "type": "object",
+      "required": ["event", "path", "declared", "observed"],
+      "properties": {
+        "event": { "type": "string" },
+        "path": { "type": "string" },
+        "declared": { "type": "array", "items": {} },
+        "observed": { "type": "array", "items": {} }
+      }
+    },
+    "DriftEntries": {
+      "type": "object",
+      "required": ["events", "services", "channels"],
+      "properties": {
+        "events": {
+          "type": "object",
+          "required": [
+            "observedButUndocumented",
+            "documentedButUnseen",
+            "fieldDrift",
+            "typeDrift",
+            "valueDrift"
+          ],
+          "properties": {
+            "observedButUndocumented": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "documentedButUnseen": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "fieldDrift": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/FieldDrift" }
+            },
+            "typeDrift": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/TypeDrift" }
+            },
+            "valueDrift": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/ValueDrift" }
+            }
+          }
+        },
+        "services": {
+          "type": "object",
+          "required": ["observedButUndocumented"],
+          "properties": {
+            "observedButUndocumented": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "channels": {
+          "type": "object",
+          "required": ["observedButUndocumented"],
+          "properties": {
+            "observedButUndocumented": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "DriftReport": {
+      "allOf": [
+        { "$ref": "#/$defs/DriftEntries" },
+        {
+          "type": "object",
+          "required": ["snapshotGeneratedAt", "snapshotService"],
+          "properties": {
+            "snapshotGeneratedAt": { "type": "string" },
+            "snapshotService": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "DriftDelta": {
+      "type": "object",
+      "required": ["introduced", "resolved", "hasNewDrift"],
+      "properties": {
+        "introduced": { "$ref": "#/$defs/DriftEntries" },
+        "resolved": { "$ref": "#/$defs/DriftEntries" },
+        "hasNewDrift": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/drift-summary-v0.1.0.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://autotel.dev/schemas/eventcatalog/drift-summary/v0.1.0.json",
+  "title": "Autotel EventCatalog Drift Summary v0.1.0",
+  "description": "Machine-readable summary written by `autotel-eventcatalog drift --summary-output`. Downstream tooling (GitHub Actions, dashboards, Slack bots) should read this. Major-version bumps are breaking; minor-version bumps add optional fields only.",
+  "type": "object",
+  "required": ["spec", "mode", "shouldFail", "reason", "counts"],
+  "additionalProperties": false,
+  "properties": {
+    "spec": {
+      "type": "string",
+      "const": "autotel-eventcatalog-drift-summary/v0.1.0"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["all", "new-only"],
+      "description": "Which policy was applied. `all` = fail on any drift; `new-only` = fail only on drift introduced vs a baseline snapshot."
+    },
+    "shouldFail": {
+      "type": "boolean",
+      "description": "True iff the configured policy considers the current state a CI failure."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Short human-readable line explaining why shouldFail is what it is."
+    },
+    "counts": {
+      "type": "object",
+      "required": [
+        "total",
+        "observedButUndocumentedEvents",
+        "documentedButUnseenEvents",
+        "fieldDriftEvents",
+        "fieldDriftPaths",
+        "typeDriftPaths",
+        "valueDriftPaths",
+        "undocumentedServices",
+        "undocumentedChannels"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sum of all individual drift findings. Matches the dashboard's `drift findings` badge."
+        },
+        "observedButUndocumentedEvents": { "type": "integer", "minimum": 0 },
+        "documentedButUnseenEvents": { "type": "integer", "minimum": 0 },
+        "fieldDriftEvents": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Distinct events with at least one field-path mismatch."
+        },
+        "fieldDriftPaths": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sum of extra + missing field paths across every event with field drift."
+        },
+        "typeDriftPaths": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of field paths where observed runtime types do not match declared schema types."
+        },
+        "valueDriftPaths": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of field paths where observed primitive values fall outside declared enum values."
+        },
+        "undocumentedServices": { "type": "integer", "minimum": 0 },
+        "undocumentedChannels": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/drift-summary-v0.2.0.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://autotel.dev/schemas/eventcatalog/drift-summary/v0.2.0.json",
+  "title": "Autotel EventCatalog Drift Summary v0.2.0",
+  "description": "Machine-readable summary written by `autotel-eventcatalog drift --summary-output`. Downstream tooling (GitHub Actions, dashboards, Slack bots) should read this. Major-version bumps are breaking; minor-version bumps add optional fields only.",
+  "type": "object",
+  "required": ["spec", "mode", "shouldFail", "reason", "counts"],
+  "additionalProperties": false,
+  "properties": {
+    "spec": {
+      "type": "string",
+      "const": "autotel-eventcatalog-drift-summary/v0.2.0"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["all", "new-only"],
+      "description": "Which policy was applied. `all` = fail on any drift; `new-only` = fail only on drift introduced vs a baseline snapshot."
+    },
+    "shouldFail": {
+      "type": "boolean",
+      "description": "True iff the configured policy considers the current state a CI failure."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Short human-readable line explaining why shouldFail is what it is."
+    },
+    "counts": {
+      "type": "object",
+      "required": [
+        "total",
+        "observedButUndocumentedEvents",
+        "documentedButUnseenEvents",
+        "fieldDriftEvents",
+        "fieldDriftPaths",
+        "typeDriftPaths",
+        "valueDriftPaths",
+        "undocumentedServices",
+        "undocumentedChannels"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sum of all individual drift findings. Matches the dashboard's `drift findings` badge."
+        },
+        "observedButUndocumentedEvents": { "type": "integer", "minimum": 0 },
+        "documentedButUnseenEvents": { "type": "integer", "minimum": 0 },
+        "fieldDriftEvents": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Distinct events with at least one field-path mismatch."
+        },
+        "fieldDriftPaths": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sum of extra + missing field paths across every event with field drift."
+        },
+        "typeDriftPaths": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of field paths where observed runtime types do not match declared schema types."
+        },
+        "valueDriftPaths": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of field paths where observed primitive values fall outside declared enum values."
+        },
+        "undocumentedServices": { "type": "integer", "minimum": 0 },
+        "undocumentedChannels": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/stamp-summary-v0.1.0.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://autotel.dev/schemas/eventcatalog/stamp-summary/v0.1.0.json",
+  "title": "Autotel EventCatalog Stamp Summary v0.1.0",
+  "description": "Machine-readable summary written by `autotel-eventcatalog stamp --summary-output`. CI workflows gate on `hadChanges` to detect 'this PR forgot to re-stamp'.",
+  "type": "object",
+  "required": [
+    "spec",
+    "dryRun",
+    "attempted",
+    "skipped",
+    "inserts",
+    "replaces",
+    "changedFiles",
+    "hadChanges"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "spec": {
+      "type": "string",
+      "const": "autotel-eventcatalog-stamp-summary/v0.1.0"
+    },
+    "dryRun": { "type": "boolean" },
+    "attempted": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total snapshot events the stamp run considered (matched + skipped)."
+    },
+    "skipped": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Snapshot events with no matching catalog entry."
+    },
+    "inserts": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Files where a stamp block was inserted for the first time."
+    },
+    "replaces": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Files where an existing stamp block was replaced (regardless of whether content actually changed)."
+    },
+    "changedFiles": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Files whose contents actually changed on disk (or would change in dry-run)."
+    },
+    "hadChanges": {
+      "type": "boolean",
+      "description": "True iff the run produced (or would produce) at least one real change."
+    }
+  }
+}

package/src/__fixtures__/drift-report-all.golden.json

@@ -0,0 +1,33 @@
+{
+  "spec": "autotel-eventcatalog-report/v0.2.0",
+  "mode": "all",
+  "report": {
+    "snapshotGeneratedAt": "2026-05-22T00:00:00.000Z",
+    "snapshotService": "fixture",
+    "events": {
+      "observedButUndocumented": [
+        "order.cancelled"
+      ],
+      "documentedButUnseen": [
+        "LegacyEvent"
+      ],
+      "fieldDrift": [
+        {
+          "event": "recommendation.generated",
+          "extra": [
+            "personalization_seed"
+          ],
+          "missing": []
+        }
+      ],
+      "typeDrift": [],
+      "valueDrift": []
+    },
+    "services": {
+      "observedButUndocumented": []
+    },
+    "channels": {
+      "observedButUndocumented": []
+    }
+  }
+}

package/src/__fixtures__/drift-summary-clean.golden.json

@@ -0,0 +1,17 @@
+{
+  "spec": "autotel-eventcatalog-drift-summary/v0.2.0",
+  "mode": "all",
+  "shouldFail": false,
+  "reason": "No drift detected.",
+  "counts": {
+    "observedButUndocumentedEvents": 0,
+    "documentedButUnseenEvents": 0,
+    "fieldDriftEvents": 0,
+    "fieldDriftPaths": 0,
+    "typeDriftPaths": 0,
+    "valueDriftPaths": 0,
+    "undocumentedServices": 0,
+    "undocumentedChannels": 0,
+    "total": 0
+  }
+}

package/src/__fixtures__/drift-summary-drifty.golden.json

@@ -0,0 +1,17 @@
+{
+  "spec": "autotel-eventcatalog-drift-summary/v0.2.0",
+  "mode": "all",
+  "shouldFail": true,
+  "reason": "Drift detected in current snapshot.",
+  "counts": {
+    "observedButUndocumentedEvents": 1,
+    "documentedButUnseenEvents": 1,
+    "fieldDriftEvents": 1,
+    "fieldDriftPaths": 1,
+    "typeDriftPaths": 0,
+    "valueDriftPaths": 0,
+    "undocumentedServices": 0,
+    "undocumentedChannels": 0,
+    "total": 3
+  }
+}

package/src/__fixtures__/stamp-summary-noop.golden.json

@@ -0,0 +1,10 @@
+{
+  "spec": "autotel-eventcatalog-stamp-summary/v0.1.0",
+  "dryRun": false,
+  "attempted": 0,
+  "skipped": 0,
+  "inserts": 0,
+  "replaces": 0,
+  "changedFiles": 0,
+  "hadChanges": false
+}