@eventcatalog/core 4.10.12 → 4.10.14

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)

package/dist/docs/federation/explanation/mvp-status-and-feedback.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 4
+sidebar_label: MVP status and feedback
+title: Federation MVP status and feedback
+description: Understand the current Federation release boundaries and how to share useful feedback.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+EventCatalog Federation is being introduced as an initial working release for feedback.
+
+The core workflow is ready to combine real catalogs, validate ownership, and build an organization-wide view. The first release deliberately keeps source configuration and execution explicit while EventCatalog learns how teams want to operate Federation.
+
+## What is included
+
+The MVP includes:
+
+- GitHub sources
+- Local filesystem sources for development
+- Indexing and hydration of EventCatalog resources
+- Cross-catalog relationship and version resolution
+- Central catalog ownership validation
+- Schemas, specifications, sidecar files, public assets, and custom components
+- Configurable `off`, `warn`, and `error` diagnostic rules
+- Content hashing and a verified local cache
+- Stale generated-output cleanup
+- Restoration of previous output after a normal failed update
+- A lockfile that records completed source and managed public-file state
+
+## Current boundaries
+
+The first release does not include:
+
+- `add`, `status`, or `dry-run` source management commands
+- Automatic Federation before `dev`, `build`, or `generate`
+- Local source watcher integration
+- A frozen mode that installs the commits recorded in `eventcatalog.lock`
+- Graph diff commands
+- Automatic cache pruning
+- Parallel source fetching
+- A command for publishing `catalog.index.json`
+- Federation of top-level reusable `snippets/`
+
+Sources are configured manually in `eventcatalog.config.js` and processed with:
+
+```bash
+npx eventcatalog federate
+```
+
+These constraints are intentional for the feedback release. They keep the contract small while the team observes which operational workflows matter in real organizations.
+
+## Useful areas for feedback
+
+When you try Federation, consider:
+
+- Is editing `federation.sources` directly clear enough?
+- Do you prefer moving branches or immutable commits?
+- Which diagnostics should block your organization catalog?
+- Does local filesystem Federation give you a useful development loop?
+- How often do resource, asset, or component collisions occur?
+- Should Federation run manually, in CI, or automatically before builds?
+- Do your teams share custom components, reusable snippets, or npm dependencies?
+- How large are your catalogs and how long does a Federation run take?
+- What information would you expect from future `status` or diff commands?
+
+## Share feedback
+
+The most useful feedback includes:
+
+- What you were trying to federate
+- The number and approximate size of the source catalogs
+- Whether the sources were GitHub or local
+- What worked
+- What was confusing
+- The diagnostic or workflow that blocked you
+- What you expected Federation to do
+
+Share feedback in the [EventCatalog Discord](https://eventcatalog.dev/discord) or [open an issue in the EventCatalog repository](https://github.com/event-catalog/eventcatalog/issues).
+
+## Related guides
+
+- [EventCatalog Federation overview](/docs/federation/overview)
+- [How Federation works](/docs/federation/explanation/how-it-works)
+- [Troubleshooting Federation](/docs/federation/reference/troubleshooting)