@eventcatalog/core 5.8.0 → 5.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/analytics/analytics.cjs +1 -1
- package/dist/analytics/analytics.js +2 -2
- package/dist/analytics/log-build.cjs +1 -1
- package/dist/analytics/log-build.js +3 -3
- package/dist/{chunk-E636DOFG.js → chunk-3PWCUWQC.js} +1 -1
- package/dist/{chunk-DT63JMNP.js → chunk-A3256YCN.js} +3 -2
- package/dist/{chunk-WLXXZTLD.js → chunk-JDSFD7IC.js} +1 -1
- package/dist/{chunk-YU6FEGOK.js → chunk-KGFAIGOT.js} +1 -1
- package/dist/{chunk-Z6UUCTIB.js → chunk-YBM7MCOY.js} +1 -1
- package/dist/constants.cjs +1 -1
- package/dist/constants.js +1 -1
- package/dist/docs/api/02-config.md +1 -1
- package/dist/docs/development/00-why-eventcatalog.md +15 -8
- package/dist/docs/development/01-adopting-eventcatalog.md +51 -0
- package/dist/docs/development/{ask-your-architecture/03-install-skills.md → 01-getting-started/install-skills.md} +10 -4
- package/dist/docs/development/01-getting-started/installation.md +5 -1
- package/dist/docs/development/ask-your-architecture/01-intro.md +21 -6
- package/dist/docs/development/ask-your-architecture/03-mcp-server/getting-started.md +17 -3
- package/dist/docs/development/ask-your-architecture/03-mcp-server/introduction.md +3 -0
- package/dist/docs/development/ask-your-architecture/06-sync-docs-with-your-code.md +227 -0
- package/dist/docs/development/ask-your-architecture/07-catch-breaking-changes.md +149 -0
- package/dist/docs/development/ask-your-architecture/08-check-code-against-adrs.md +169 -0
- package/dist/docs/development/components/custom-components/02-create-your-first-component.md +4 -0
- package/dist/docs/development/customization/customize-visualizer/00-visualizer-nodes.md +7 -5
- package/dist/docs/development/developer-tools/api-catalog.md +1 -1
- package/dist/docs/development/{ask-your-architecture/02-llms.txt.md → developer-tools/llms.txt.md} +2 -0
- package/dist/docs/development/{ask-your-architecture/03-schemas.txt.md → developer-tools/schemas.txt.md} +1 -1
- package/dist/docs/development/developer-tools/ubiquitous-language.txt.md +42 -0
- package/dist/docs/development/guides/domains/03-ownership-and-language/02-adding-ubiquitous-language.md +3 -0
- package/dist/docs/development/guides/resources/adrs/01-introduction.md +1 -0
- package/dist/eventcatalog.cjs +6 -5
- package/dist/eventcatalog.js +8 -8
- package/dist/generate.cjs +3 -2
- package/dist/generate.js +3 -3
- package/dist/utils/cli-logger.cjs +1 -1
- package/dist/utils/cli-logger.js +2 -2
- package/eventcatalog/auth.config.ts +7 -9
- package/eventcatalog/src/components/Settings/LlmAccessSettingsForm.tsx +23 -3
- package/eventcatalog/src/features/ai/chat-api.ts +2 -4
- package/eventcatalog/src/features/auth/login.astro +2 -4
- package/eventcatalog/src/features/auth/middleware/middleware-auth.ts +1 -0
- package/eventcatalog/src/features/auth/middleware/middleware.ts +2 -3
- package/eventcatalog/src/features/mcp/apps/generated/viewer.html +1 -1
- package/eventcatalog/src/features/mcp/mcp-scoped-tools.ts +7 -4
- package/eventcatalog/src/features/mcp/mcp-server.ts +15 -2
- package/eventcatalog/src/features/tools/catalog-tools.ts +97 -30
- package/eventcatalog/src/pages/docs/llm/llms.txt.ts +24 -17
- package/eventcatalog/src/pages/docs/llm/schemas.txt.ts +1 -1
- package/eventcatalog/src/pages/docs/llm/ubiquitous-language.txt.ts +68 -0
- package/eventcatalog/src/pages/settings/llm-access.astro +2 -0
- package/eventcatalog/src/utils/catalog-modules.ts +16 -0
- package/eventcatalog/src/utils/collections/domains.ts +84 -0
- package/package.json +2 -2
- package/dist/docs/development/ask-your-architecture/04-agents/01-overview.md +0 -27
- package/dist/docs/development/ask-your-architecture/04-agents/02-code-to-docs.md +0 -124
- package/dist/docs/development/ask-your-architecture/04-agents/03-breaking-changes.md +0 -170
- package/dist/docs/development/ask-your-architecture/04-agents/_category_.json +0 -12
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
---
|
|
2
|
+
sidebar_position: 7
|
|
3
|
+
keywords:
|
|
4
|
+
- Breaking Changes
|
|
5
|
+
- EventCatalog Agents
|
|
6
|
+
- schema governance
|
|
7
|
+
- schema compatibility
|
|
8
|
+
- GitHub Actions
|
|
9
|
+
sidebar_label: Catch breaking changes
|
|
10
|
+
title: Catch breaking changes
|
|
11
|
+
description: The Breaking Changes workflow comments on pull requests when a schema change would break a consumer documented in your EventCatalog, with the consumers and their owners.
|
|
12
|
+
slug: /development/agents/set-up-breaking-changes
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
import { BreakingChangesComment } from '@site/src/components/AgentOutputs';
|
|
16
|
+
import { AgentPrompt } from '@site/src/components/AgentPrompt';
|
|
17
|
+
|
|
18
|
+
The **Breaking Changes** workflow checks the message schemas changed in a pull request. If a change would break consumers documented in your catalog, it comments with what breaks, who is affected, and who owns them, before the change merges. It never edits your catalog.
|
|
19
|
+
|
|
20
|
+
<AgentPrompt variant="breaking-changes" />
|
|
21
|
+
|
|
22
|
+
<BreakingChangesComment />
|
|
23
|
+
|
|
24
|
+
## How it works
|
|
25
|
+
|
|
26
|
+
1. **Finds changed schemas.** It looks for changed schema files in the pull request.
|
|
27
|
+
2. **Checks each change.** A change is breaking when existing consumers could fail: a removed or renamed field, a changed type, a new required field, a narrowed enum, and similar. Additive changes, such as a new optional field, are not breaking.
|
|
28
|
+
3. **Finds the consumers.** It matches the schema to its message in your catalog, then finds every service, agent or domain that receives it at an affected version.
|
|
29
|
+
4. **Comments on the pull request** with the breaking lines and each consumer with its owners.
|
|
30
|
+
|
|
31
|
+
If the pull request changes no schemas, or none of the changes are breaking, it doesn't comment. If a breaking change has no consumers in your catalog, the comment says so.
|
|
32
|
+
|
|
33
|
+
A consumer is affected when it receives the message at its current version, at `latest` or with no version, or at a range that includes the current version, such as `1.x`. Consumers pinned to an older version are listed too, with their version. The reason given for each consumer comes from your catalog, such as "Receives payment-succeeded 1.0.0". The agent doesn't guess how a consumer uses particular fields.
|
|
34
|
+
|
|
35
|
+
## Before you start
|
|
36
|
+
|
|
37
|
+
You need:
|
|
38
|
+
|
|
39
|
+
- An EventCatalog in a GitHub repository (the **catalog repository**), with the catalog at the root of the repository, and the consumers of your messages documented in it.
|
|
40
|
+
- A repository with message schemas (the **source repository**).
|
|
41
|
+
- An API key for an AI model provider.
|
|
42
|
+
|
|
43
|
+
## Setup
|
|
44
|
+
|
|
45
|
+
In your source repository, add two secrets under **Settings → Secrets and variables → Actions**:
|
|
46
|
+
|
|
47
|
+
- `ANTHROPIC_API_KEY`, or the key for [your model provider](#models).
|
|
48
|
+
- `EVENTCATALOG_TOKEN`, a GitHub token that can read your catalog repository. The workflow never writes to it.
|
|
49
|
+
|
|
50
|
+
Then add the workflow. It runs while the pull request is open, so the warning arrives before the change merges:
|
|
51
|
+
|
|
52
|
+
```yaml title=".github/workflows/eventcatalog-breaking-changes.yml"
|
|
53
|
+
on:
|
|
54
|
+
pull_request:
|
|
55
|
+
types: [opened, synchronize, reopened]
|
|
56
|
+
|
|
57
|
+
jobs:
|
|
58
|
+
breaking-changes:
|
|
59
|
+
runs-on: ubuntu-latest
|
|
60
|
+
permissions:
|
|
61
|
+
contents: read
|
|
62
|
+
issues: write
|
|
63
|
+
pull-requests: write
|
|
64
|
+
steps:
|
|
65
|
+
- uses: actions/checkout@v6
|
|
66
|
+
with:
|
|
67
|
+
ref: ${{ github.event.pull_request.head.sha }}
|
|
68
|
+
fetch-depth: 0
|
|
69
|
+
- uses: event-catalog/agents@v2
|
|
70
|
+
env:
|
|
71
|
+
# The key for your model's provider. This one is for the default model.
|
|
72
|
+
# Using another provider? Swap this variable and set `model` below.
|
|
73
|
+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
74
|
+
with:
|
|
75
|
+
# The agent workflow to run.
|
|
76
|
+
agent: breaking-changes
|
|
77
|
+
# Your catalog repository, in owner/repo format.
|
|
78
|
+
catalog-repo: your-org/your-catalog
|
|
79
|
+
# A token that can read your catalog repository.
|
|
80
|
+
catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
|
|
81
|
+
# Optional: the model to use. Defaults to anthropic/claude-sonnet-4-6.
|
|
82
|
+
# model: openai/gpt-5.1
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Replace `your-org/your-catalog` with your catalog repository. Keep `fetch-depth: 0`: the agent needs it to compare the pull request with its base branch.
|
|
86
|
+
|
|
87
|
+
To check it works, open a pull request that removes a field from a schema that a service in your catalog consumes.
|
|
88
|
+
|
|
89
|
+
If you also [sync docs with your code](/docs/development/agents/set-up-code-to-docs), you can run both from one workflow file: add `closed` to the `types`, and give each job an `if`:
|
|
90
|
+
|
|
91
|
+
```yaml
|
|
92
|
+
on:
|
|
93
|
+
pull_request:
|
|
94
|
+
types: [opened, synchronize, reopened, closed]
|
|
95
|
+
|
|
96
|
+
jobs:
|
|
97
|
+
breaking-changes:
|
|
98
|
+
if: github.event.action != 'closed'
|
|
99
|
+
# ... as above
|
|
100
|
+
|
|
101
|
+
code-to-docs:
|
|
102
|
+
if: github.event.action == 'closed' && github.event.pull_request.merged == true
|
|
103
|
+
# ...
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Configuration
|
|
107
|
+
|
|
108
|
+
| Input | Required | Default | Description |
|
|
109
|
+
| --- | --- | --- | --- |
|
|
110
|
+
| `agent` | Yes | | Set to `breaking-changes` to run this workflow. |
|
|
111
|
+
| `catalog-repo` | Yes | | Your catalog repository, in `owner/repo` format. |
|
|
112
|
+
| `catalog-ref` | No | `main` | The catalog branch to read. |
|
|
113
|
+
| `catalog-token` | No | `github.token` | A token that can read the catalog repository. |
|
|
114
|
+
| `catalog-url` | No | | The URL of your hosted catalog. The comment links consumers and owners to it. |
|
|
115
|
+
| `model` | No | `anthropic/claude-sonnet-4-6` | The model the agent uses. See [models](#models). |
|
|
116
|
+
| `schema-extensions` | No | `.json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql` | The file extensions treated as message schemas. |
|
|
117
|
+
| `ignore-paths` | No | Build and dependency folders | Comma-separated paths or glob patterns to leave out of the review. |
|
|
118
|
+
|
|
119
|
+
To check message contracts in other files, such as TypeScript types, set `schema-extensions`. Your list replaces the defaults, so include every extension you want checked:
|
|
120
|
+
|
|
121
|
+
```yaml
|
|
122
|
+
with:
|
|
123
|
+
schema-extensions: .json,.yaml,.ts
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Only add source code extensions for files that contain message contracts: every changed file with a listed extension is checked.
|
|
127
|
+
|
|
128
|
+
## Models
|
|
129
|
+
|
|
130
|
+
Use any model from [these providers](https://pi.dev/models). Set `model` to a provider and model name, and pass your provider's key as an environment variable on the step:
|
|
131
|
+
|
|
132
|
+
| Provider | Model example | Environment variable |
|
|
133
|
+
| --- | --- | --- |
|
|
134
|
+
| Anthropic | `anthropic/claude-sonnet-4-6` | `ANTHROPIC_API_KEY` |
|
|
135
|
+
| OpenAI | `openai/gpt-5.1` | `OPENAI_API_KEY` |
|
|
136
|
+
| OpenRouter | `openrouter/anthropic/claude-sonnet-4.6` | `OPENROUTER_API_KEY` |
|
|
137
|
+
|
|
138
|
+
To use models in your own AWS account, use an `amazon-bedrock/` model, such as `amazon-bedrock/eu.anthropic.claude-sonnet-4-6`, and give the job AWS credentials with [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials).
|
|
139
|
+
|
|
140
|
+
## Data and privacy
|
|
141
|
+
|
|
142
|
+
- **It's read-only.** It only comments on pull requests, and never edits your catalog.
|
|
143
|
+
- **Your code goes to one place:** the model provider you configure. The agent runs in your GitHub Actions runner. EventCatalog never receives your code, your catalog or your pull requests.
|
|
144
|
+
|
|
145
|
+
Each run sends one anonymous usage event: the outcome and the kind of error if it failed, the model, the run's duration, whether the pull request was open or merged, and the repository name. It never contains code, file names, paths, diffs or pull request content. To turn it off, set `POSTHOG_KEY: ''` in the step's `env`.
|
|
146
|
+
|
|
147
|
+
## Versions
|
|
148
|
+
|
|
149
|
+
Use `event-catalog/agents@v2` for the latest v2 release, or an exact release such as `event-catalog/agents@v2.1.0`, which never changes. Releases are listed on [GitHub](https://github.com/event-catalog/agents/tags).
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
---
|
|
2
|
+
sidebar_position: 8
|
|
3
|
+
keywords:
|
|
4
|
+
- ADR Compliance
|
|
5
|
+
- EventCatalog Agents
|
|
6
|
+
- architecture decision records
|
|
7
|
+
- ADR governance
|
|
8
|
+
- GitHub Actions
|
|
9
|
+
sidebar_label: Check code against ADRs
|
|
10
|
+
title: Check code against ADRs
|
|
11
|
+
description: The ADR Compliance workflow comments on pull requests when the code conflicts with an architecture decision documented in your EventCatalog, citing the line and the decision.
|
|
12
|
+
slug: /development/agents/set-up-adr-compliance
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
import { AdrComplianceComment } from '@site/src/components/AgentOutputs';
|
|
16
|
+
import { AgentPrompt } from '@site/src/components/AgentPrompt';
|
|
17
|
+
|
|
18
|
+
The **ADR Compliance** workflow checks the code changed in a pull request against the [architecture decision records](/docs/development/guides/resources/adrs/introduction) in your catalog. You choose which ADRs apply to the repository. If the code clearly conflicts with one, it comments with the line, the decision, and how to fix it. It never edits your catalog or blocks a merge.
|
|
19
|
+
|
|
20
|
+
<AgentPrompt variant="adr-compliance" />
|
|
21
|
+
|
|
22
|
+
### Example
|
|
23
|
+
<AdrComplianceComment />
|
|
24
|
+
|
|
25
|
+
## How it works
|
|
26
|
+
|
|
27
|
+
1. **Selects the ADRs.** It finds the ADRs matching your `adrs` input, and keeps the `accepted` ones at their latest version. If an accepted ADR amends one of them, it's included too, because the decision can't be judged correctly without it.
|
|
28
|
+
2. **Finds the relevant ones.** It compares the ADR summaries with the changes, so only ADRs on the same topic are reviewed in full.
|
|
29
|
+
3. **Reviews the changed lines.** It reports only clear conflicts. Code that follows an ADR, code the pull request didn't change, and comments that merely mention something an ADR rules out are not conflicts. A decision for a domain or system takes precedence over a broader one on the same topic.
|
|
30
|
+
4. **Checks its citations.** The line must be one the pull request changed, and the quoted sentence must be in the ADR. A conflict that fails this check is dropped.
|
|
31
|
+
5. **Comments on the pull request** with each conflict. The comment updates on every push, and says so once the conflicts are gone.
|
|
32
|
+
|
|
33
|
+
If there are no conflicts, it doesn't comment.
|
|
34
|
+
|
|
35
|
+
## Before you start
|
|
36
|
+
|
|
37
|
+
You need:
|
|
38
|
+
|
|
39
|
+
- An EventCatalog in a GitHub repository (the **catalog repository**), with the catalog at the root of the repository, and your decisions documented as [ADRs](/docs/development/guides/resources/adrs/creating-adrs).
|
|
40
|
+
- A repository with the code you want to check (the **source repository**).
|
|
41
|
+
- An API key for an AI model provider.
|
|
42
|
+
|
|
43
|
+
## Setup
|
|
44
|
+
|
|
45
|
+
In your source repository, add two secrets under **Settings → Secrets and variables → Actions**:
|
|
46
|
+
|
|
47
|
+
- `ANTHROPIC_API_KEY`, or the key for [your model provider](#models).
|
|
48
|
+
- `EVENTCATALOG_TOKEN`, a GitHub token that can read your catalog repository. The workflow never writes to it.
|
|
49
|
+
|
|
50
|
+
Then add the workflow. It runs while the pull request is open, so a conflict is raised while the code can still change:
|
|
51
|
+
|
|
52
|
+
```yaml title=".github/workflows/eventcatalog-adr-compliance.yml"
|
|
53
|
+
on:
|
|
54
|
+
pull_request:
|
|
55
|
+
types: [opened, synchronize, reopened]
|
|
56
|
+
|
|
57
|
+
jobs:
|
|
58
|
+
adr-compliance:
|
|
59
|
+
runs-on: ubuntu-latest
|
|
60
|
+
permissions:
|
|
61
|
+
contents: read
|
|
62
|
+
issues: write
|
|
63
|
+
pull-requests: write
|
|
64
|
+
steps:
|
|
65
|
+
- uses: actions/checkout@v6
|
|
66
|
+
with:
|
|
67
|
+
ref: ${{ github.event.pull_request.head.sha }}
|
|
68
|
+
fetch-depth: 0
|
|
69
|
+
- uses: event-catalog/agents@v2
|
|
70
|
+
env:
|
|
71
|
+
# The key for your model's provider. This one is for the default model.
|
|
72
|
+
# Using another provider? Swap this variable and set `model` below.
|
|
73
|
+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
74
|
+
with:
|
|
75
|
+
# The agent workflow to run.
|
|
76
|
+
agent: adr-compliance
|
|
77
|
+
# The ADRs to check against, as globs from your catalog's root.
|
|
78
|
+
# Here: the top-level adrs folder and the Orders domain.
|
|
79
|
+
adrs: adrs/**, domains/Orders/**
|
|
80
|
+
# Your catalog repository, in owner/repo format.
|
|
81
|
+
catalog-repo: your-org/your-catalog
|
|
82
|
+
# A token that can read your catalog repository.
|
|
83
|
+
catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
|
|
84
|
+
# Optional: the model to use. Defaults to anthropic/claude-sonnet-4-6.
|
|
85
|
+
# model: openai/gpt-5.1
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Replace `your-org/your-catalog` with your catalog repository, and set `adrs` to the [ADRs that apply to this repository](#choose-which-adrs-to-check). Keep `fetch-depth: 0`: the agent needs it to compare the pull request with its base branch.
|
|
89
|
+
|
|
90
|
+
To check it works, open a pull request that does something one of your accepted ADRs rules out.
|
|
91
|
+
|
|
92
|
+
## Choose which ADRs to check
|
|
93
|
+
|
|
94
|
+
The `adrs` input is required. It takes comma-separated globs, relative to the root of your catalog. ADRs can live in any `adrs` folder in your catalog, so point the globs at wherever yours are:
|
|
95
|
+
|
|
96
|
+
| To check against | Use |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| ADRs in the top-level `adrs` folder | `adrs/**` |
|
|
99
|
+
| A domain, and everything nested in it | `domains/Orders/**` |
|
|
100
|
+
| One system | `domains/Orders/systems/checkout-system/**` |
|
|
101
|
+
| One service | `domains/Orders/services/OrdersAPI/**` |
|
|
102
|
+
| ADRs that share a naming convention | `adrs/adr-orders-*/**` |
|
|
103
|
+
| One ADR | `adrs/adr-012-use-outbox` |
|
|
104
|
+
| Every ADR in the catalog | `'**/adrs/**'` |
|
|
105
|
+
|
|
106
|
+
A typical repository checks against your organization-wide ADRs and those of its own domain:
|
|
107
|
+
|
|
108
|
+
```yaml
|
|
109
|
+
with:
|
|
110
|
+
adrs: adrs/**, domains/Orders/**
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Globs start at the catalog root, so `adrs/**` means only the top-level folder, not every folder called `adrs`. A value that starts with `*` needs quotes in YAML.
|
|
114
|
+
|
|
115
|
+
If `adrs` is missing or matches no ADRs, the run fails with an error that shows where your ADRs are, so a typo can't look like a clean pass.
|
|
116
|
+
|
|
117
|
+
:::tip
|
|
118
|
+
Checking every ADR in the catalog can raise conflicts with decisions meant for other teams. Start with the ADRs that apply to the repository.
|
|
119
|
+
:::
|
|
120
|
+
|
|
121
|
+
## Record an exception
|
|
122
|
+
|
|
123
|
+
If a conflict is intentional, add a line to the pull request description with the ADR's `id` and your reason:
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
adr-exception: adr-003-offload-async-work-to-worker small thumbnails only
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The conflict then moves to an exceptions list in the comment, so reviewers can still see it. The agent reads the description when it runs, so push a commit or re-run the workflow after adding the line. To re-run automatically when the description changes, add `edited` to the `types`.
|
|
130
|
+
|
|
131
|
+
A reason is required: a line without one is ignored. Exceptions are visible rather than enforced, so anyone who can edit the description can add one.
|
|
132
|
+
|
|
133
|
+
If the decision itself has changed, propose a new ADR in your catalog instead. See [ADR relationships](/docs/development/guides/resources/adrs/relationships).
|
|
134
|
+
|
|
135
|
+
## Configuration
|
|
136
|
+
|
|
137
|
+
| Input | Required | Default | Description |
|
|
138
|
+
| --- | --- | --- | --- |
|
|
139
|
+
| `agent` | Yes | | Set to `adr-compliance` to run this workflow. |
|
|
140
|
+
| `adrs` | Yes | | Comma-separated globs, relative to the catalog root, selecting the ADRs to check against. |
|
|
141
|
+
| `catalog-repo` | Yes | | Your catalog repository, in `owner/repo` format. |
|
|
142
|
+
| `catalog-ref` | No | `main` | The catalog branch to read. |
|
|
143
|
+
| `catalog-token` | No | `github.token` | A token that can read the catalog repository. |
|
|
144
|
+
| `catalog-url` | No | | The URL of your hosted catalog. The comment links ADRs to it. Without it, they link to your catalog repository. |
|
|
145
|
+
| `model` | No | `anthropic/claude-sonnet-4-6` | The model the agent uses. See [models](#models). |
|
|
146
|
+
| `ignore-paths` | No | Build and dependency folders | Comma-separated paths or glob patterns to leave out of the review. |
|
|
147
|
+
|
|
148
|
+
## Models
|
|
149
|
+
|
|
150
|
+
Use any model from [these providers](https://pi.dev/models). Set `model` to a provider and model name, and pass your provider's key as an environment variable on the step:
|
|
151
|
+
|
|
152
|
+
| Provider | Model example | Environment variable |
|
|
153
|
+
| --- | --- | --- |
|
|
154
|
+
| Anthropic | `anthropic/claude-sonnet-4-6` | `ANTHROPIC_API_KEY` |
|
|
155
|
+
| OpenAI | `openai/gpt-5.1` | `OPENAI_API_KEY` |
|
|
156
|
+
| OpenRouter | `openrouter/anthropic/claude-sonnet-4.6` | `OPENROUTER_API_KEY` |
|
|
157
|
+
|
|
158
|
+
To use models in your own AWS account, use an `amazon-bedrock/` model, such as `amazon-bedrock/eu.anthropic.claude-sonnet-4-6`, and give the job AWS credentials with [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials).
|
|
159
|
+
|
|
160
|
+
## Data and privacy
|
|
161
|
+
|
|
162
|
+
- **It's read-only.** It only comments on pull requests, and never edits your catalog.
|
|
163
|
+
- **Your code goes to one place:** the model provider you configure. The agent runs in your GitHub Actions runner. EventCatalog never receives your code, your catalog or your pull requests.
|
|
164
|
+
|
|
165
|
+
Each run sends one anonymous usage event: the outcome and the kind of error if it failed, the model, the run's duration, whether the pull request was open or merged, and the repository name. It never contains code, file names, paths, diffs or pull request content. To turn it off, set `POSTHOG_KEY: ''` in the step's `env`.
|
|
166
|
+
|
|
167
|
+
## Versions
|
|
168
|
+
|
|
169
|
+
ADR Compliance needs `event-catalog/agents@v2.2.0` or later. Use `event-catalog/agents@v2` for the latest v2 release, or an exact release such as `event-catalog/agents@v2.2.0`, which never changes. Releases are listed on [GitHub](https://github.com/event-catalog/agents/tags).
|
package/dist/docs/development/components/custom-components/02-create-your-first-component.md
CHANGED
|
@@ -5,8 +5,12 @@ title: Create your first component
|
|
|
5
5
|
description: Create a small reusable component and render it in a catalog page.
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
+
import { AgentPrompt } from '@site/src/components/AgentPrompt';
|
|
9
|
+
|
|
8
10
|
In this guide, we will create a simple component and add it to a service page.
|
|
9
11
|
|
|
12
|
+
<AgentPrompt variant="custom-component" />
|
|
13
|
+
|
|
10
14
|
## Create the component
|
|
11
15
|
|
|
12
16
|
Create a new file in your catalog.
|
|
@@ -30,8 +30,8 @@ name: Notification Service
|
|
|
30
30
|
summary: |
|
|
31
31
|
Service that handles orders
|
|
32
32
|
styles:
|
|
33
|
-
icon:
|
|
34
|
-
node:
|
|
33
|
+
icon: /icons/bell.svg
|
|
34
|
+
node:
|
|
35
35
|
color: purple
|
|
36
36
|
label: "Custom"
|
|
37
37
|
---
|
|
@@ -45,6 +45,8 @@ styles:
|
|
|
45
45
|
|
|
46
46
|
| ID | Required | Default | Description |
|
|
47
47
|
| --- | --- | --- | --- |
|
|
48
|
-
| `styles.icon` | No | Depends on resource type |
|
|
49
|
-
| `styles.node.color` | No | Depends on resource type | The color to use for the node
|
|
50
|
-
| `styles.node.label` | No | Depends on resource type | The label
|
|
48
|
+
| `styles.icon` | No | Depends on resource type | An icon shown next to the resource's name: a path to an image in your catalog's `public` folder (e.g. `/icons/bell.svg`) or an image URL. Domain, flow and entity nodes also take a [Heroicons](https://heroicons.com/) name (e.g. `BellIcon`). |
|
|
49
|
+
| `styles.node.color` | No | Depends on resource type | The color to use for the node: a [Tailwind color](https://tailwindcss.com/docs/colors) name (e.g. `blue`, `emerald`) or a hex color (e.g. `#0ea5e9`). It colors the node's border, badge and handles. |
|
|
50
|
+
| `styles.node.label` | No | Depends on resource type | The label shown in the node's type badge, in place of its type (e.g. `Service`). |
|
|
51
|
+
|
|
52
|
+
Colors and labels apply to services, events, commands, queries, channels, data stores, data products, agents and flows.
|
|
@@ -109,4 +109,4 @@ When the EventCatalog MCP server is enabled, an additional entry pointing at `/d
|
|
|
109
109
|
|
|
110
110
|
Only services and domains are included in v1 of this endpoint. Events, commands, queries, data products, schemas, diagrams, teams, and users are out of scope for this release.
|
|
111
111
|
|
|
112
|
-
For a broader machine-readable index of your catalog content, see [llms.txt](/docs/development/
|
|
112
|
+
For a broader machine-readable index of your catalog content, see [llms.txt](/docs/development/developer-tools/llms.txt) and [schemas.txt](/docs/development/developer-tools/schemas.txt).
|
package/dist/docs/development/{ask-your-architecture/02-llms.txt.md → developer-tools/llms.txt.md}
RENAMED
|
@@ -52,6 +52,8 @@ The recommended URLs for AI tools are at the catalog root:
|
|
|
52
52
|
- `https://<your-catalog-url>/llms-full.txt`
|
|
53
53
|
- Demo: https://demo.eventcatalog.dev/llms-full.txt
|
|
54
54
|
|
|
55
|
+
The ubiquitous language of your catalog is also available as [ubiquitous-language.txt](/docs/development/developer-tools/ubiquitous-language.txt).
|
|
56
|
+
|
|
55
57
|
The legacy paths `/docs/llm/llms.txt` and `/docs/llm/llms-full.txt` still work for backward compatibility.
|
|
56
58
|
|
|
57
59
|
### How to use LLMS.txt?
|
|
@@ -17,7 +17,7 @@ Message schemas and service specifications can be fetched from your EventCatalog
|
|
|
17
17
|
|
|
18
18
|
### What is schemas.txt?
|
|
19
19
|
|
|
20
|
-
Schemas.txt is very similar to [LLMS.txt](/docs/development/
|
|
20
|
+
Schemas.txt is very similar to [LLMS.txt](/docs/development/developer-tools/llms.txt), but it is specifically for schemas in your EventCatalog.
|
|
21
21
|
|
|
22
22
|
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).
|
|
23
23
|
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
sidebar_position: 8
|
|
3
|
+
keywords:
|
|
4
|
+
- ubiquitous language
|
|
5
|
+
- glossary
|
|
6
|
+
- AI
|
|
7
|
+
- LLM
|
|
8
|
+
sidebar_label: ubiquitous-language.txt
|
|
9
|
+
title: ubiquitous-language.txt
|
|
10
|
+
description: Give AI tools the ubiquitous language of your organization
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
import AddedIn from '@site/src/components/MDX/AddedIn';
|
|
14
|
+
|
|
15
|
+
<AddedIn version="5.9.0" />
|
|
16
|
+
|
|
17
|
+
Give AI tools one file with the ubiquitous language of your whole organization.
|
|
18
|
+
|
|
19
|
+
### What is ubiquitous-language.txt?
|
|
20
|
+
|
|
21
|
+
The file lists the terms of every domain and subdomain, with subdomains under their parent domain. It is generated from your [`ubiquitous-language.mdx`](/docs/development/guides/domains/ownership-and-language/adding-ubiquitous-language) files, so there is nothing to configure.
|
|
22
|
+
|
|
23
|
+
Terms are never merged, because a word can mean different things in different domains. Terms defined in more than one domain are listed together at the top of the file, with the meaning in each domain.
|
|
24
|
+
|
|
25
|
+
```txt
|
|
26
|
+
## Terms defined in more than one domain
|
|
27
|
+
- Reservation
|
|
28
|
+
- Fulfilment: A temporary hold on stock for a specific order, taken during checkout.
|
|
29
|
+
- Ordering: A temporary hold on stock for the items in a cart, taken during checkout.
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Each term is one line with its summary (or its description, flattened to one line, when it has no summary). Each domain section links to that domain's `/docs/domains/{id}/language.mdx` for the full definitions.
|
|
33
|
+
|
|
34
|
+
### Access the file
|
|
35
|
+
|
|
36
|
+
- `https://<your-catalog-url>/docs/llm/ubiquitous-language.txt`
|
|
37
|
+
|
|
38
|
+
The file is turned on and off with the `llmsTxt` setting, the same as [llms.txt](/docs/development/developer-tools/llms.txt). When it is disabled the file returns a 404. It is linked from the LLM access settings page, and from the Ubiquitous Language section of `llms.txt`.
|
|
39
|
+
|
|
40
|
+
### Use with the MCP server
|
|
41
|
+
|
|
42
|
+
The [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/getting-started#available-tools) exposes the same language through the `explainUbiquitousLanguageTerms` tool.
|
|
@@ -96,5 +96,8 @@ When you add a ubiquitous language dictionary to your domain, it will automatica
|
|
|
96
96
|
|
|
97
97
|
Clicking on a term in the Domain Language explorer will open that term in a new page.
|
|
98
98
|
|
|
99
|
+
### Share with AI tools
|
|
99
100
|
|
|
101
|
+
<AddedIn version="5.9.0" />
|
|
100
102
|
|
|
103
|
+
Your terms from every domain are also available to AI tools in one file, [ubiquitous-language.txt](/docs/development/developer-tools/ubiquitous-language.txt), and through the `explainUbiquitousLanguageTerms` tool of the [MCP server](/docs/development/ask-your-architecture/mcp-server/getting-started#explain-ubiquitous-language).
|
|
@@ -20,6 +20,7 @@ Documenting ADRs in your catalog gives your team:
|
|
|
20
20
|
- **Context** — anyone can see what alternatives were considered and why a particular path was chosen.
|
|
21
21
|
- **Traceability** — decisions are linked directly to the services, events, domains, and flows they affect via `appliesTo`.
|
|
22
22
|
- **Lifecycle tracking** — each ADR has a status (`proposed`, `accepted`, `rejected`, `deprecated`, `superseded`) so it is clear which decisions are still in force.
|
|
23
|
+
- **Checks in pull requests** — the [ADR Compliance workflow](/docs/development/agents/set-up-adr-compliance) comments when a pull request's code conflicts with an accepted decision.
|
|
23
24
|
- **AI-ready context** — because ADRs sit alongside the resources they govern, the [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) can surface the *why* behind your architecture to AI assistants, not just the *what*. When an LLM is reasoning about a service or event, it picks up the decisions, trade-offs, and constraints recorded in your ADRs.
|
|
24
25
|
|
|
25
26
|
## Lifecycle statuses
|
package/dist/eventcatalog.cjs
CHANGED
|
@@ -33,11 +33,12 @@ var import_node_path22 = require("path");
|
|
|
33
33
|
var import_node_http = __toESM(require("http"), 1);
|
|
34
34
|
var import_fs = __toESM(require("fs"), 1);
|
|
35
35
|
var import_node_path23 = __toESM(require("path"), 1);
|
|
36
|
-
var
|
|
36
|
+
var import_node_url3 = require("url");
|
|
37
37
|
var import_node_module3 = require("module");
|
|
38
38
|
|
|
39
39
|
// src/generate.js
|
|
40
40
|
var import_node_path3 = __toESM(require("path"), 1);
|
|
41
|
+
var import_node_url2 = require("url");
|
|
41
42
|
|
|
42
43
|
// src/eventcatalog-config-file-utils.js
|
|
43
44
|
var import_promises2 = require("fs/promises");
|
|
@@ -174,7 +175,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
|
|
|
174
175
|
var import_picocolors = __toESM(require("picocolors"), 1);
|
|
175
176
|
|
|
176
177
|
// package.json
|
|
177
|
-
var version = "5.
|
|
178
|
+
var version = "5.9.1";
|
|
178
179
|
|
|
179
180
|
// src/constants.ts
|
|
180
181
|
var VERSION = version;
|
|
@@ -273,7 +274,7 @@ var generate = async (PROJECT_DIRECTORY) => {
|
|
|
273
274
|
plugin = plugin.replace("<rootDir>", PROJECT_DIRECTORY);
|
|
274
275
|
}
|
|
275
276
|
try {
|
|
276
|
-
const importedGenerator = await import(plugin);
|
|
277
|
+
const importedGenerator = await (import_node_path3.default.isAbsolute(plugin) ? import((0, import_node_url2.pathToFileURL)(plugin).href) : import(plugin));
|
|
277
278
|
const generator2 = getDefaultExport(importedGenerator);
|
|
278
279
|
await generator2({ eventCatalogConfig: {} }, pluginConfig);
|
|
279
280
|
} catch (error) {
|
|
@@ -3090,7 +3091,7 @@ Run npm i @eventcatalog/core to update`;
|
|
|
3090
3091
|
};
|
|
3091
3092
|
|
|
3092
3093
|
// src/eventcatalog.ts
|
|
3093
|
-
var currentDir = import_node_path23.default.dirname((0,
|
|
3094
|
+
var currentDir = import_node_path23.default.dirname((0, import_node_url3.fileURLToPath)(importMetaUrl));
|
|
3094
3095
|
var astroCli = import_node_path23.default.join(import_node_path23.default.dirname((0, import_node_module3.createRequire)(importMetaUrl).resolve("astro/package.json")), "bin/astro.mjs");
|
|
3095
3096
|
var ASTRO_IN_FOREGROUND = { ASTRO_DEV_BACKGROUND: "1", ASTRO_PREVIEW_BACKGROUND: "1" };
|
|
3096
3097
|
var program = new import_commander.Command().version(VERSION);
|
|
@@ -3576,7 +3577,7 @@ var startServerCatalog = async () => {
|
|
|
3576
3577
|
const base = (config?.base || "/").replace(/\/$/, "");
|
|
3577
3578
|
await runCommandWithFilteredOutput({
|
|
3578
3579
|
command: process.execPath,
|
|
3579
|
-
args: ["--input-type=module", "-e", SERVER_BOOTSTRAP, (0,
|
|
3580
|
+
args: ["--input-type=module", "-e", SERVER_BOOTSTRAP, (0, import_node_url3.pathToFileURL)(serverEntryPath).href],
|
|
3580
3581
|
cwd: dir,
|
|
3581
3582
|
env: {
|
|
3582
3583
|
PROJECT_DIR: dir,
|
package/dist/eventcatalog.js
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
import {
|
|
2
|
-
stopChildWithParent
|
|
3
|
-
} from "./chunk-S5GWAUG5.js";
|
|
4
1
|
import {
|
|
5
2
|
runMigrations
|
|
6
3
|
} from "./chunk-XUAF2H54.js";
|
|
7
4
|
import "./chunk-CA4U2JP7.js";
|
|
5
|
+
import {
|
|
6
|
+
stopChildWithParent
|
|
7
|
+
} from "./chunk-S5GWAUG5.js";
|
|
8
8
|
import {
|
|
9
9
|
log_build_default
|
|
10
|
-
} from "./chunk-
|
|
10
|
+
} from "./chunk-3PWCUWQC.js";
|
|
11
11
|
import {
|
|
12
12
|
getLicenseStatus,
|
|
13
13
|
printLicenseStatus
|
|
14
14
|
} from "./chunk-AD7CL772.js";
|
|
15
|
-
import "./chunk-
|
|
15
|
+
import "./chunk-YBM7MCOY.js";
|
|
16
16
|
import "./chunk-YRZK7HKX.js";
|
|
17
17
|
import "./chunk-CA6WCQ2T.js";
|
|
18
18
|
import "./chunk-CPW6G62V.js";
|
|
@@ -39,10 +39,10 @@ import {
|
|
|
39
39
|
} from "./chunk-NKNOXQ62.js";
|
|
40
40
|
import {
|
|
41
41
|
generate
|
|
42
|
-
} from "./chunk-
|
|
42
|
+
} from "./chunk-A3256YCN.js";
|
|
43
43
|
import {
|
|
44
44
|
logger
|
|
45
|
-
} from "./chunk-
|
|
45
|
+
} from "./chunk-JDSFD7IC.js";
|
|
46
46
|
import {
|
|
47
47
|
resolve_catalog_dependencies_default
|
|
48
48
|
} from "./chunk-PD7KTSYN.js";
|
|
@@ -79,7 +79,7 @@ import {
|
|
|
79
79
|
} from "./chunk-LFQJXLHG.js";
|
|
80
80
|
import {
|
|
81
81
|
VERSION
|
|
82
|
-
} from "./chunk-
|
|
82
|
+
} from "./chunk-KGFAIGOT.js";
|
|
83
83
|
import {
|
|
84
84
|
getEventCatalogConfigFile,
|
|
85
85
|
verifyRequiredFieldsAreInCatalogConfigFile
|
package/dist/generate.cjs
CHANGED
|
@@ -34,6 +34,7 @@ __export(generate_exports, {
|
|
|
34
34
|
});
|
|
35
35
|
module.exports = __toCommonJS(generate_exports);
|
|
36
36
|
var import_node_path3 = __toESM(require("path"), 1);
|
|
37
|
+
var import_node_url2 = require("url");
|
|
37
38
|
|
|
38
39
|
// src/eventcatalog-config-file-utils.js
|
|
39
40
|
var import_promises2 = require("fs/promises");
|
|
@@ -105,7 +106,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
|
|
|
105
106
|
var import_picocolors = __toESM(require("picocolors"), 1);
|
|
106
107
|
|
|
107
108
|
// package.json
|
|
108
|
-
var version = "5.
|
|
109
|
+
var version = "5.9.1";
|
|
109
110
|
|
|
110
111
|
// src/constants.ts
|
|
111
112
|
var VERSION = version;
|
|
@@ -204,7 +205,7 @@ var generate = async (PROJECT_DIRECTORY) => {
|
|
|
204
205
|
plugin = plugin.replace("<rootDir>", PROJECT_DIRECTORY);
|
|
205
206
|
}
|
|
206
207
|
try {
|
|
207
|
-
const importedGenerator = await import(plugin);
|
|
208
|
+
const importedGenerator = await (import_node_path3.default.isAbsolute(plugin) ? import((0, import_node_url2.pathToFileURL)(plugin).href) : import(plugin));
|
|
208
209
|
const generator2 = getDefaultExport(importedGenerator);
|
|
209
210
|
await generator2({ eventCatalogConfig: {} }, pluginConfig);
|
|
210
211
|
} catch (error) {
|
package/dist/generate.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import {
|
|
2
2
|
generate
|
|
3
|
-
} from "./chunk-
|
|
4
|
-
import "./chunk-
|
|
5
|
-
import "./chunk-
|
|
3
|
+
} from "./chunk-A3256YCN.js";
|
|
4
|
+
import "./chunk-JDSFD7IC.js";
|
|
5
|
+
import "./chunk-KGFAIGOT.js";
|
|
6
6
|
import "./chunk-4G7FSRPN.js";
|
|
7
7
|
export {
|
|
8
8
|
generate
|