@eventcatalog/core 5.7.6 → 5.9.0

package/eventcatalog/src/utils/raw-specification.ts

@@ -0,0 +1,126 @@
+import type { APIContext, APIRoute } from 'astro';
+import type { CollectionEntry } from 'astro:content';
+import type { CollectionTypes } from '@types';
+import { getSpecificationMediaType, processSpecifications, type SpecificationType } from '@utils/collections/util';
+import { readResourceFile, resourceFileExists } from '@utils/resource-files';
+import { resolveHeaders } from '@utils/remote-spec';
+import { buildUrl } from '@utils/url-builder';
+import Config from '@utils/eventcatalog-config/catalog';
+
+/** The folder each kind of specification page lives in, under /docs/{type}/{id}/{version}/ */
+const PAGE_SEGMENT_BY_SPECIFICATION_TYPE: Record<SpecificationType, string> = {
+  asyncapi: 'asyncapi',
+  openapi: 'spec',
+  graphql: 'graphql',
+  generic: 'generic',
+};
+
+export type StaticPath = { params: Record<string, string | undefined>; props: Record<string, any> };
+
+/** The data a specification page loads: the resource, plus the specification's path and file names */
+export type SpecificationPageData = CollectionEntry<CollectionTypes> & {
+  path: string;
+  filename: string;
+  filenameWithoutExtension: string;
+};
+
+/** A specification page's data loader (the `Page` class in each `_[filename].data.ts`) */
+export type SpecificationPage = {
+  getStaticPaths(): Promise<StaticPath[]>;
+  getData(astro: { params: Record<string, string | undefined>; props: Record<string, any> }): Promise<any>;
+};
+
+/**
+ * The name a specification's file has in its URL: a remote specification's file name without the URL's query
+ * or fragment (orders.yaml?token=abc is orders.yaml), which would otherwise end the URL's path
+ */
+export const getRawSpecificationFileName = (filename: string) => filename.split(/[?#]/, 1)[0];
+
+/** Whether a raw specification URL's `file` names this specification's file */
+export const isRawSpecificationFile = (pageData: SpecificationPageData, file: string | undefined) =>
+  getRawSpecificationFileName(pageData.filename) === file;
+
+/**
+ * The URL of a specification's file, as written (JSON, YAML, GraphQL...): its page's URL followed by the
+ * file's name, e.g. /docs/services/Orders/1.0.0/asyncapi/orders/orders.yaml
+ */
+export const getRawSpecificationUrl = ({
+  collection,
+  id,
+  version,
+  type,
+  filename,
+  filenameWithoutExtension,
+}: {
+  collection: string;
+  id: string;
+  version: string;
+  type: SpecificationType;
+  filename: string;
+  filenameWithoutExtension: string;
+}) =>
+  buildUrl(
+    `/docs/${collection}/${id}/${version}/${PAGE_SEGMENT_BY_SPECIFICATION_TYPE[type]}/${filenameWithoutExtension}/${getRawSpecificationFileName(filename)}`,
+    true
+  );
+
+const isRemote = (path: string) => /^https?:\/\//i.test(path);
+
+export const notFound = (error: string) =>
+  new Response(JSON.stringify({ error }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+
+/** The specification's file, as written, with the media type of its format */
+export const getRawSpecificationResponse = async (
+  type: SpecificationType,
+  pageData: SpecificationPageData
+): Promise<Response> => {
+  const specification = processSpecifications((pageData.data as any).specifications).find(
+    (spec) => spec.type === type && spec.path === pageData.path
+  );
+
+  if (!specification) return notFound('Specification not found');
+
+  const headers = { 'Content-Type': getSpecificationMediaType(specification) };
+
+  if (isRemote(specification.path)) {
+    const allowAnyEnvInHeaders = type === 'asyncapi' && (Config?.asyncAPI?.allowAnyEnvInSpecHeaders ?? false);
+    const response = await fetch(specification.path, {
+      headers: resolveHeaders(specification.headers ?? {}, { allowAnyEnvInHeaders }),
+    }).catch(() => null);
+
+    if (!response?.ok) return notFound('Specification file could not be fetched');
+    return new Response(await response.text(), { headers });
+  }
+
+  const content = readResourceFile(pageData, specification.path);
+  if (content === null) return notFound('Specification file could not be read');
+
+  return new Response(content, { headers });
+};
+
+/**
+ * Each specification page's path, with the specification's file name added as `file`. A local file that
+ * doesn't exist gets no path: a static build would otherwise save the 404's JSON under the file's name.
+ */
+export const toRawSpecificationPaths = (paths: StaticPath[]): StaticPath[] =>
+  paths
+    .filter(({ props }) => isRemote(props.path) || resourceFileExists(props, props.path))
+    .map(({ params, props }) => ({ params: { ...params, file: getRawSpecificationFileName(props.filename) }, props }));
+
+/**
+ * The route that serves a specification's file next to its page:
+ * /docs/{type}/{id}/{version}/{asyncapi|spec|graphql|generic}/{filename}/{file}
+ */
+export const createRawSpecificationRoute = (type: SpecificationType, Page: SpecificationPage) => {
+  const getStaticPaths = async () => toRawSpecificationPaths(await Page.getStaticPaths());
+
+  const GET: APIRoute = async ({ params, props }: APIContext) => {
+    const pageData: SpecificationPageData | undefined = await Page.getData({ params, props });
+
+    if (!pageData || !isRawSpecificationFile(pageData, params.file)) return notFound('Specification not found');
+
+    return getRawSpecificationResponse(type, pageData);
+  };
+
+  return { getStaticPaths, GET };
+};

package/package.json

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

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."
-  }
-}

package/dist/{chunk-46TBJZC3.js → chunk-QJ7KKN2D.js}

@@ -1,7 +1,3 @@
-import {
-  getFederationDiagnostics,
-  resolveFederationRules
-} from "./chunk-JJPB6EOZ.js";
 import {
   withFederationOutputTransaction
 } from "./chunk-WRNH5C3U.js";
@@ -14,6 +10,10 @@ import {
 import {
   createFederationContentCache
 } from "./chunk-R7Z5ALYI.js";
+import {
+  getFederationDiagnostics,
+  resolveFederationRules
+} from "./chunk-JJPB6EOZ.js";
 import {
   getEventCatalogConfigFile
 } from "./chunk-4G7FSRPN.js";