@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/developer-tools/github-action.md

@@ -0,0 +1,147 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog components
+sidebar_label: AI Reviewer
+title: AI Reviewer
+description: Integrate EventCatalog with GitHub Actions
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+
+<EventCatalogPro />
+
+
+
+The [EventCatalog GitHub Action](https://github.com/event-catalog/github-action) brings AI-powered insight into your Git workflows. It uses large language models (LLMs) to automatically review changes to your EventCatalog, helping you catch issues early—before they reach production. You can pick from OpenAI, Anthropic, or Google.
+
+Think of it as a smart assistant for your pull requests. It doesn't just lint code—it understands the implications of your changes.
+
+<details>
+<summary>Watch the video to see the GitHub Action in action</summary>
+
+<iframe width="100%" height="
+515" src="https://www.youtube.com/embed/xAQ20eAfKsI?si=ZNQMEcAkDSjfIa3b" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</details>
+
+**What it does:**
+
+- Detect breaking changes in schemas during pull requests
+- Score how likely a change is to cause issues
+- List affected consumers so you know who’s impacted
+- Recommend actions to resolve problems before merging
+
+By automating the review process, this GitHub Action saves your team hours of manual effort, reduces human error, and brings consistency to your EventCatalog maintenance.
+
+You’re always in control—the final merge decision is still up to you. But now, you’ll have the insights to make it with confidence.
+
+
+<img src="/img/github-actions.png" alt="EventCatalog GitHub Action" />
+
+### Functionality
+
+The GitHub action supports many different tasks, and you can use the same action for multiple tasks.
+
+Tasks:
+
+- [schema_review](./github-action.md#task-automated-schema-reviews):
+  -  Automatically review the schemas for breaking changes in your pull requests
+
+_More tasks will be added in the future_
+
+
+
+
+---
+
+### Task: Automated schema reviews
+
+The schema review task is used to review schemas for breaking changes. This task let's you catch breaking changes in your schemas before they are deployed.
+
+The schema review supports any schema format, including (JSON, Avro, Protobuf, Thrift, etc.).
+
+<img src="/img/github-actions.png" alt="EventCatalog GitHub Action" width="30%" />
+
+
+
+**Why use the schema review task?**
+
+- Capture breaking changes in your schemas before they are deployed
+- Get a score of how likely the changes are to be breaking
+- See a list of consumers that will be affected by the changes
+- Take action to fix breaking changes before they are deployed
+
+**Workflow example:**
+
+1. Your team member makes a change to a schema in EventCatalog (inside your events, queries or commands folders)
+1. The action will review the schema for breaking changes using your configured LLM (OpenAI, Anthropic, Google)
+1. The action will return a summary of changes, and give you a score of how likely the changes are to be breaking
+1. The action will list affected consumers so you know who’s impacted
+1. Your team member is still in control of the merge decision, but now has the information to make a more informed decision
+
+#### Setup
+
+:::info EventCatalog Scale License
+The GitHub action requires an EventCatalog Scale License. 
+You can get a 14 day free trial from [EventCatalog Cloud](https://eventcatalog.dev/cloud).
+:::
+
+Set your EventCatalog Scale License key in the `license_key` parameter. We recommend storing the `license_key` value as a GitHub secret.
+
+To use the EventCatalog GitHub Action, create a new .github/workflows/eventcatalog-ci.yaml file in your repository with the following content:
+
+```yaml title=".github/workflows/eventcatalog-ci.yaml"
+name: EventCatalog CI
+on:
+  push:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+  delete:
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  schema_review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: event-catalog/github-action@main
+        with:
+          # The task to run, currently only schema_review is supported
+          task: schema_review
+          # The AI LLM provider to use (openai, anthropic, google)
+          provider: openai
+
+          # The model to use for the task, defaults to o4-mini
+          # Find the models in the documentation below
+          model: o4-mini
+
+          # Your API KEY for the LLM provider
+          api_key: ${{ secrets.OPENAI_API_KEY }}
+          
+          # Your EventCatalog Scale License key
+          license_key: ${{ secrets.EVENT_CATALOG_LICENSE_KEY }}
+
+          # Your GitHub token
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+```
+
+#### Configuration options
+
+<!-- Table with configuration options -->
+
+| Parameter | Description | Required | Default |
+|-----------|-------------|----------|---------|
+| `task` | The task to run, currently only `schema_review` is supported | Yes | N/A |
+| `catalog_directory` | The directory where the EventCatalog files are located. Useful for monorepos. By default, the action will review all files in the repository. If you have EventCatalog in a subdirectory, you can specify the directory here. | No | `./` |
+| `failure_threshold` | The score below which the action will fail. The score is a number between 0 and 100. The default is 25. The LLM will return a score between 0 and 100, based on the likelihood of the changes being breaking. | No | 25 |
+| `provider` | The AI LLM provider to use (openai, anthropic, google) | Yes | openai |
+| `model` | The model to use for the task, defaults to `o4-mini`. See the list of supported models: [OpenAI models](https://github.com/event-catalog/github-action/blob/bf92166b4e4c9414caf63e88bc7a315467b506b6/src/ai-models/openai.ts#L4), [Anthropic models](https://github.com/event-catalog/github-action/blob/bf92166b4e4c9414caf63e88bc7a315467b506b6/src/ai-models/anthropic.ts#L4), [Google models](https://github.com/event-catalog/github-action/blob/bf92166b4e4c9414caf63e88bc7a315467b506b6/src/ai-models/google.ts#L4) |Yes | o4-mini |
+| `api_key` | Your API KEY for the LLM provider | Yes | N/A |
+| `license_key` | Your EventCatalog Scale License key | Yes | N/A |
+
+#### Got an issue?
+
+If you have any issues with the GitHub action, please [open an issue](https://github.com/event-catalog/github-action) on the GitHub action repository.

package/dist/docs/development/developer-tools/llms.txt.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 3
+keywords:
+- mermaid
+sidebar_label: llms.txt
+title: LLMS.txt
+description: Understanding how to use LLMS.txt with EventCatalog and your LLMs
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.20.0" />
+
+Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly understand your EventCatalog.
+
+### What is LLMS.txt?
+
+[LLMS.txt](https://llmstxt.org/) is a proposed standard that helps AI-powered development tools better understand and interact with your documentation. Similar to how robots.txt guides web crawlers, LLMS.txt provides structured information that makes it easier for AI assistants like Claude, ChatGPT, and GitHub Copilot to process your EventCatalog documentation.
+
+The file is automatically generated and maintained as part of your documentation pipeline, requiring no manual configuration. It organizes your documentation's key concepts, structures, and relationships in a format optimized for machine reading.
+
+### llms.txt and llms-full.txt
+
+The `llms.txt` file includes your EventCatalog resources in a simple format. Lists your resources with a summary for each of them.
+
+The `llms-full.txt` file includes your EventCatalog resources in a more detailed format. All the contents of your Catalog resources are included in the file.
+
+### Enable in EventCatalog
+
+**`llms.txt` is enabled by default in EventCatalog.**
+
+You can disable it by turning it off in your `eventcatalog.config.js` file.
+
+```js title="eventcatalog.config.js"
+llmsTxt: {
+    enabled: false,
+},
+```
+
+Once you enable llms.txt you can query both the urls:
+ - `https://<your-catalog-url>/docs/llm/llms.txt`
+    - Demo: https://demo.eventcatalog.dev/docs/llm/llms.txt
+ - `https://<your-catalog-url>/docs/llm/llms-full.txt`
+    - Demo: https://demo.eventcatalog.dev/docs/llm/llms-full.txt
+
+### How to use LLMS.txt?
+
+Once you deploy your EventCatalog you can use your tools to ask questions about your Catalog.
+
+![LLMS.txt](./img/ai-example.png)
+
+
+
+
+

package/dist/docs/development/developer-tools/schemas.txt.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 3
+keywords:
+- mermaid
+sidebar_label: schemas.txt
+title: schemas.txt
+description: Understanding how to use schemas.txt with EventCatalog and your schemas
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.64.0" />
+
+Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly fetch and understand your EventCatalog schemas.
+
+Message schemas and service specifications can be fetched from your EventCatalog and used in your own applications.
+
+### What is schemas.txt?
+
+Schemas.txt is very similar to [LLMS.txt](/docs/development/developer-tools/llms.txt), but it is specifically for schemas in your EventCatalog. 
+
+Schemas.txt supports any schema format for your messages (e.g Avro, Protobuf, JSON Schema etc) and any specification for your services (e.g OpenAPI, AsyncAPI, GraphQL etc).
+
+The schemas.txt file is automatically generated and maintained as part of your documentation pipeline, requiring no manual configuration. It organizes your schemas in a format optimized for machine reading.
+
+### schemas.txt and schemas-full.txt
+
+The `schemas.txt` file includes your EventCatalog schemas in a simple format. Lists your schemas with a summary for each of them.
+
+### How to use schemas.txt?
+
+The [EventCatalog MCP](/docs/development/ask-your-architecture/mcp-server/introduction) already uses the schemas.txt file to provide access to your schemas in your MCP clients (e.g Cursor, Windsurf, Claude Desktop etc).
+
+If you want to use schemas.txt in your own application, you can query the urls:
+
+ - `https://<your-catalog-url>/docs/llm/schemas.txt`
+    - Demo: https://demo.eventcatalog.dev/docs/llm/schemas.txt
+
+
+
+
+

package/dist/docs/development/governance/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Governance Patterns",
+  "position": 9,
+  "collapsible": true,
+  "collapsed": false
+}

package/dist/docs/development/governance/architecture-change-detection/01-introduction.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+title: Architecture Change Detection
+description: Know when your event-driven architecture changes. Get notified when services start or stop producing and consuming messages.
+---
+
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+
+<EventCatalogPro />
+
+Services get added. Consumers change. Producers disappear. In event-driven systems, these relationship changes often go unnoticed until something breaks downstream.
+
+**Architecture Change Detection** compares your catalog across branches and tells you exactly what changed: which services started consuming a message, which stopped producing one, and who is affected.
+
+You can configure webhooks to send notifications to tools like Slack or PagerDuty when changes are detected, including relationship changes, deprecations, and schema updates. Rules can also be configured to block CI/CD pipelines entirely using the `fail` action.
+
+:::info Scale plan required
+Architecture Change Detection requires an [EventCatalog Scale plan](https://eventcatalog.dev/pricing).
+:::
+
+## How it works
+
+1. Define rules in `governance.yaml` at the root of your catalog
+2. Each rule specifies **triggers** (what kind of change to detect), **resources** (which services or messages to watch), and **actions** (how to get notified)
+3. Run `eventcatalog governance check` to compare your catalog against a base branch
+4. Matched changes print to the console, fire webhook notifications, and optionally exit with a non-zero code to block merges
+
+```mermaid
+flowchart LR
+    A[governance.yaml] --> B[eventcatalog governance check]
+    B --> C{Compare branches}
+    C --> D[Detect changes]
+    D --> E[Console output]
+    D --> F[Webhook notifications]
+    D --> G[Fail action — exit code 1]
+```
+
+## Quick example
+
+```yaml title="governance.yaml"
+rules:
+  - name: notify-consumer-changes
+    when:
+      - consumer_added
+      - consumer_removed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+This rule detects whenever any service starts or stops consuming any message, and sends a notification to Slack.
+
+## Notifications when you want them
+
+Using the [`status` field](/docs/development/governance/architecture-change-detection/ci-cd#include-a-status-label) you can choose to detect changes that are proposed vs approved. This can be useful when you want to detect changes that are proposed vs approved in your architecture.
+
+
+

package/dist/docs/development/governance/architecture-change-detection/02-configuration.md

@@ -0,0 +1,134 @@
+---
+sidebar_position: 2
+sidebar_label: Configuration
+title: Configuration
+description: Configure governance rules with triggers, resource filters, and actions
+---
+
+## Create a config file
+
+Add a `governance.yaml` file to the root of your catalog directory. Each rule has a name, a list of triggers, a resource filter, and one or more actions.
+
+```yaml title="governance.yaml"
+rules:
+  # Name of your rule
+  - name: notify-consumer-changes
+    # List of triggers
+    when:
+      - consumer_added
+      - consumer_removed
+    # Configure which resources to watch
+    # * is everything
+    resources:
+      - "*"
+    # List of actions to perform
+    actions:
+      # Print to the console
+      - type: console
+      # Send a webhook to a Slack or PagerDuty webhook
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+        headers:
+          Authorization: Bearer $API_TOKEN
+```
+
+## Triggers
+
+The `when` field lists the events that activate a rule. Relationship triggers compare the target state against the base branch. The `message_deprecated` and `schema_changed` triggers inspect the target branch directly.
+
+| Trigger | Description |
+|---|---|
+| `consumer_added` | A service starts receiving a message |
+| `consumer_removed` | A service stops receiving a message |
+| `producer_added` | A service starts sending a message |
+| `producer_removed` | A service stops sending a message |
+| `message_deprecated` | A producing service marks a message as deprecated |
+| `schema_changed` | A message schema file is added, modified, or replaced |
+
+A single rule can listen to multiple triggers:
+
+```yaml
+when:
+  - consumer_added
+  - consumer_removed
+```
+
+## Resource filters
+
+The `resources` field controls which changes are checked against the rule. Each entry uses a prefix to specify what to match.
+
+| Prefix | Example | Matches |
+|---|---|---|
+| `"*"` | `"*"` | All changes across the catalog |
+| `"message:<id>"` | `"message:OrderCreated"` | Changes involving a specific message |
+| `"service:<id>"` | `"service:NotificationService"` | Changes where the named service is the consumer or producer |
+| `"produces:<service>"` | `"produces:OrdersService"` | Changes involving any message that the named service sends |
+| `"consumes:<service>"` | `"consumes:PaymentService"` | Changes involving any message that the named service receives. For `message_deprecated` and `schema_changed`, matches messages consumed by the named service |
+
+You can combine multiple filters in one rule. A change matches if it matches **any** entry:
+
+```yaml
+resources:
+  - message:OrderCreated
+  - message:OrderConfirmed
+  - service:NotificationService
+```
+
+## Actions
+
+Each rule can trigger one or more actions when its conditions are met.
+
+### Console
+
+Prints a summary of matched changes to the terminal. No additional configuration required.
+
+```yaml
+actions:
+  - type: console
+```
+
+### Webhook
+
+Sends a POST request in [CloudEvents 1.0](https://cloudevents.io/) format to the specified URL. Custom headers are supported.
+
+_You can use [Webhook Sites](https://webhook.site) to test your webhook URLs. Don't share any sensitive information in the payload._
+
+```yaml
+actions:
+  - type: webhook
+    url: $SLACK_WEBHOOK_URL
+    headers:
+      Authorization: Bearer $API_TOKEN
+```
+
+See [Webhook Payload](/docs/development/governance/architecture-change-detection/webhooks) for the full payload format.
+
+### Fail
+
+Exits the CLI with code `1`, failing the CI/CD step and blocking the pipeline. An optional `message` field provides a human-readable reason shown in the terminal output.
+
+```yaml
+actions:
+  - type: fail
+    message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+The `message` field supports `$ENV_VAR` interpolation. A rule can include multiple `fail` actions; all messages are collected and printed together before the process exits.
+
+If no triggered rule has a `fail` action, the CLI exits with code `0` regardless of how many rules fired. This means adding `type: fail` to specific rules is a non-breaking, opt-in change.
+
+See [Pipeline gates](/docs/development/governance/architecture-change-detection/pipeline-gates) for full examples of blocking CI/CD with governance rules.
+
+## Environment variables
+
+Webhook URLs and header values can reference environment variables using the `$VAR_NAME` syntax. The CLI loads your catalog's `.env` file automatically, so you can keep secrets out of `governance.yaml`.
+
+```yaml
+actions:
+  - type: webhook
+    url: $SLACK_WEBHOOK_URL
+    headers:
+      Authorization: Bearer $API_TOKEN
+```
+
+If a referenced variable is not set at runtime, the command exits with an error.