@eventcatalog/core 4.10.12 → 4.10.14

package/dist/docs/federation/explanation/ownership-and-references.md

@@ -0,0 +1,134 @@
+---
+sidebar_position: 2
+sidebar_label: Ownership and references
+title: Ownership and cross-catalog references
+description: Understand how Federation assigns ownership and resolves relationships across catalog boundaries.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Federation separates **owning a resource** from **referring to a resource**.
+
+A catalog owns a resource when it contains the resource documentation. Other catalogs can use normal EventCatalog relationship pointers to refer to that ID without copying its definition.
+
+## One resource, one owner
+
+Resource IDs are organization-wide in a federated view.
+
+If Payments owns `payment-captured`, another catalog should not create a second `payment-captured` event as a placeholder. It should point to the owner's ID.
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart LR
+  ORD[Orders service] -->|receives payment-captured| EVT[payment-captured event]
+  PAY[Payments catalog] -->|owns documentation| EVT
+
+  classDef owner fill:#ecfdf5,stroke:#10b981,color:#064e3b
+  classDef consumer fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
+  class PAY,EVT owner
+  class ORD consumer
+```
+
+</div>
+
+The same owner should document every version of an ID. Splitting version `1.0.0` and version `2.0.0` across catalogs is still multiple ownership.
+
+## Relationships stay in normal frontmatter
+
+Teams keep authoring `sends`, `receives`, domain membership, flow steps, and other EventCatalog relationships as they do in a standalone catalog.
+
+For example, an Orders service can receive an event owned by Payments:
+
+```yaml
+---
+id: order-service
+name: Order Service
+version: 1.0.0
+receives:
+  - id: payment-captured
+    version: 1.0.0
+---
+```
+
+The Orders catalog does not need a local event file for `payment-captured`. When both catalogs participate in the central view, Federation connects the relationship to the Payments resource.
+
+## Central resources participate too
+
+The central catalog can own local resources. Those resources are included when Federation validates ownership and resolves relationships from remote catalogs.
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart TB
+  REMOTE[Remote service] -->|referenced by| LOCAL[Central flow or domain]
+  LOCAL --> GRAPH[Combined ownership graph]
+  REMOTE --> GRAPH
+```
+
+</div>
+
+This allows organization-wide flows and architecture decisions to refer to team-owned services and messages without copying them into the central repository.
+
+## How versions resolve
+
+Relationship pointers can select:
+
+| Pointer | Resolution |
+| --- | --- |
+| No version | Highest available version |
+| `latest` | Highest available version |
+| Exact version such as `1.2.0` | That version only |
+| Semantic range such as `^1.2.0` | Highest available version satisfying the range |
+
+If the ID exists but the requested version cannot be selected, Federation reports `federation/unresolved-version` with the requested and available versions.
+
+## Missing resource and unresolved version are different
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart TD
+  P[Relationship pointer] --> ID{Does the ID exist?}
+  ID -->|No| M[federation/missing-resource]
+  ID -->|Yes| V{Does a version match?}
+  V -->|No| U[federation/unresolved-version]
+  V -->|Yes| R[Resolved relationship]
+```
+
+</div>
+
+- **Missing resource** means no participating catalog documents the target ID.
+- **Unresolved version** means an owner exists, but it does not publish a matching version.
+
+Both are warnings by default so organizations can onboard catalogs gradually. They can be promoted to errors with [Federation rules](/docs/federation/how-to/configure-validation-rules).
+
+## Ambiguous ownership blocks by default
+
+Federation reports structural errors when:
+
+- Several catalogs own the same resource ID
+- The same ID is documented as different resource types
+- A relationship expects one resource type but finds another
+- Catalogs provide contradictory facets for one resource
+
+These problems have no unambiguous organization-wide interpretation, so their rules default to `error`.
+
+## Ownership conventions to agree on
+
+Before onboarding many catalogs, agree that:
+
+- Every resource ID has one owning catalog
+- The owner keeps all versions of the resource
+- Consumers point to the owner rather than creating placeholders
+- Shared teams and users have one source of truth
+- Central documentation uses unique IDs for resources it owns
+- Teams coordinate any intentionally shared asset or component paths
+
+## Related guides
+
+- [Configure validation rules](/docs/federation/how-to/configure-validation-rules)
+- [Diagnostic rule reference](/docs/federation/reference/diagnostic-rules)
+- [Troubleshooting ownership problems](/docs/federation/reference/troubleshooting#ownership-and-type-errors)

package/dist/docs/federation/how-to/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "How-to guides",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "federation/how-to",
+    "title": "Federation how-to guides",
+    "description": "Task-focused guides for configuring, running, and operating EventCatalog Federation."
+  }
+}

package/dist/docs/federation/how-to/configure-github-sources.md

@@ -0,0 +1,156 @@
+---
+sidebar_position: 1
+sidebar_label: Configure GitHub sources
+title: Configure GitHub federation sources
+description: Add public or private GitHub-hosted EventCatalog projects to a central catalog.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Use this guide when the catalogs you want to federate are stored in GitHub repositories.
+
+## Prerequisites
+
+You need:
+
+- A central EventCatalog project
+- One or more EventCatalog projects in GitHub
+- Git installed on the machine running Federation
+- An EventCatalog Enterprise offline license. Email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) to request a trial key.
+- A GitHub token with read access when a repository is private
+
+## Add a catalog at the repository root
+
+Add the source to `federation.sources` in the central `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    sources: [
+      {
+        id: 'acme/payments',
+        source: 'github:acme/payments-catalog',
+      },
+    ],
+  },
+};
+```
+
+The `github:` locator contains the GitHub owner and repository name. It does not contain a full URL.
+
+## Add a catalog from a repository subdirectory
+
+Use `path` when the EventCatalog is not at the repository root:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    sources: [
+      {
+        id: 'acme/payments',
+        source: 'github:acme/platform',
+        path: 'catalogs/payments',
+      },
+    ],
+  },
+};
+```
+
+`path` is relative to the source repository. It cannot be absolute or escape the repository.
+
+## Choose a branch, tag, or commit
+
+GitHub sources use `main` by default. Set `ref` to use another branch or tag:
+
+```js title="eventcatalog.config.js"
+{
+  id: 'acme/payments',
+  source: 'github:acme/payments-catalog',
+  ref: 'production',
+}
+```
+
+Use an exact commit SHA when the central build must repeatedly select the same source state:
+
+```js title="eventcatalog.config.js"
+{
+  id: 'acme/payments',
+  source: 'github:acme/payments-catalog',
+  ref: '4a1b7e23c79b4ef9f5f337c5e7655a5ec82a4761',
+}
+```
+
+The lockfile records what a run resolved, but it does not pin the next run. Repeatability comes from configuring an immutable `ref`.
+
+## Authenticate to private repositories
+
+Set one of these environment variables before running Federation:
+
+```bash
+export EVENTCATALOG_GITHUB_TOKEN=your-token
+```
+
+or:
+
+```bash
+export GITHUB_TOKEN=your-token
+```
+
+`EVENTCATALOG_GITHUB_TOKEN` takes precedence when both are set. The token needs read access to repository contents.
+
+For local development, place the token in the central catalog's `.env` file:
+
+```dotenv title=".env"
+EVENTCATALOG_GITHUB_TOKEN=your-token
+```
+
+Do not commit the token.
+
+## Configure several catalogs from one repository
+
+Give each catalog a different stable `id` and `path`:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    sources: [
+      {
+        id: 'acme/orders',
+        source: 'github:acme/architecture-catalogs',
+        path: 'orders',
+      },
+      {
+        id: 'acme/payments',
+        source: 'github:acme/architecture-catalogs',
+        path: 'payments',
+      },
+    ],
+  },
+};
+```
+
+Source IDs must be unique within the central configuration. Keep them stable if repositories or folders move, because the IDs are used in provenance, generated paths, diagnostics, and the lockfile.
+
+## Run Federation
+
+From the central catalog:
+
+```bash
+npx eventcatalog federate
+```
+
+If the source contains a `catalog.index.json`, Federation validates and uses it. Otherwise, Federation checks out the requested source and creates an index for the run.
+
+Run with verbose diagnostics when you need details for every warning:
+
+```bash
+npx eventcatalog federate --verbose
+```
+
+## Next steps
+
+- [Run Federation in CI](/docs/federation/how-to/run-in-ci)
+- [Use local sources during development](/docs/federation/how-to/use-local-sources)
+- Review the [source configuration reference](/docs/federation/reference/configuration#sources)

package/dist/docs/federation/how-to/configure-validation-rules.md

@@ -0,0 +1,127 @@
+---
+sidebar_position: 4
+sidebar_label: Configure validation rules
+title: Configure Federation validation rules
+description: Change federation diagnostics to off, warn, or error for your organization.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Federation rules work like lint rules. Every supported rule has one of three levels:
+
+| Level | Behavior |
+| --- | --- |
+| `off` | Do not report the diagnostic |
+| `warn` | Report the diagnostic and continue |
+| `error` | Report the diagnostic and stop before installing new output |
+
+Unconfigured rules keep the default levels shown below.
+
+## Available rules
+
+| Rule | Default | When it appears | Typical fix |
+| --- | --- | --- | --- |
+| `federation/duplicate-source` | `error` | More than one catalog documents and claims ownership of the same resource ID | Choose one owning catalog and remove copied or placeholder definitions from the others |
+| `federation/type-collision` | `error` | The same resource ID is documented with different types, such as an event in one catalog and a command in another | Correct the resource type or give the different resources unique IDs |
+| `federation/pointer-type-mismatch` | `error` | A relationship expects one resource type, but the referenced resource is documented as another type | Correct the relationship pointer or point it to the intended resource |
+| `federation/facet-disagreement` | `error` | Catalogs contribute contradictory information for the same resource facet | Choose an authoritative source and align or remove the conflicting contribution |
+| `federation/asset-collision` | `warn` | Remote catalogs publish different files to the same `public/` or `components/` path | Namespace the paths, make the files identical, or deliberately accept the last configured source as the winner |
+| `federation/missing-resource` | `warn` | A relationship references a resource ID that no participating catalog documents | Add the owning catalog, document the missing resource, or correct the referenced ID |
+| `federation/unresolved-version` | `warn` | The referenced resource exists, but none of its available versions satisfy the requested version or range | Reference an available version or publish a version that satisfies the request |
+
+Rules that default to `error` protect the catalog from ambiguous ownership or resource types. Rules that default to `warn` allow teams to onboard catalogs incrementally while keeping incomplete relationships and asset collisions visible.
+
+For the diagnostic messages and output attributes associated with each rule, see the [diagnostic rule reference](/docs/federation/reference/diagnostic-rules).
+
+## Add rule overrides
+
+Add `rules` beside `sources`:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    rules: {
+      'federation/missing-resource': 'error',
+      'federation/unresolved-version': 'error',
+      'federation/asset-collision': 'off',
+    },
+    sources: [
+      // ...
+    ],
+  },
+};
+```
+
+## Make unresolved references block a build
+
+Missing IDs and unavailable versions are warnings by default because organizations often introduce catalogs gradually.
+
+Use errors when every relationship in the organization view must resolve:
+
+```js title="eventcatalog.config.js"
+rules: {
+  'federation/missing-resource': 'error',
+  'federation/unresolved-version': 'error',
+}
+```
+
+This is useful in CI after all expected owning catalogs have been onboarded.
+
+## Keep asset collisions visible
+
+Asset collisions use `warn` by default. The last configured remote source wins when remote sources publish different content to the same path.
+
+Keep this warning enabled unless the collision is deliberate and reviewed:
+
+```js title="eventcatalog.config.js"
+rules: {
+  'federation/asset-collision': 'warn',
+}
+```
+
+The diagnostic identifies the asset path, all contributing sources, and the winning source.
+
+## Be careful with structural rules
+
+These rules default to `error` because continuing can produce an ambiguous organization model:
+
+- `federation/duplicate-source`
+- `federation/type-collision`
+- `federation/pointer-type-mismatch`
+- `federation/facet-disagreement`
+
+:::warning Changing ownership errors
+
+Changing a structural rule to `warn` or `off` allows Federation to continue with ambiguity that would normally block the update. Prefer fixing the ownership boundary, resource type, or relationship pointer.
+
+Use lower levels temporarily only when you understand how the resulting catalog will be interpreted.
+
+:::
+
+## Review warning details
+
+Run with `--verbose`:
+
+```bash
+npx eventcatalog federate --verbose
+```
+
+Warnings are grouped with their rule ID and attributes. Errors always show details, even without verbose output.
+
+## Validate the configuration
+
+Federation rejects unknown rule IDs and invalid levels. For example, `fatal` is not a valid level.
+
+Run Federation after editing the rules:
+
+```bash
+npx eventcatalog federate
+```
+
+## Next steps
+
+- Look up every [diagnostic rule](/docs/federation/reference/diagnostic-rules)
+- [Resolve common Federation problems](/docs/federation/reference/troubleshooting)
+- [Understand ownership and cross-catalog references](/docs/federation/explanation/ownership-and-references)

