@eventcatalog/core 4.10.13 → 4.10.15

package/dist/docs/federation/00-overview.md

@@ -0,0 +1,158 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+title: EventCatalog Federation
+description: Combine independently owned EventCatalogs into one validated organization-wide catalog.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+EventCatalog Federation is a solution for distributed documentation across your organization. Teams document and own their services, domains, messages, ADRs, specifications, schemas, diagrams, and everything else EventCatalog supports in their own catalogs, while Federation combines them into one organization-wide view.
+
+Each team keeps its documentation, ownership, and review workflow in its own EventCatalog project. A central catalog selects those catalogs, validates them together, and materializes their resources as one connected catalog.
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart LR
+  subgraph TEAMS["Team-owned catalogs"]
+    direction TB
+    PAY["`**Payments team**
+    Services · APIs · events
+    ADRs · docs`"]
+    ORD["`**Orders team**
+    Services · commands · flows
+    ADRs · docs`"]
+    FUL["`**Fulfillment team**
+    Services · events · diagrams
+    ADRs · docs`"]
+  end
+
+  PAY --> FED["`**eventcatalog federate**
+  Merge · resolve · validate`"]
+  ORD --> FED
+  FUL --> FED
+  FED --> ORG["`**Organization catalog**
+  One connected view`"]
+
+  classDef team fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
+  classDef federation fill:#f5f3ff,stroke:#8b5cf6,color:#2e1065
+  classDef central fill:#ecfdf5,stroke:#10b981,color:#064e3b
+  class PAY,ORD,FUL team
+  class FED federation
+  class ORG central
+  style TEAMS fill:#f8fafc,stroke:#cbd5e1,stroke-dasharray:5 5,color:#475569
+```
+
+</div>
+
+Federation is useful when one catalog repository or one documentation team would become a bottleneck. Each team can document its part of the architecture close to the people and code that own it, while the organization still gets one place to discover resources and follow relationships.
+
+## What Federation gives you
+
+Use Federation to:
+
+- Combine resources from multiple EventCatalog projects
+- Resolve relationships between catalogs
+- Validate organization-wide ownership and resource types
+- Include schemas, specifications, sidecar documentation, public assets, and custom components
+- Test federation against local catalogs before using remote sources
+- Fetch public or private catalogs from GitHub
+- Treat selected diagnostics as warnings, errors, or disabled rules
+- Keep the previous generated output when an update fails
+
+## The central catalog is still an EventCatalog
+
+The central catalog can own organization-wide documentation of its own, such as cross-domain flows, shared architecture decisions, or enterprise domains. Its local resources participate in the same ownership validation as federated resources.
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart LR
+  subgraph TEAMS["Team-owned catalogs"]
+    direction TB
+    ORD["`**Orders team**
+    Services · commands · docs`"]
+    PAY["`**Payments team**
+    Services · APIs · events`"]
+    FUL["`**Fulfillment team**
+    Services · events · diagrams`"]
+  end
+
+  FED["`**eventcatalog federate**
+  Hydrate · resolve · validate`"]
+
+  subgraph CENTRAL["Central catalog"]
+    direction TB
+    LOCAL["`**Central-owned documentation**
+    Organization flows · ADRs · domains`"]
+    REMOTE["`**Federated resources**
+    Generated into federated/`"]
+    VIEW["`**Organization catalog**
+    One connected view`"]
+
+    LOCAL --> VIEW
+    REMOTE --> VIEW
+  end
+
+  ORD --> FED
+  PAY --> FED
+  FUL --> FED
+  FED --> REMOTE
+
+  classDef team fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
+  classDef federation fill:#f5f3ff,stroke:#8b5cf6,color:#2e1065
+  classDef central fill:#ecfdf5,stroke:#10b981,color:#064e3b
+  class ORD,PAY,FUL team
+  class FED federation
+  class LOCAL,REMOTE central
+  class VIEW central
+  style TEAMS fill:#f8fafc,stroke:#cbd5e1,stroke-dasharray:5 5,color:#475569
+  style CENTRAL fill:#f8fafc,stroke:#cbd5e1,stroke-dasharray:5 5,color:#475569
+```
+
+</div>
+
+The generated content is written to `federated/`. The normal EventCatalog development server or build then reads the local and federated resources together.
+
+## Federation is explicit
+
+The current workflow has two separate commands:
+
+```bash
+npx eventcatalog federate
+npm run build
+```
+
+`eventcatalog federate` fetches, validates, and materializes the configured sources. `npm run build` renders the resulting catalog. Federation does not run automatically before `dev`, `build`, or `generate`.
+
+:::info Enterprise feature
+
+EventCatalog Federation requires an EventCatalog Enterprise offline license. To try it, email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) and we will send you an offline trial key. Save the `license.jwt` file in the root of your central catalog before running Federation.
+
+Learn more about [offline license validation](/docs/development/license-keys/license-validation#offline-validation).
+
+:::
+
+## Built-in Federation and the Federation generator
+
+These docs describe the built-in `eventcatalog federate` workflow. It uses catalog indexes, graph validation, content hashes, and generated federation output.
+
+It is different from the older `@eventcatalog/generator-federation` integration, which clones repositories and copies configured directories through the generator pipeline.
+
+## Current release status
+
+Federation is being released as an initial working version for feedback. The core composition and validation workflow is ready to use, while operational features such as automatic build integration, source management commands, frozen lockfile installs, and local file watching may evolve from user feedback.
+
+Read [MVP status and feedback](/docs/federation/explanation/mvp-status-and-feedback) for the current boundaries.
+
+## Next steps
+
+- Follow the [first federation tutorial](/docs/federation/first-federation).
+- Learn [how Federation works](/docs/federation/explanation/how-it-works).
+- [Configure GitHub sources](/docs/federation/how-to/configure-github-sources).
+- [Use local catalogs during development](/docs/federation/how-to/use-local-sources).
+- Look up the complete [configuration reference](/docs/federation/reference/configuration).
+- Review the [diagnostic rule reference](/docs/federation/reference/diagnostic-rules).

package/dist/docs/federation/01-first-federation.md

@@ -0,0 +1,199 @@
+---
+sidebar_position: 2
+sidebar_label: First federation tutorial
+title: Federate your first catalogs
+description: Create two local EventCatalog projects and combine them into one organization catalog.
+slug: /federation/first-federation
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+This tutorial takes you through the first successful Federation workflow:
+
+1. Create a team catalog
+2. Create an empty organization catalog
+3. Configure the team catalog as a local source
+4. Run Federation
+5. Open the combined catalog
+
+The goal is to learn the federation loop before introducing GitHub, CI, or organization-wide validation rules.
+
+## What you will build
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart LR
+  TEAM["`**team-catalog/**
+  Services · messages · docs`"]
+  FED["`**eventcatalog federate**
+  Fetch · validate · hydrate`"]
+  ORG["`**organization-catalog/**
+  Local + federated resources`"]
+
+  TEAM -->|local source| FED
+  FED --> ORG
+
+  classDef team fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
+  classDef federation fill:#f5f3ff,stroke:#8b5cf6,color:#2e1065
+  classDef central fill:#ecfdf5,stroke:#10b981,color:#064e3b
+  class TEAM team
+  class FED federation
+  class ORG central
+```
+
+</div>
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- [Node.js 22 or later](https://nodejs.org/en/download/)
+- Git installed
+- An EventCatalog Enterprise offline license. Email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) to request a trial key.
+- A terminal and text editor
+
+Check Node and Git with:
+
+```bash
+node -v
+git --version
+```
+
+## Create the tutorial catalogs
+
+Create a directory for the tutorial:
+
+```bash
+mkdir federation-tutorial
+cd federation-tutorial
+```
+
+Create a team catalog with the sample resources included by the EventCatalog installer:
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest team-catalog
+```
+
+Create an empty catalog that will become the organization view:
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest organization-catalog --empty
+```
+
+You now have two sibling projects:
+
+```text
+federation-tutorial/
+├── team-catalog/
+└── organization-catalog/
+```
+
+## Add your Enterprise license
+
+Federation uses an offline Enterprise license. Save the `license.jwt` file we send you in the root of the organization catalog:
+
+```text
+organization-catalog/
+├── license.jwt
+├── eventcatalog.config.js
+└── package.json
+```
+
+To try Federation, email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) and ask for an offline trial key. You can commit `license.jwt` with the central catalog so it is available locally and in CI/CD. If your organization prefers not to commit it, provide the file during your CI/CD job instead.
+
+## Configure the local source
+
+Open `organization-catalog/eventcatalog.config.js` and add `federation.sources` to the exported configuration:
+
+```js title="organization-catalog/eventcatalog.config.js"
+export default {
+  // Keep the settings created by the installer...
+  federation: {
+    sources: [
+      {
+        id: 'tutorial/team-catalog',
+        source: 'file:../team-catalog',
+      },
+    ],
+  },
+};
+```
+
+The source path is relative to the organization catalog. The `id` is the stable identity Federation uses for ownership, generated paths, and diagnostics.
+
+## Ignore generated output
+
+Add the generated federation directory and cache to `organization-catalog/.gitignore`:
+
+```gitignore title="organization-catalog/.gitignore"
+federated/
+.eventcatalog-cache/
+```
+
+Do not edit files under `federated/`. Federation replaces that directory on a successful run.
+
+## Run Federation
+
+Move into the organization catalog and run the command:
+
+```bash
+cd organization-catalog
+
+# If this does not work, add federate script in your package.json "federate: eventcatalog federate"
+npm run federate
+```
+
+A successful run ends with output similar to:
+
+```text
+[federation] Graph resolved: 20 remote resources, 28 relationships
+[federation] Federation complete: 1 source, 20 remote resources, 35 files written
+[federation] Recorded resolved source state in eventcatalog.lock
+```
+
+The exact resource and file counts depend on the current starter catalog.
+
+Federation has now created:
+
+- `federated/` containing the team catalog resources
+- `.eventcatalog-cache/federation/content/` containing verified reusable content
+- `eventcatalog.lock` recording the source state resolved by this run
+
+## Open the organization catalog
+
+Start the organization catalog:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000). The resources from `team-catalog` now appear in the organization catalog.
+
+## Make a source change
+
+Stop the development server, then change the name or documentation of a resource in `team-catalog`.
+
+Run Federation again from `organization-catalog`:
+
+```bash
+npx eventcatalog federate
+```
+
+Start the development server again. The organization view now contains the updated source content.
+
+Local filesystem sources are one-shot inputs. You need to rerun `eventcatalog federate` after a source changes.
+
+## What you learned
+
+You have completed the core federation loop:
+
+- A team catalog owns its source documentation
+- The organization catalog selects it through configuration
+- Federation indexes, validates, and materializes the source
+- The normal EventCatalog application renders the combined view
+- Rerunning Federation updates the generated output
+
+Next, learn how to [configure GitHub sources](/docs/federation/how-to/configure-github-sources), [resolve relationships across catalogs](/docs/federation/explanation/ownership-and-references), or [run Federation in CI](/docs/federation/how-to/run-in-ci).

package/dist/docs/federation/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Federation",
+  "position": 3,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "federation",
+    "title": "EventCatalog Federation",
+    "description": "Combine independently owned EventCatalogs into one validated organization-wide catalog."
+  }
+}

package/dist/docs/federation/explanation/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Explanation",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "federation/explanation",
+    "title": "Federation explanation",
+    "description": "Conceptual guides that explain composition, ownership, resolution, generated output, caching, and the federation lockfile."
+  }
+}

package/dist/docs/federation/explanation/how-it-works.md

@@ -0,0 +1,129 @@
+---
+sidebar_position: 1
+sidebar_label: How Federation works
+title: How EventCatalog Federation works
+description: Understand how EventCatalog indexes, resolves, and materializes several catalogs into one organization view.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+EventCatalog Federation is a build-time composition process.
+
+It reads independently owned catalogs, converts them into a common index, validates the combined graph, and writes generated catalog files that the normal EventCatalog application can render.
+
+## The three-stage pipeline
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart LR
+  A[Source catalogs] --> B[Index]
+  B --> C[Resolve]
+  C --> D{Blocking diagnostics?}
+  D -->|Yes| E[Keep previous output]
+  D -->|No| F[Hydrate]
+  F --> G[Generated organization view]
+```
+
+</div>
+
+### Index
+
+Each source catalog is described as facts:
+
+- Resource IDs, types, and versions
+- Resource ownership and relationships
+- Content paths and hashes
+- Schemas and specifications
+- Sidecar documentation
+- Public assets and custom components
+
+Federation operates on EventCatalog's existing files and frontmatter. Teams do not maintain a second federation-specific resource definition.
+
+### Resolve
+
+Federation combines the indexes into one graph. The resolver:
+
+- Connects relationships across source boundaries
+- Selects resource versions for relationship pointers
+- Detects multiple owners for one resource ID
+- Detects conflicting resource types
+- Detects relationship type mismatches
+- Identifies missing resources and unavailable versions
+- Chooses a deterministic winner for remote asset collisions
+
+The central catalog's local resources participate in ownership validation. A local flow or architecture decision can point to federated resources, while a local resource can also conflict with a remote owner.
+
+### Hydrate
+
+After validation succeeds, Federation fetches the selected resource files and writes them under `federated/`.
+
+Schemas, specifications, sidecars, public assets, and custom components travel with their owning resources. Content hashes are checked before files are accepted.
+
+The normal EventCatalog build then reads local and federated content together.
+
+## How sources are acquired
+
+Federation currently supports GitHub and local filesystem sources.
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart TB
+  CFG[eventcatalog.config.js] --> ROUTE{Source locator}
+  ROUTE -->|github:| GH[Fetch published index or create one from checkout]
+  ROUTE -->|file:| FS[Index the current local directory]
+  GH --> IDX[Catalog index]
+  FS --> IDX
+  IDX --> RESOLVE[Shared resolver and hydration pipeline]
+```
+
+</div>
+
+A GitHub source can publish `catalog.index.json`. If the file exists, Federation checks its source ID and uses it. If the file does not exist, Federation creates an index from a temporary checkout.
+
+A filesystem source is indexed directly. Its revision is derived from the indexed content so the completed run can record which local state it used.
+
+After source acquisition, both source types use the same validation, hydration, caching, asset, and lockfile behavior.
+
+## Federation materializes files
+
+Federation does not make live requests to team catalogs when somebody opens the organization site.
+
+The generated files are a local representation of the last successful federation run:
+
+```text
+central-catalog/
+├── domains/                  # centrally owned resources
+├── federated/                # generated source resources
+├── public/                   # central and managed remote assets
+├── eventcatalog.lock         # completed-run receipt and managed asset state
+└── .eventcatalog-cache/      # reusable verified content
+```
+
+This means the organization catalog can be built and deployed through the same process as any other EventCatalog after Federation completes.
+
+## Failed updates preserve the previous view
+
+Federation validates the graph before hydration. Output changes are staged, and the lockfile is written after the generated resources and public assets are composed.
+
+If a normal update fails while installing new output, Federation attempts to restore the previous `federated/` directory and affected public assets. A bad source update should not replace the last successful organization view with partial output.
+
+## Federation is explicit
+
+The federation command and EventCatalog build are separate:
+
+```bash
+npx eventcatalog federate
+npm run build
+```
+
+This keeps source acquisition and graph validation visible in local workflows and CI. The current release does not automatically federate before `dev`, `build`, or `generate`.
+
+## Related guides
+
+- [Ownership and cross-catalog references](/docs/federation/explanation/ownership-and-references)
+- [Lockfile and cache](/docs/federation/explanation/lockfile-and-cache)
+- [Generated output reference](/docs/federation/reference/generated-output)

package/dist/docs/federation/explanation/lockfile-and-cache.md

@@ -0,0 +1,134 @@
+---
+sidebar_position: 3
+sidebar_label: Lockfile and cache
+title: Federation lockfile and content cache
+description: Understand what eventcatalog.lock records, what it does not pin, and how the Federation cache works.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Federation writes two kinds of local state:
+
+- `eventcatalog.lock` records the source state and managed public files from a completed run.
+- `.eventcatalog-cache/` stores verified content that can be reused by later runs.
+
+They solve different problems.
+
+<div className="federation-mermaid">
+
+```mermaid
+flowchart LR
+  CFG[eventcatalog.config.js] -->|controls next run| RUN[eventcatalog federate]
+  CACHE[.eventcatalog-cache/] <--> |reuses verified content| RUN
+  RUN -->|records completed run| LOCK[eventcatalog.lock]
+  RUN --> OUT[federated/]
+```
+
+</div>
+
+## What the lockfile records
+
+For each source, `eventcatalog.lock` records:
+
+- The stable source ID
+- The Git commit or content-derived local revision used by the run
+- A digest of the resolved source index
+- The time the source was resolved
+
+It also records the hash and source of public files managed by Federation. This allows a later run to update or remove generated public files without deleting files owned or modified by the central catalog.
+
+A simplified lockfile looks like:
+
+```json title="eventcatalog.lock"
+{
+  "lockVersion": 1,
+  "sources": [
+    {
+      "id": "acme/payments",
+      "digest": "sha256:...",
+      "commit": "4a1b7e23c79b4ef9f5f337c5e7655a5ec82a4761",
+      "resolvedAt": "2026-08-21T10:30:00.000Z"
+    }
+  ],
+  "publicFiles": {
+    "payments/payment-flow.svg": {
+      "source": "acme/payments",
+      "hash": "sha256:..."
+    }
+  }
+}
+```
+
+## The lockfile does not control the next run
+
+The current lockfile is a completed-run receipt and managed-output record. It is not read as a package-manager-style source lock.
+
+Every Federation run:
+
+- Resolves the configured GitHub `ref` again
+- Re-indexes the current files for a `file:` source
+- Writes a new lockfile after the update succeeds
+
+If `ref` is `main`, a later run can select a newer commit. To make a source repeatable, configure `ref` as an exact commit SHA.
+
+:::warning Do not describe the current lockfile as a pin
+
+The commit in `eventcatalog.lock` tells you what the completed run used. It does not force the next run to use that commit.
+
+:::
+
+## Should the lockfile be committed?
+
+It is safe to commit `eventcatalog.lock` when you want:
+
+- An auditable record of the last completed federation run
+- Managed public-file state shared between environments
+- Source revisions visible during code review
+
+Expect a moving branch or edited local source to update the lockfile. Committing it does not by itself make future builds repeatable.
+
+## How the content cache works
+
+Federation stores content under:
+
+```text
+.eventcatalog-cache/
+└── federation/
+    └── content/
+```
+
+Cache entries are addressed by SHA-256 content hashes. Before reusing an entry, Federation calculates its hash again. A corrupt or mismatched entry is discarded instead of being hydrated.
+
+The cache avoids downloading identical resource files, schemas, specifications, sidecars, and assets on every run.
+
+## Ignore or persist the cache
+
+Add the cache to `.gitignore`:
+
+```gitignore
+.eventcatalog-cache/
+```
+
+The cache is disposable. You can remove it when you need to reclaim disk space; the next run downloads the required content again.
+
+The current release does not prune old content automatically, so a long-lived cache can grow as source content changes.
+
+Persisting `.eventcatalog-cache` in CI can improve repeat build times, but it is not required for correctness.
+
+## Refresh cached content
+
+Use `--no-cache` to disable cache reads for one run:
+
+```bash
+npx eventcatalog federate --no-cache
+```
+
+Federation fetches the required content and writes valid content back to the cache. The option refreshes cache entries; it does not permanently disable caching.
+
+## Related guides
+
+- [Run Federation in CI](/docs/federation/how-to/run-in-ci)
+- [Generated output reference](/docs/federation/reference/generated-output)
+- [CLI reference](/docs/federation/reference/cli)