@eventcatalog/core 4.10.13 → 4.10.15

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)

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)