package/dist/docs/federation/how-to/run-in-ci.md

@@ -0,0 +1,138 @@
+---
+sidebar_position: 3
+sidebar_label: Run in CI
+title: Run EventCatalog Federation in CI
+description: Fetch and validate federated catalogs before building the organization catalog in CI.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Run Federation before the normal EventCatalog build so the generated organization view exists when EventCatalog renders the site.
+
+## Add explicit scripts
+
+Add separate and combined scripts to the central catalog:
+
+```json title="package.json"
+{
+  "scripts": {
+    "federate": "eventcatalog federate",
+    "build": "eventcatalog build",
+    "build:federated": "npm run federate && npm run build"
+  }
+}
+```
+
+Keeping `federate` and `build` separate makes it clear which stage failed. The combined script is useful for deployment platforms that accept one build command.
+
+## Provide your Enterprise license and repository tokens
+
+Federation requires an EventCatalog Enterprise offline license. Email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) to request a trial key.
+
+The simplest option is to commit `license.jwt` in the central catalog root. Federation will find it automatically when CI runs. If your organization prefers not to commit the file, store its contents in your CI provider and write `license.jwt` during the job. Set `EC_LICENSE` only when you write the file somewhere other than the catalog root.
+
+Provide these environment variables when needed:
+
+| Variable | When it is needed |
+| --- | --- |
+| `EC_LICENSE` | Optional path to the Enterprise offline license file when it is not stored at `./license.jwt` |
+| `EVENTCATALOG_GITHUB_TOKEN` | Recommended for private GitHub sources |
+| `GITHUB_TOKEN` | Used as a fallback when `EVENTCATALOG_GITHUB_TOKEN` is not set |
+
+GitHub tokens need read access to the configured repositories. Store those tokens in your CI provider's secret store rather than in `eventcatalog.config.js`.
+
+## Run the pipeline
+
+The CI sequence is:
+
+```bash
+npm ci
+npm run federate
+npm run build
+```
+
+or:
+
+```bash
+npm ci
+npm run build:federated
+```
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart LR
+  A[Install dependencies] --> B[Federate sources]
+  B --> C{Errors?}
+  C -->|Yes| D[Stop the pipeline]
+  C -->|No| E[Build EventCatalog]
+  E --> F[Deploy organization catalog]
+```
+
+</div>
+
+## Choose moving or immutable refs
+
+A branch such as `main` makes CI pick up new source commits whenever Federation runs. This is useful when the organization catalog should continuously follow each team.
+
+An exact commit SHA makes the configured source repeatable:
+
+```js title="eventcatalog.config.js"
+{
+  id: 'acme/payments',
+  source: 'github:acme/payments-catalog',
+  ref: '4a1b7e23c79b4ef9f5f337c5e7655a5ec82a4761',
+}
+```
+
+`eventcatalog.lock` records the source state selected by a completed run, but it does not control the next run. Use immutable `ref` values when repeatability is required.
+
+## Decide which warnings should block CI
+
+Promote important warning rules to `error` in the central configuration:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    rules: {
+      'federation/missing-resource': 'error',
+      'federation/unresolved-version': 'error',
+    },
+    sources: [/* ... */],
+  },
+};
+```
+
+This makes the federation command return an error before installing new output when a configured rule is violated.
+
+Review [Configure validation rules](/docs/federation/how-to/configure-validation-rules) before changing structural errors to warnings.
+
+## Cache downloaded content
+
+Federation stores verified content in `.eventcatalog-cache/federation/content/`. Persisting `.eventcatalog-cache` with your CI cache can reduce repeated downloads.
+
+Treat the cache as disposable. Federation checks content hashes before reuse and downloads content again when a valid entry is unavailable.
+
+Use `--no-cache` when investigating a cache problem:
+
+```bash
+npm run federate -- --no-cache
+```
+
+## Preserve useful failure output
+
+Errors always include their details. Warning details require `--verbose`:
+
+```bash
+npm run federate -- --verbose
+```
+
+Consider using verbose output in CI while Federation is being introduced, then switch back to the concise output if the logs become noisy.
+
+## Next steps
+
+- [Configure GitHub sources](/docs/federation/how-to/configure-github-sources)
+- [Configure validation rules](/docs/federation/how-to/configure-validation-rules)
+- [Understand the lockfile and cache](/docs/federation/explanation/lockfile-and-cache)

