@eventcatalog/core 5.8.0 → 5.9.0

package/eventcatalog/src/pages/docs/llm/ubiquitous-language.txt.ts

@@ -0,0 +1,68 @@
+import config from '@config';
+import type { APIRoute } from 'astro';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import {
+  getTermsDefinedInSeveralDomains,
+  getTermSummary,
+  getUbiquitousLanguageGlossary,
+  type DomainGlossary,
+  type UbiquitousLanguageTerm,
+} from '@utils/collections/domains';
+
+const formatTerm = (term: UbiquitousLanguageTerm) => {
+  const summary = getTermSummary(term);
+  return `- ${term.name}${summary ? `: ${summary}` : ''}`;
+};
+
+export const GET: APIRoute = async ({ request }) => {
+  if (!isLLMSTxtEnabled()) {
+    return new Response('ubiquitous-language.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const url = new URL(request.url);
+  const baseUrl = process.env.LLMS_TXT_BASE_URL || `${url.origin}`;
+
+  const glossary = await getUbiquitousLanguageGlossary();
+
+  const header = [
+    `# ${config.organizationName} Ubiquitous Language`,
+    '> The business terms used across this organization, grouped by domain. A term only applies within its domain: the same word can mean something different in another domain.',
+  ].join('\n');
+
+  if (glossary.length === 0) {
+    return new Response(`${header}\n\nNo ubiquitous language terms are defined in this catalog.`, {
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    });
+  }
+
+  const formatDomain = (domain: DomainGlossary, heading: string) =>
+    [
+      `${heading} ${domain.name}`,
+      ...(domain.terms.length > 0
+        ? [`Full definitions: ${baseUrl}/docs/domains/${domain.id}/language.mdx`, ...domain.terms.map(formatTerm)]
+        : []),
+    ].join('\n');
+
+  const termsInSeveralDomains = [...getTermsDefinedInSeveralDomains(glossary).values()].map((definitions) =>
+    [
+      `- ${definitions[0].term.name}`,
+      ...definitions.map(({ domain, term }) => {
+        const summary = getTermSummary(term);
+        return `  - ${domain.name}${summary ? `: ${summary}` : ''}`;
+      }),
+    ].join('\n')
+  );
+
+  const sections = [
+    header,
+    ...(termsInSeveralDomains.length > 0 ? [`## Terms defined in more than one domain\n${termsInSeveralDomains.join('\n')}`] : []),
+    ...glossary.flatMap((domain) => [
+      formatDomain(domain, '##'),
+      ...domain.subdomains.map((subdomain) => formatDomain(subdomain, '###')),
+    ]),
+  ];
+
+  return new Response(sections.join('\n\n'), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};

package/eventcatalog/src/pages/settings/llm-access.astro

@@ -16,6 +16,7 @@ const apiBase = buildUrl('/api/settings');
 const llmsTxtUrl = buildUrl('/llms.txt');
 const llmsFullTxtUrl = buildUrl('/llms-full.txt');
 const schemasTxtUrl = buildUrl('/docs/llm/schemas.txt');
+const ubiquitousLanguageTxtUrl = buildUrl('/docs/llm/ubiquitous-language.txt');
 ---
 
 <SettingsLayout title="LLM Access" active="llm-access">
@@ -27,5 +28,6 @@ const schemasTxtUrl = buildUrl('/docs/llm/schemas.txt');
     llmsTxtUrl={llmsTxtUrl}
     llmsFullTxtUrl={llmsFullTxtUrl}
     schemasTxtUrl={schemasTxtUrl}
+    ubiquitousLanguageTxtUrl={ubiquitousLanguageTxtUrl}
   />
 </SettingsLayout>

package/eventcatalog/src/utils/collections/domains.ts

@@ -436,6 +436,90 @@ export const getRootDomains = async (): Promise<Domain[]> => {
   return domains.filter((d) => !allSubDomains.some((sd) => sd.data.id === d.data.id));
 };
 
+export type UbiquitousLanguageTerm = NonNullable<UbiquitousLanguage['data']['dictionary']>[number];
+
+export type DomainGlossary = {
+  id: string;
+  version: string;
+  name: string;
+  terms: UbiquitousLanguageTerm[];
+};
+
+export type SubdomainGlossary = DomainGlossary & { parentId: string };
+
+export type OrganizationGlossaryDomain = DomainGlossary & { subdomains: SubdomainGlossary[] };
+
+/**
+ * The ubiquitous language of the whole catalog: every domain with terms (or with a subdomain that has
+ * them), with all of its subdomains, at any depth, listed under it. Terms stay with their domain and are
+ * never merged, because the same word can mean something different in another domain.
+ */
+export const getUbiquitousLanguageGlossary = async (): Promise<OrganizationGlossaryDomain[]> => {
+  const [domains, rootDomains, ubiquitousLanguages] = await Promise.all([
+    getDomains({ getAllVersions: false }),
+    getRootDomains(),
+    getCollection('ubiquitousLanguages'),
+  ]);
+  const domainsById = new Map(domains.map((domain) => [domain.data.id, domain]));
+
+  const toGlossary = (domain: Domain): DomainGlossary => ({
+    id: domain.data.id,
+    version: domain.data.version,
+    name: domain.data.name || domain.data.id,
+    terms: getUbiquitousLanguageFromCollection(domain, ubiquitousLanguages).flatMap(
+      (ubiquitousLanguage) => ubiquitousLanguage.data.dictionary || []
+    ),
+  });
+
+  // Each domain is only listed once, whether several domains share it or domains point at each other
+  const listedDomains = new Set<string>();
+
+  const getDescendants = (parent: Domain): SubdomainGlossary[] =>
+    ((parent.data.domains as unknown as Domain[]) || []).flatMap((subdomain) => {
+      if (listedDomains.has(subdomain.data.id)) return [];
+      listedDomains.add(subdomain.data.id);
+
+      // Use the current version even when the parent pins an old one: only current versions have glossaries,
+      // and their own subdomains resolved
+      const currentSubdomain = domainsById.get(subdomain.data.id) || subdomain;
+
+      return [{ ...toGlossary(currentSubdomain), parentId: parent.data.id }, ...getDescendants(currentSubdomain)];
+    });
+
+  // Root domains go first. Any domain still not listed after them points in a loop, so has no root.
+  return [...rootDomains, ...domains]
+    .flatMap((domain) => {
+      if (listedDomains.has(domain.data.id)) return [];
+      listedDomains.add(domain.data.id);
+
+      return [
+        {
+          ...toGlossary(domain),
+          subdomains: getDescendants(domain).filter((subdomain) => subdomain.terms.length > 0),
+        },
+      ];
+    })
+    .filter((domain) => domain.terms.length > 0 || domain.subdomains.length > 0);
+};
+
+/** The terms defined in more than one domain, keyed by their lowercase name */
+export const getTermsDefinedInSeveralDomains = (glossary: OrganizationGlossaryDomain[]) => {
+  const definitions = new Map<string, { domain: DomainGlossary; term: UbiquitousLanguageTerm }[]>();
+
+  for (const domain of glossary.flatMap((domain) => [domain, ...domain.subdomains])) {
+    for (const term of domain.terms) {
+      const key = term.name.toLowerCase();
+      definitions.set(key, [...(definitions.get(key) || []), { domain, term }]);
+    }
+  }
+
+  return new Map([...definitions].filter(([, termDefinitions]) => new Set(termDefinitions.map((d) => d.domain.id)).size > 1));
+};
+
+/** A term's definition on one line, for the text files we generate for LLMs */
+export const getTermSummary = (term: UbiquitousLanguageTerm) =>
+  (term.summary || term.description || '').replace(/\s+/g, ' ').trim();
+
 export const getDomainsForService = async (service: Service): Promise<Domain[]> => {
   const domains = await getDomains({ getAllVersions: false });
   return domains.filter((d) => {

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "publishConfig": {
     "access": "public"
   },
@@ -142,9 +142,9 @@
     "yjs": "^13.6.33",
     "zod": "^4.6.6",
     "@eventcatalog/exporters": "0.1.4",
-    "@eventcatalog/fitness": "0.1.1",
     "@eventcatalog/sdk": "2.32.0",
-    "@eventcatalog/visualiser": "^5.2.4",
+    "@eventcatalog/visualiser": "^5.2.5",
+    "@eventcatalog/fitness": "0.1.1",
     "@eventcatalog/linter": "1.3.1"
   },
   "devDependencies": {

package/dist/docs/development/ask-your-architecture/04-agents/01-overview.md

@@ -1,27 +0,0 @@
----
-sidebar_position: 1
-keywords:
-  - AI Agents
-  - documentation generation
-  - automation
-sidebar_label: Overview
-title: EventCatalog Agents
-description: AI agents that help you manage and document your architecture with EventCatalog
----
-
-[EventCatalog Agent](https://github.com/event-catalog/agents) is an agent that helps you manage your documentation through CI/CD and adds a governing layer to your pull requests.
-
-Our Agent understands EventCatalog conventions (domains, systems and resources) and uses that understanding to keep your architecture documented for you, without you having to hand-write and maintain every catalog file yourself.
-
-EventCatalog Agent lets you define and bring your own model.
-
-### Available workflows
-
-| Agent | What it does |
-| --- | --- |
-| [Code-to-Docs](/docs/development/ask-your-architecture/agents/code-to-docs) | The EventCatalog Agent will review your pull request code and update your catalog documentation for you. |
-| [Breaking Changes](/docs/development/ask-your-architecture/agents/breaking-changes) | Detects breaking schema changes in a pull request and shows which catalog consumers could be affected. |
-
-### Have an idea for a workflow?
-
-More agents and AI workflows are on the way. If you have an idea for an agent or an AI workflow you'd like to see in EventCatalog, [open an issue on GitHub](https://github.com/event-catalog/agents/issues/new) and let us know. We use these ideas to decide what to build next.

package/dist/docs/development/ask-your-architecture/04-agents/02-code-to-docs.md

@@ -1,124 +0,0 @@
----
-sidebar_position: 2
-keywords:
-  - Code to Docs
-  - AI Agents
-  - GitHub Action
-  - documentation generation
-sidebar_label: Code-to-Docs Agent
-title: Code-to-Docs Agent
-description: Keep your EventCatalog documentation in sync with your code using the Code-to-Docs agent
----
-
-The **Code-to-Docs** agent keeps your EventCatalog documentation in sync with your code.
-
-When you open a pull request, the agent reviews the diff, works out which documentation should change, updates it in your catalog repository, and opens (or updates) a documentation pull request. It then comments back on your source pull request with a summary and a link.
-
-## How it works
-
-```mermaid
-flowchart LR
-    PR[Source pull request] --> Agent[Code-to-Docs agent]
-    Agent --> Plan{Docs need<br/>updating?}
-    Plan -- No --> Comment[Comment on source PR]
-    Plan -- Yes --> Docs[Update catalog docs]
-    Docs --> CatalogPR[Open catalog pull request]
-    CatalogPR --> Comment
-```
-
-When a pull request is opened, the agent:
-
-1. **Checks out your catalog** so it can see your existing documentation.
-2. **Collects the changed source files** from the pull request.
-3. **Plans the impact**. A read-only pass where the agent decides whether the diff requires any documentation changes, and if so, exactly which catalog resources should change. If nothing is needed, it stops here and says so.
-4. **Applies the plan**. The agent updates the documentation, using EventCatalog conventions for frontmatter and folder structure, and a linter to validate its changes. It is only allowed to touch the resources approved in the plan.
-5. **Opens a catalog pull request** with the changes for you to review.
-6. **Comments on your source pull request** with a high-level summary and a link to the catalog pull request.
-
-You stay in control: the agent never edits your catalog silently. Every change arrives as a pull request you can review, tweak, and merge.
-
-## Getting started
-
-The Code-to-Docs agent runs as a GitHub Action. Add it to your repository in three steps.
-
-### 1. Add a new GitHub workflow
-
-Create a new workflow in your source directory. Typically this is where your source code lives (e.g a service that publishes/consumes messages).
-
-Create a `.github/workflows/eventcatalog.yml` file.
-
-```yaml
-on:
-  pull_request:
-
-jobs:
-  eventcatalog:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - uses: event-catalog/agents@main
-        env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-        with:
-          agent: code-to-docs
-          catalog-repo: your-org/your-catalog
-          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
-```
-
-`fetch-depth: 0` is required so the agent can diff the pull request against its base.
-
-### 2. Add your model provider key
-
-Add the API key for your chosen model as a secret in your repository (**Settings → Secrets and variables → Actions**). Use the one that matches your model, for example `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
-
-You can see the list of [available models here](https://pi.dev/models).
-
-### 3. Open a pull request
-
-When you next open a pull request on your project, the EventCatalog Agent will run.
-
-If your architecture changed, opens a documentation pull request in your catalog repository and comments back with a link.
-
-## Configuration
-
-### Inputs
-
-| Input | Required | Default | Description |
-| --- | --- | --- | --- |
-| `catalog-repo` | Yes | | The location of your hosted EventCatalog. EventCatalog repository to document into, in `owner/repo` format. |
-| `catalog-ref` | No | `main` | Branch checked out from the catalog repository and targeted by documentation pull requests. |
-| `catalog-token` | No | `github.token` | Token used to check out the catalog repository and open documentation pull requests. |
-| `model` | No | `anthropic/claude-sonnet-4-6` | Model specifier for the agent. See [available models](https://pi.dev/models). |
-| `ignore-paths` | No | common build/output paths | Comma-separated paths or glob patterns to ignore in pull request diffs. |
-| `agent` | No | `code-to-docs` | Which EventCatalog agent to run. Use `code-to-docs` for this workflow. |
-
-### Provider API keys
-
-The model provider's API key is passed as a normal workflow environment variable. Set the one that matches your `model`:
-
-| Provider | Environment variable |
-| --- | --- |
-| Anthropic | `ANTHROPIC_API_KEY` |
-| OpenAI | `OPENAI_API_KEY` |
-| OpenRouter | `OPENROUTER_API_KEY` |
-
-The agent supports models from many providers. See the full list of model specifiers at [pi.dev/models](https://pi.dev/models).
-
-### Documenting into a separate catalog repository
-
-When your catalog lives in a **different** repository from your source code, provide a `catalog-token` with permission to push branches and open pull requests in that catalog repository (the default `github.token` only has access to the current repository).
-
-:::info Early access
-The Code-to-Docs agent is in early access and free to evaluate. In the future, a license will be required to run EventCatalog Agents in production.
-:::
-
-## Found an issue or have feedback?
-
-The Code-to-Docs agent is open on GitHub at [event-catalog/agents](https://github.com/event-catalog/agents). If you hit a problem, or the agent documents something in a way you didn't expect, [open an issue](https://github.com/event-catalog/agents/issues/new) and let us know. Your feedback during early access directly shapes how the agent works.

package/dist/docs/development/ask-your-architecture/04-agents/03-breaking-changes.md

@@ -1,170 +0,0 @@
----
-sidebar_position: 3
-keywords:
-  - Breaking Changes
-  - AI Agents
-  - GitHub Action
-  - schema governance
-  - schema compatibility
-sidebar_label: Breaking Changes Agent
-title: Breaking Changes Agent
-description: Detect breaking schema changes and affected EventCatalog consumers from pull requests
----
-
-The **Breaking Changes** agent reviews schema changes in pull requests and reports whether they are likely to break existing consumers.
-
-When a pull request changes a message schema, the agent checks whether the diff removes or renames fields, changes types, adds new required fields, narrows enums, or introduces similar compatibility risks. If it finds a breaking change, it traces the schema through your EventCatalog and comments on the source pull request with the breaking lines and affected consumers.
-
-The Breaking Changes agent is read-only. It does not edit your catalog or open documentation pull requests.
-
-![Breaking Changes agent pull request comment showing detected schema changes and affected consumers](./img/breaking-changes-agent.jpeg)
-
-## How it works
-
-```mermaid
-flowchart LR
-    PR[Source pull request] --> Agent[Breaking Changes agent]
-    Agent --> Schema{Schema<br/>changed?}
-    Schema -- No --> Skip[Nothing to report]
-    Schema -- Yes --> Breaking{Breaking<br/>change?}
-    Breaking -- No --> Skip
-    Breaking -- Yes --> Consumers[Find catalog consumers]
-    Consumers --> Comment[Comment on source PR]
-```
-
-When a pull request is opened, the agent:
-
-1. **Checks out your catalog** so it can understand the existing producers, consumers, messages, schemas, and flows.
-2. **Collects the changed source files** from the pull request.
-3. **Filters to schema files** using the configured schema extensions.
-4. **Scores each schema change** for breaking-change risk. Additive changes, such as adding an optional field, are skipped.
-5. **Finds affected consumers** for each breaking schema change by tracing the message through EventCatalog.
-6. **Comments on your source pull request** with the breaking change, the relevant diff lines, and the consumers that could be affected.
-
-If the pull request has no changed schema files, or only non-breaking schema changes, the workflow exits without creating a catalog pull request.
-
-## Getting started
-
-The Breaking Changes agent runs as a GitHub Action.
-
-### 1. Add a new GitHub workflow
-
-Create a `.github/workflows/eventcatalog-breaking-changes.yml` file in the repository where your source changes happen.
-
-```yaml
-on:
-  pull_request:
-
-jobs:
-  eventcatalog-breaking-changes:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - uses: event-catalog/agents@main
-        env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-        with:
-          agent: breaking-changes
-          catalog-repo: your-org/your-catalog
-          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
-```
-
-`fetch-depth: 0` is required so the agent can diff the pull request against its base.
-
-### 2. Add your model provider key
-
-Add the API key for your chosen model as a secret in your repository (**Settings → Secrets and variables → Actions**). Use the one that matches your model, for example `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
-
-You can see the list of [available models here](https://pi.dev/models).
-
-### 3. Open a pull request that changes a schema
-
-When a pull request changes a schema, the agent reviews the schema diff. If it finds a breaking change, it comments on the pull request with the affected EventCatalog consumers.
-
-## Configuration
-
-### Inputs
-
-| Input | Required | Default | Description |
-| --- | --- | --- | --- |
-| `agent` | No | `code-to-docs` | Set this to `breaking-changes` to run the Breaking Changes agent. |
-| `catalog-repo` | Yes | | The EventCatalog repository to inspect, in `owner/repo` format. |
-| `catalog-ref` | No | `main` | Branch checked out from the catalog repository. |
-| `catalog-token` | No | `github.token` | Token used to check out the catalog repository. Use a token with read access when the catalog is in another private repository. |
-| `model` | No | `anthropic/claude-sonnet-4-6` | Model specifier for the agent. See [available models](https://pi.dev/models). |
-| `ignore-paths` | No | common build/output paths | Comma-separated paths or glob patterns to ignore in pull request diffs. |
-| `schema-extensions` | No | `.json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql` | Comma-separated file extensions the agent treats as message schemas. |
-
-### Schema extensions
-
-By default, the agent checks common schema files:
-
-```yaml
-schema-extensions: .json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql
-```
-
-If your message contracts live in another file type, add that extension:
-
-```yaml
-- uses: event-catalog/agents@main
-  env:
-    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-  with:
-    agent: breaking-changes
-    catalog-repo: your-org/your-catalog
-    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
-    schema-extensions: .json,.yaml,.ts
-```
-
-Only add source-code extensions when those files contain message contracts. The agent ignores non-schema files for this workflow.
-
-### Provider API keys
-
-The model provider's API key is passed as a normal workflow environment variable. Set the one that matches your `model`:
-
-| Provider | Environment variable |
-| --- | --- |
-| Anthropic | `ANTHROPIC_API_KEY` |
-| OpenAI | `OPENAI_API_KEY` |
-| OpenRouter | `OPENROUTER_API_KEY` |
-
-The agent supports models from many providers. See the full list of model specifiers at [pi.dev/models](https://pi.dev/models).
-
-## Run with Code-to-Docs
-
-Each Action step runs one EventCatalog agent. To run Breaking Changes and [Code-to-Docs](/docs/development/ask-your-architecture/agents/code-to-docs) on the same pull request, add two steps:
-
-```yaml
-- uses: event-catalog/agents@main
-  env:
-    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-  with:
-    agent: breaking-changes
-    catalog-repo: your-org/your-catalog
-    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
-
-- uses: event-catalog/agents@main
-  env:
-    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-  with:
-    agent: code-to-docs
-    catalog-repo: your-org/your-catalog
-    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
-```
-
-Use Breaking Changes when you want pull request feedback about schema compatibility. Use Code-to-Docs when you want catalog documentation updates proposed as a separate pull request.
-
-:::info Early access
-The Breaking Changes agent is in early access and free to evaluate. In the future, a license will be required to run EventCatalog Agents in production.
-:::
-
-## Found an issue or have feedback?
-
-The Breaking Changes agent is open on GitHub at [event-catalog/agents](https://github.com/event-catalog/agents). If you hit a problem, or the agent reports something in a way you didn't expect, [open an issue](https://github.com/event-catalog/agents/issues/new) and let us know. Your feedback during early access directly shapes how the agent works.

package/dist/docs/development/ask-your-architecture/04-agents/_category_.json

@@ -1,12 +0,0 @@
-{
-  "label": "Agents",
-  "position": 4,
-  "collapsible": true,
-  "collapsed": true,
-  "link": {
-    "type": "generated-index",
-    "slug": "/development/ask-your-architecture/agents",
-    "title": "EventCatalog Agents",
-    "description": "AI agents that help you manage and document your architecture with EventCatalog."
-  }
-}