@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/governance/architecture-change-detection/03-recipes.md

@@ -0,0 +1,309 @@
+---
+sidebar_position: 3
+sidebar_label: Recipes
+title: Recipes
+description: Common governance configurations you can copy and adapt
+---
+
+## Alert when anyone consumes a message your service produces
+
+Use the `produces:` prefix to scope a rule to all messages sent by a given service. This is the recommended pattern for service owners who want visibility into downstream adoption.
+
+```yaml title="governance.yaml"
+rules:
+  - name: orders-service-consumer-changes
+    when:
+      - consumer_added
+      - consumer_removed
+    resources:
+      - produces:OrdersService
+    actions:
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+        headers:
+          Authorization: Bearer $API_TOKEN
+```
+
+## Alert when a producer stops producing a message your service depends on
+
+Use `consumes:` to watch all messages a service receives, then trigger on `producer_removed`. This catches upstream breaking changes before they affect your service.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-service-upstream-removed
+    when:
+      - producer_removed
+    resources:
+      - consumes:PaymentService
+    actions:
+      - type: console
+      - type: webhook
+        url: $PAGERDUTY_WEBHOOK_URL
+```
+
+A collection of examples of common governance configurations you can copy and adapt.
+
+## Alert when a message gets a new consumer
+
+Useful when you own a message and want to know when other teams start depending on it.
+
+```yaml title="governance.yaml"
+rules:
+  - name: new-consumer-for-payment-processed
+    when:
+      - consumer_added
+    resources:
+      - message:PaymentProcessed
+    actions:
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Alert when a message gets a new producer
+
+Useful for messages that should only ever have one authoritative producer.
+
+```yaml title="governance.yaml"
+rules:
+  - name: new-producer-for-order-created
+    when:
+      - producer_added
+    resources:
+      - message:OrderCreated
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+
+
+## Track all changes across the catalog
+
+The `"*"` wildcard matches every consumer and producer change. Useful for audit logs or a central ops channel.
+
+```yaml title="governance.yaml"
+rules:
+  - name: catalog-wide-relationship-changes
+    when:
+      - consumer_added
+      - consumer_removed
+      - producer_added
+      - producer_removed
+    resources:
+      - "*"
+    actions:
+      - type: webhook
+        url: $AUDIT_WEBHOOK_URL
+```
+
+## Monitor all changes for a specific service
+
+Use the `service:` prefix to watch any consuming or producing change that involves a named service, regardless of which message is affected.
+
+```yaml title="governance.yaml"
+rules:
+  - name: notification-service-changes
+    when:
+      - consumer_added
+      - consumer_removed
+      - producer_added
+      - producer_removed
+    resources:
+      - service:NotificationService
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Get notified when a message your service consumes is deprecated
+
+Use `consumes:` with `message_deprecated` to alert your team when an upstream producer deprecates a message you depend on. This is the most useful deprecation pattern for consumer teams.
+
+```yaml title="governance.yaml"
+rules:
+  - name: alert-deprecated-messages
+    when:
+      - message_deprecated
+    resources:
+      - "consumes:InventoryService"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Watch a specific message for deprecation
+
+Use `message:` to monitor a single message across any of its producers.
+
+```yaml title="governance.yaml"
+rules:
+  - name: watch-order-placed-deprecation
+    when:
+      - message_deprecated
+    resources:
+      - "message:OrderPlaced"
+    actions:
+      - type: webhook
+        url: $TEAM_WEBHOOK_URL
+```
+
+## Track all deprecations across the catalog
+
+The `"*"` wildcard catches every deprecation in the catalog. Useful for a central ops channel or audit log.
+
+```yaml title="governance.yaml"
+rules:
+  - name: catalog-wide-deprecation-alerts
+    when:
+      - message_deprecated
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $AUDIT_WEBHOOK_URL
+```
+
+## Alert when a message schema changes
+
+Use `schema_changed` to detect when the schema file for any message is added, modified, or replaced. This is useful for catching breaking changes before they propagate to consumers.
+
+```yaml title="governance.yaml"
+rules:
+  - name: schema-change-alerts
+    when:
+      - schema_changed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Alert when a schema changes for messages your service consumes
+
+Use `consumes:` with `schema_changed` to scope alerts to only the messages your service depends on.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-service-schema-changes
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+    actions:
+      - type: webhook
+        url: $PAGERDUTY_WEBHOOK_URL
+```
+
+## Watch a specific message for schema changes
+
+Use `message:` to monitor schema changes for a single message across any of its producers.
+
+```yaml title="governance.yaml"
+rules:
+  - name: order-created-schema-watch
+    when:
+      - schema_changed
+    resources:
+      - message:OrderCreated
+    actions:
+      - type: console
+      - type: webhook
+        url: $TEAM_WEBHOOK_URL
+```
+
+## Block CI when a payment-critical schema changes
+
+Combine `type: fail` with `schema_changed` and service-scoped resource filters to require sign-off before a schema change can merge.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+      - consumes:BillingService
+      - message:PaymentProcessed
+      - message:OrderCreated
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_ALERTS_WEBHOOK
+        headers:
+          Authorization: Bearer $SLACK_TOKEN
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+## Block CI when a consumer is silently removed
+
+Use `consumer_removed` with `type: fail` to ensure consumer removals are never merged without a migration ticket.
+
+```yaml title="governance.yaml"
+rules:
+  - name: consumer-removal-guard
+    when:
+      - consumer_removed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: fail
+        message: "Removing a consumer is a breaking change. Open a migration ticket first."
+```
+
+## Block CI on deprecation without a replacement
+
+Pair `message_deprecated` with `type: fail` to enforce that deprecations are reviewed before merging.
+
+```yaml title="governance.yaml"
+rules:
+  - name: deprecation-review-gate
+    when:
+      - message_deprecated
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: fail
+        message: "Deprecations require a migration guide before merging. See CONTRIBUTING.md."
+```
+
+## Notify on some changes, block on others
+
+Rules without `type: fail` always exit `0`, so you can mix notification-only rules with blocking rules in the same file.
+
+```yaml title="governance.yaml"
+rules:
+  # Blocks CI — schema changes to payment-critical messages
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+    actions:
+      - type: console
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+
+  # Notifies only — new consumers are welcome but the team wants visibility
+  - name: notify-new-consumers
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_NOTIFICATIONS_WEBHOOK
+```
+
+## Future changes
+
+We are working on adding new change detection features to EventCatalog, if you have any ideas or feedback please let us know on [Discord](https://eventcatalog.dev/discord) or raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).

package/dist/docs/development/governance/architecture-change-detection/04-webhooks.md

@@ -0,0 +1,187 @@
+---
+sidebar_position: 4
+sidebar_label: Webhook Payload
+title: Webhook Payload
+description: CloudEvents 1.0 payload format sent by governance webhook actions
+---
+
+## Payload format
+
+Webhook actions send a POST request in [CloudEvents 1.0](https://cloudevents.io/) format. Each matched change produces a separate request.
+
+```json
+{
+  "specversion": "1.0",
+  "type": "eventcatalog.governance.consumer_added",
+  "source": "eventcatalog/governance",
+  "id": "uuid",
+  "time": "2026-03-04T12:00:00.000Z",
+  "datacontenttype": "application/json",
+  "data": {
+    "schemaVersion": 1,
+    "summary": "NotificationService is now consuming the event OrderConfirmed",
+    "consumer": {
+      "id": "NotificationService",
+      "version": "0.0.2"
+    },
+    "message": {
+      "id": "OrderConfirmed",
+      "version": "0.0.1",
+      "type": "event"
+    }
+  }
+}
+```
+
+## CloudEvents envelope
+
+| Field | Value |
+|---|---|
+| `specversion` | Always `"1.0"` |
+| `type` | `eventcatalog.governance.<trigger>`, one of `consumer_added`, `consumer_removed`, `producer_added`, `producer_removed`, `message_deprecated`, `schema_changed` |
+| `source` | `eventcatalog/governance` |
+| `id` | Unique UUID per request |
+| `time` | ISO 8601 timestamp |
+| `datacontenttype` | `application/json` |
+
+## Data object
+
+| Field | Description |
+|---|---|
+| `schemaVersion` | Always `1` (reserved for future format changes) |
+| `status` | Only present when `--status` is passed to the CLI |
+| `summary` | Human-readable description of the change |
+| `consumer` or `producer` | The service involved. `consumer` for consumer triggers, `producer` for producer and `message_deprecated` triggers |
+| `message` | The message involved, including its `type` (`event`, `command`, or `query`) |
+| `schema` | Only present for `schema_changed`. Contains `beforeHash`, `afterHash`, `beforePath`, and `afterPath` |
+| `consumers` | Only present for `schema_changed`. Array of services that consume the changed message |
+| `producers` | Only present for `schema_changed`. Array of services that produce the changed message |
+| `refs` | Only present for `schema_changed`. Contains `base` and `target` branch labels |
+
+## Producer triggers
+
+For `producer_added` and `producer_removed`, the `consumer` field is replaced with `producer`:
+
+```json
+{
+  "data": {
+    "schemaVersion": 1,
+    "summary": "OrdersService is now producing the event OrderCreated",
+    "producer": {
+      "id": "OrdersService",
+      "version": "1.0.0"
+    },
+    "message": {
+      "id": "OrderCreated",
+      "version": "1.0.0",
+      "type": "event"
+    }
+  }
+}
+```
+
+## Deprecation trigger
+
+For `message_deprecated`, the payload identifies the producing service and the deprecated message. One webhook fires per producing service, so if a message has multiple producers, each producer sends a separate request.
+
+```json
+{
+  "specversion": "1.0",
+  "type": "eventcatalog.governance.message_deprecated",
+  "source": "eventcatalog/governance",
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "time": "2026-03-05T14:30:00.000Z",
+  "datacontenttype": "application/json",
+  "data": {
+    "schemaVersion": 1,
+    "summary": "OrderCreated (event) has been deprecated by OrdersService",
+    "producer": {
+      "id": "OrdersService",
+      "version": "2.0.0",
+      "owners": ["team-orders"]
+    },
+    "message": {
+      "id": "OrderCreated",
+      "version": "1.0.0",
+      "type": "event"
+    }
+  }
+}
+```
+
+The `owners` field is only present when the producing service has owners defined. The trigger fires only for newly deprecated messages: existing deprecations and un-deprecations do not fire.
+
+## Schema changed trigger
+
+For `schema_changed`, the payload includes a `schema` object with hashes and paths for the before and after versions, plus arrays of the affected consumer and producer services. One webhook fires per changed message.
+
+```json
+{
+  "specversion": "1.0",
+  "type": "eventcatalog.governance.schema_changed",
+  "source": "eventcatalog/governance",
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "time": "2026-03-05T14:30:00.000Z",
+  "datacontenttype": "application/json",
+  "data": {
+    "schemaVersion": 1,
+    "summary": "Schema changed for event OrderCreated",
+    "message": {
+      "id": "OrderCreated",
+      "version": "1.0.0",
+      "type": "event"
+    },
+    "schema": {
+      "beforeHash": "abc123",
+      "afterHash": "def456",
+      "beforePath": "schemas/order-created.v1.json",
+      "afterPath": "schemas/order-created.v2.json"
+    },
+    "refs": {
+      "base": "main",
+      "target": "feature/update-schema"
+    },
+    "producers": [
+      { "id": "OrdersService", "version": "1.0.0", "owners": ["team-orders"] }
+    ],
+    "consumers": [
+      { "id": "PaymentService", "version": "1.0.0", "owners": ["team-payments"] }
+    ]
+  }
+}
+```
+
+The `schema.beforeHash` and `schema.afterHash` are SHA-256 hashes of the schema file content. Either side can be `null` when a schema is first added or removed. The `owners` field on each service is only present when owners are defined.
+
+## Status field
+
+When you pass `--status` to the CLI, the value is included in the payload. This is useful for distinguishing between stages in a pull request lifecycle.
+
+```bash
+eventcatalog governance check --status proposed
+```
+
+```json
+{
+  "data": {
+    "schemaVersion": 1,
+    "status": "proposed",
+    "summary": "NotificationService is now consuming the event OrderConfirmed",
+    "consumer": { "id": "NotificationService", "version": "0.0.2" },
+    "message": { "id": "OrderConfirmed", "version": "0.0.1", "type": "event" }
+  }
+}
+```
+
+## Custom headers
+
+Headers support environment variable substitution using `$VAR_NAME` syntax.
+
+```yaml
+actions:
+  - type: webhook
+    url: $SLACK_WEBHOOK_URL
+    headers:
+      Authorization: Bearer $API_TOKEN
+      X-Custom-Header: my-value
+```

package/dist/docs/development/governance/architecture-change-detection/05-ci-cd.md

@@ -0,0 +1,121 @@
+---
+sidebar_position: 5
+sidebar_label: CLI & CI/CD
+title: CLI & CI/CD
+description: Run governance checks locally and in your CI/CD pipeline
+---
+
+## Run the check
+
+Run the check from inside your catalog directory. By default it compares the current working directory against the `main` branch.
+
+```bash
+eventcatalog governance check
+```
+
+#### Testing locally
+
+To test locally, make changes to your catalog locally and then run the governance check command.
+
+```sh
+eventcatalog governance check --target main
+```
+
+This will compare the current working directory against the specified branch.
+
+## CLI options
+
+| Option | Description | Default |
+|---|---|---|
+| `--base <branch>` | Base branch to compare against | `main` |
+| `--target <branch>` | Target branch to compare (instead of working directory) | working directory |
+| `--format json` | Output results as JSON | text |
+| `--status <label>` | Status label included in webhook payloads (e.g. `proposed`, `approved`) | none |
+
+### Compare two branches
+
+```bash
+eventcatalog governance check --base main --target feature/new-consumers
+```
+
+### Output JSON
+
+```bash
+eventcatalog governance check --format json
+```
+
+### Include a status label
+
+The `--status` flag adds a `status` field to webhook payloads, useful when running governance checks at different stages of a pull request lifecycle.
+
+```bash
+eventcatalog governance check --status proposed
+```
+
+## GitHub Actions
+
+### Proposed changes
+
+When you want to notify your teams of incoming changes (not merged yet), you can use the `--status proposed` flag to mark the changes as proposed.
+
+This example workflow will notify your teams of incoming changes (not merged yet). The status `proposed` will be included in the webhook payload.
+
+```yaml title=".github/workflows/governance.yaml"
+name: EventCatalog Governance
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+      # Fetch the base branch (e.g. main or whatever you want to compare against)
+      - run: git fetch origin main
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: |
+          npx @eventcatalog/cli governance check \
+            --base main \
+            --target ${{ github.head_ref }} \
+            --status proposed
+        env:
+          EVENTCATALOG_SCALE_LICENSE_KEY: ${{ secrets.EVENTCATALOG_SCALE_LICENSE_KEY }}
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+```
+
+### Approved changes
+
+When a pull request is merged to the base branch, you can run the check again with `--status approved` to notify teams that the change is confirmed.
+
+This example workflow will notify your teams that the change is confirmed. The status `approved` will be included in the webhook payload.
+
+```yaml title=".github/workflows/governance.yaml"
+name: EventCatalog Governance
+on: merge
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.base_ref }} 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: |
+          npx @eventcatalog/cli governance check \
+            --base main \
+            --target ${{ github.base_ref }} \
+            --status approved
+        env:
+          EVENTCATALOG_SCALE_LICENSE_KEY: ${{ secrets.EVENTCATALOG_SCALE_LICENSE_KEY }}
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+```