package/dist/docs/federation/how-to/share-assets-and-components.md

@@ -0,0 +1,125 @@
+---
+sidebar_position: 5
+sidebar_label: Share assets and components
+title: Share public assets and custom components through Federation
+description: Include source catalog images, files, and custom components in the organization catalog.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Federation includes top-level `public/` assets and `components/` custom components from source catalogs.
+
+Use this guide when federated resource pages depend on images, downloadable files, or custom components owned by the source catalog.
+
+## Add a public asset to a source catalog
+
+Keep the asset under the source catalog's `public/` directory:
+
+```text
+payments-catalog/
+├── public/
+│   └── payments/
+│       └── payment-flow.svg
+└── services/
+    └── payment-service/
+        └── index.mdx
+```
+
+Reference it from the source documentation as you normally would:
+
+```mdx
+![Payment flow](/payments/payment-flow.svg)
+```
+
+Run Federation from the central catalog:
+
+```bash
+npx eventcatalog federate
+```
+
+The asset is composed into the central `public/` directory so the federated page can use the same URL.
+
+## Avoid public asset collisions
+
+Use namespaced paths such as `public/payments/` and `public/orders/` rather than generic names such as `public/diagram.svg`.
+
+When remote sources publish different content to the same path:
+
+1. Federation reports `federation/asset-collision`.
+2. The last configured source wins.
+3. Verbose output names the path, sources, and winner.
+
+An existing public file owned by the central catalog is preserved instead of being overwritten by a remote source.
+
+## Understand managed public files
+
+`eventcatalog.lock` stores hashes and provenance for public files copied by Federation. On a later run, Federation can update or remove a file while avoiding deletion of a file that a user changed or the central catalog owns.
+
+If a previously managed file has been edited directly in the central `public/` directory, Federation preserves it.
+
+## Add a custom component to a source catalog
+
+Keep the component under the source catalog's top-level `components/` directory:
+
+```text
+payments-catalog/
+├── components/
+│   └── PaymentStatus.astro
+└── services/
+    └── payment-service/
+        └── index.mdx
+```
+
+Use it in source documentation through the normal EventCatalog custom component alias:
+
+```mdx
+import PaymentStatus from '@catalog/components/PaymentStatus.astro';
+
+<PaymentStatus status="available" />
+```
+
+Federation creates a shared `federated/components/` layer. When EventCatalog prepares the site, it combines federated components with the central catalog's own `components/` directory.
+
+## Override a federated component centrally
+
+Create a component at the same relative path in the central catalog:
+
+```text
+central-catalog/
+└── components/
+    └── PaymentStatus.astro
+```
+
+The central component overrides the federated component. Use this deliberately when the organization view needs a shared presentation that differs from the team catalog.
+
+Remote component path collisions are reported as asset collisions. Use source-specific component directories when components are not intended to be shared.
+
+## Install component dependencies centrally
+
+Federation copies component source files, not the source catalog's `package.json` dependencies. If a custom component imports an npm package, install a compatible dependency in the central catalog.
+
+Prefer self-contained components or document their central dependencies clearly.
+
+## Rerun after component changes
+
+Rerun Federation after changing a source component:
+
+```bash
+npx eventcatalog federate
+```
+
+Local file watching does not currently resynchronize components from another catalog.
+
+:::info Reusable snippets
+
+Top-level `snippets/` dependencies are not federated in the current release. A federated page should not import a snippet that exists only in its source catalog.
+
+:::
+
+## Next steps
+
+- [Understand generated Federation files](/docs/federation/reference/generated-output)
+- [Configure asset collision severity](/docs/federation/how-to/configure-validation-rules#keep-asset-collisions-visible)
+- [Troubleshoot asset and component problems](/docs/federation/reference/troubleshooting#public-assets-or-components-are-not-correct)