@eventcatalog/core 4.10.13 → 4.10.15

package/dist/docs/federation/reference/configuration.md

@@ -0,0 +1,192 @@
+---
+sidebar_position: 1
+sidebar_label: Configuration
+title: Federation configuration reference
+description: Reference for federation sources and rule levels in eventcatalog.config.js.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Configure Federation under the `federation` key in the central catalog's `eventcatalog.config.js`.
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    rules: {
+      'federation/missing-resource': 'error',
+    },
+    sources: [
+      {
+        id: 'acme/payments',
+        source: 'github:acme/payments-catalog',
+        path: 'catalog',
+        ref: 'main',
+      },
+    ],
+  },
+};
+```
+
+## `federation`
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `sources` | `FederationSourceConfig[]` | Yes | Catalogs included in the organization view. Use an empty array to remove previous Federation output. |
+| `rules` | `Record<FederationRuleId, FederationRuleLevel>` | No | Overrides diagnostic levels. Unconfigured rules keep their defaults. |
+
+## Sources
+
+Each entry in `federation.sources` selects one EventCatalog project.
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `id` | `string` | Yes |  | Stable source identity used by indexes, ownership, generated paths, diagnostics, and the lockfile. |
+| `source` | `string` | Yes |  | Source locator. Supported protocols are `github:` and `file:`. |
+| `path` | `string` | No | `.` | Catalog directory within the selected repository or filesystem source. |
+| `ref` | `string` | No | `main` | GitHub branch, tag, or commit. Not supported by filesystem sources. |
+
+### Source IDs
+
+Every source requires a non-empty `id`, and the same ID cannot be configured more than once.
+
+Use stable organization-oriented IDs:
+
+```js
+{
+  id: 'acme/payments',
+  source: 'github:acme/payments-catalog',
+}
+```
+
+Changing the repository or directory does not require changing the ID. Keeping it stable preserves understandable provenance and generated paths.
+
+If a GitHub source publishes `catalog.index.json`, its `source` value must exactly match the configured `id`.
+
+### GitHub locator
+
+Syntax:
+
+```text
+github:<owner>/<repository>
+```
+
+Example at the repository root:
+
+```js
+{
+  id: 'acme/payments',
+  source: 'github:acme/payments-catalog',
+}
+```
+
+Example in a monorepo:
+
+```js
+{
+  id: 'acme/payments',
+  source: 'github:acme/architecture-catalogs',
+  path: 'catalogs/payments',
+  ref: 'production',
+}
+```
+
+GitHub authentication is read from `EVENTCATALOG_GITHUB_TOKEN`, then `GITHUB_TOKEN` as a fallback.
+
+### Filesystem locator
+
+Syntax:
+
+```text
+file:<path-from-central-catalog>
+```
+
+Example:
+
+```js
+{
+  id: 'acme/payments',
+  source: 'file:../payments-catalog',
+}
+```
+
+Example with a catalog inside the selected source root:
+
+```js
+{
+  id: 'acme/payments',
+  source: 'file:../architecture-catalogs',
+  path: 'payments',
+}
+```
+
+Filesystem sources reject `ref`. Paths must remain within the selected source root, including after symbolic links are resolved.
+
+## Rules
+
+Every rule accepts:
+
+```ts
+'off' | 'warn' | 'error'
+```
+
+| Rule ID | Default |
+| --- | --- |
+| `federation/duplicate-source` | `error` |
+| `federation/type-collision` | `error` |
+| `federation/pointer-type-mismatch` | `error` |
+| `federation/facet-disagreement` | `error` |
+| `federation/asset-collision` | `warn` |
+| `federation/missing-resource` | `warn` |
+| `federation/unresolved-version` | `warn` |
+
+Example:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    rules: {
+      'federation/duplicate-source': 'error',
+      'federation/missing-resource': 'error',
+      'federation/asset-collision': 'off',
+    },
+    sources: [/* ... */],
+  },
+};
+```
+
+Unknown rule IDs and values other than `off`, `warn`, or `error` cause a configuration error.
+
+See the [diagnostic rule reference](/docs/federation/reference/diagnostic-rules) for triggers and output attributes.
+
+## Complete conditional source example
+
+This example uses local sibling catalogs during development and GitHub in shared environments:
+
+```js title="eventcatalog.config.js"
+const source =
+  process.env.EVENTCATALOG_FEDERATION_LOCAL === 'true'
+    ? 'file:..'
+    : 'github:acme/architecture-catalogs';
+
+export default {
+  federation: {
+    rules: {
+      'federation/unresolved-version': 'error',
+    },
+    sources: [
+      {
+        id: 'acme/orders',
+        source,
+        path: 'orders',
+      },
+      {
+        id: 'acme/payments',
+        source,
+        path: 'payments',
+      },
+    ],
+  },
+};
+```

package/dist/docs/federation/reference/diagnostic-rules.md

@@ -0,0 +1,173 @@
+---
+sidebar_position: 3
+sidebar_label: Diagnostic rules
+title: Federation diagnostic rule reference
+description: Reference for every Federation rule, default level, trigger, output attributes, and resolution.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Federation diagnostics use stable rule IDs. Configure each rule as `off`, `warn`, or `error` under `federation.rules`.
+
+| Rule | Default | Summary |
+| --- | --- | --- |
+| `federation/duplicate-source` | `error` | A resource has multiple owning catalogs |
+| `federation/type-collision` | `error` | One resource ID is documented with conflicting types |
+| `federation/pointer-type-mismatch` | `error` | A relationship expects the wrong target type |
+| `federation/facet-disagreement` | `error` | Catalogs provide contradictory facets for a resource |
+| `federation/asset-collision` | `warn` | Remote sources publish different files at one asset path |
+| `federation/missing-resource` | `warn` | A relationship points to an ID that is not present |
+| `federation/unresolved-version` | `warn` | The target ID exists, but its requested version does not |
+
+## `federation/duplicate-source`
+
+**Message:** `Resource has multiple owners`
+
+Triggered when the same resource ID and type are owned by more than one catalog. All versions of one resource ID must have the same owner.
+
+Attributes:
+
+| Attribute | Meaning |
+| --- | --- |
+| `resource` | Conflicting resource ID |
+| `catalogs` | Catalogs claiming ownership |
+| `resolution` | Suggested ownership action |
+
+Resolution: choose one owning catalog. Remove copied or placeholder resource definitions from consumers.
+
+## `federation/type-collision`
+
+**Message:** `Resource ID has conflicting types`
+
+Triggered when the same resource ID is documented as different EventCatalog resource types, such as an event in one catalog and a command in another.
+
+Attributes:
+
+| Attribute | Meaning |
+| --- | --- |
+| `resource` | Conflicting resource ID |
+| `<catalog ID>` | Type documented by that catalog |
+
+Resolution: correct the resource type or use distinct IDs for different resources.
+
+## `federation/pointer-type-mismatch`
+
+**Message:** `Reference type does not match resource`
+
+Triggered when a relationship pointer expects one target type but the resolved resource has another type.
+
+Attributes:
+
+| Attribute | Meaning |
+| --- | --- |
+| `resource` | Referenced resource ID |
+| `expected type` | Type required by the relationship |
+| `actual type` | Type documented by the owner |
+| `catalogs` | Catalogs involved in the mismatch |
+
+Resolution: correct the pointer or point it to the intended resource ID.
+
+## `federation/facet-disagreement`
+
+**Message:** `Catalogs disagree about this resource`
+
+Represents contradictory contributed facets for a resource, such as incompatible content supplied for the same facet by several catalogs.
+
+Attributes:
+
+| Attribute | Meaning |
+| --- | --- |
+| `resource` | Resource ID with contradictory facets |
+| `detail` | Available disagreement detail |
+| `catalogs` | Catalogs contributing the conflicting values |
+
+Resolution: decide which source is authoritative and align or remove the conflicting contribution.
+
+## `federation/asset-collision`
+
+**Message:** `Asset collision`
+
+Triggered when remote sources publish different content to the same `public/` or `components/` path.
+
+Attributes:
+
+| Attribute | Meaning |
+| --- | --- |
+| `asset` | Conflicting catalog-relative asset path |
+| `sources` | Sources publishing the path |
+| `winner` | Source selected by Federation |
+| `resolution` | Selection rule, currently `last configured source wins` |
+
+Resolution: namespace the paths, make the files identical, or deliberately order the sources and keep the warning visible.
+
+An existing public asset owned by the central catalog is preserved.
+
+## `federation/missing-resource`
+
+**Message:** `Referenced EventCatalog resource does not exist`
+
+Triggered when a relationship points to a resource ID that is not documented by any participating remote or central catalog.
+
+Attributes:
+
+| Attribute | Meaning |
+| --- | --- |
+| `source catalog` | Catalog containing the relationship pointer |
+| `referenced by` | Resource containing the pointer |
+| `missing resource` | Missing ID and requested version, when present |
+
+Resolution: add the owning catalog, document the resource in its owner, or correct the pointer ID.
+
+## `federation/unresolved-version`
+
+**Message:** `Referenced EventCatalog resource version does not exist`
+
+Triggered when the resource ID exists, but no available version satisfies the pointer.
+
+Attributes:
+
+| Attribute | Meaning |
+| --- | --- |
+| `source catalog` | Catalog containing the relationship pointer |
+| `referenced by` | Versioned resource containing the pointer |
+| `resource` | Target resource ID |
+| `requested version` | Exact version, range, or authored pointer value |
+| `available versions` | Versions published by the owner |
+
+Resolution: change the pointer to an available version or publish a matching version in the owning catalog.
+
+## Configure levels
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    rules: {
+      'federation/missing-resource': 'error',
+      'federation/unresolved-version': 'error',
+      'federation/asset-collision': 'off',
+    },
+    sources: [/* ... */],
+  },
+};
+```
+
+Changing structural rules from `error` can allow ambiguous ownership or types into the generated view. See [Configure validation rules](/docs/federation/how-to/configure-validation-rules).
+
+## Operational errors without rule IDs
+
+Some failures stop Federation directly and do not have configurable `federation/*` rule IDs. These include:
+
+- Missing or invalid license access
+- Duplicate configured source IDs
+- Unsupported source locators
+- GitHub authentication or network failures
+- Missing filesystem source directories
+- Unsafe source, catalog, or artifact paths
+- Invalid published indexes
+- Content hash mismatches
+- Unreadable lockfiles
+- Filesystem write or rollback failures
+
+See [Troubleshooting Federation](/docs/federation/reference/troubleshooting).

package/dist/docs/federation/reference/generated-output.md

@@ -0,0 +1,118 @@
+---
+sidebar_position: 5
+sidebar_label: Generated output
+title: Federation generated output reference
+description: Reference for federated resources, shared components, public assets, the lockfile, and content cache.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+A successful Federation run can create or update four locations in the central catalog:
+
+```text
+central-catalog/
+├── federated/
+├── public/
+├── .eventcatalog-cache/
+└── eventcatalog.lock
+```
+
+## `federated/`
+
+Federated resource files are grouped by stable source identity:
+
+```text
+federated/
+├── acme-payments--0cfe83f789ab/
+│   ├── domains/
+│   ├── services/
+│   ├── events/
+│   ├── teams/
+│   └── users/
+├── acme-orders--7575b99c8b32/
+│   ├── domains/
+│   ├── services/
+│   └── events/
+└── components/
+```
+
+The directory name contains:
+
+- A filesystem-safe form of the source `id`
+- A short hash of the complete source `id`
+
+The hash prevents different IDs that produce the same safe text from sharing a directory.
+
+Resource-relative files remain with their resource, including:
+
+- Schemas
+- OpenAPI, AsyncAPI, and GraphQL specifications
+- Sidecar documentation and files
+- Diagrams and other resource-local content
+
+Do not edit `federated/`. It is replaced by the next successful run.
+
+## `federated/components/`
+
+Top-level custom components from remote catalogs are materialized into the shared `federated/components/` directory.
+
+When EventCatalog prepares the application, federated components form the base layer and the central catalog's local `components/` directory is applied afterward. A local component at the same relative path overrides the federated component.
+
+Top-level reusable `snippets/` are not federated in the current release.
+
+## `public/`
+
+Remote `public/` assets are first hydrated, then composed into the central catalog's `public/` directory.
+
+Selection rules:
+
+1. When several remote sources publish different content at one path, the last configured source wins and `federation/asset-collision` is reported.
+2. When the central catalog already owns the path, the central file is preserved.
+3. When a previously managed remote file was changed manually, Federation preserves it instead of treating it as managed output.
+4. When a managed remote file disappears from all sources, a later successful run removes it.
+
+Managed public-file hashes and source IDs are stored in `eventcatalog.lock`.
+
+## `eventcatalog.lock`
+
+The lockfile records:
+
+- `lockVersion`
+- Source IDs
+- Source commits or local content revisions
+- Source index digests
+- Resolution times
+- Managed public files
+
+It is written after a successful output update. It records what the run used but does not control the next run.
+
+See [Federation lockfile and content cache](/docs/federation/explanation/lockfile-and-cache).
+
+## `.eventcatalog-cache/`
+
+Federation content is cached under:
+
+```text
+.eventcatalog-cache/federation/content/
+```
+
+Entries use SHA-256 content keys and are verified before reuse. The cache is disposable and should normally be ignored by Git.
+
+The current release does not automatically remove content that is no longer referenced, so the cache can grow over time.
+
+## Cleanup when sources change
+
+On a successful run:
+
+- Resources no longer present in an index disappear from `federated/`
+- Removed sources disappear from `federated/`
+- Stale managed public files are removed
+- New source content replaces the previous generated content
+
+When `federation.sources` becomes empty, the command removes previous Federation output, managed public files, and the lockfile.
+
+## Failed output updates
+
+Federation stages new output and snapshots affected public files. If a normal output update fails, it attempts to restore the previous generated resources and public assets. The previous lockfile remains associated with the previous successful view.

package/dist/docs/federation/reference/supported-content.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 4
+sidebar_label: Supported content
+title: Federation supported content
+description: Reference for resources, files, assets, and catalog-level content included by Federation.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Federation indexes and materializes normal EventCatalog resource content from every configured source.
+
+## Supported resources
+
+The current release supports:
+
+- Architecture decision records (ADRs)
+- Agents
+- Channels
+- Commands
+- Data products
+- Data stores (`container` resources)
+- Diagrams
+- Domains and subdomains
+- Entities
+- Events
+- Flows
+- Queries
+- Services
+- Systems
+- Teams
+- Users
+
+Resource versions remain with their owner and are included in cross-catalog version resolution.
+
+## Resource files
+
+Federation includes files associated with supported resources:
+
+- Markdown and MDX resource documentation
+- Schemas attached to events, commands, and queries
+- OpenAPI, AsyncAPI, and GraphQL specifications
+- Resource-local sidecar documentation
+- Resource-local images, diagrams, examples, and other files
+- Changelog and version documentation stored with the resource
+
+Paths and content hashes from the source index are used to fetch and verify these files.
+
+## Teams and users
+
+Top-level teams and users are included. Give shared people and teams one owning catalog to avoid organization-wide duplicate ownership.
+
+## Public assets
+
+Files under a source catalog's top-level `public/` directory are included and composed into the central `public/` directory.
+
+Remote collisions use last-configured-source-wins and report `federation/asset-collision`. Existing central public files are preserved.
+
+See [Share public assets and custom components](/docs/federation/how-to/share-assets-and-components).
+
+## Custom components
+
+Files under a source catalog's top-level `components/` directory are included in the federated component layer.
+
+Central components override federated components at the same relative path. Any npm packages imported by a federated component must be installed in the central catalog.
+
+## Content not included
+
+The current release does not federate:
+
+- Top-level reusable `snippets/`
+- Custom pages and API routes
+- `eventcatalog.config.js` settings from source catalogs
+- Source catalog themes, navigation, or global styles
+- Source `package.json` dependencies
+- `node_modules/`, build output, or cache directories
+- Content already under a source catalog's generated `federated/` directory
+
+The central catalog owns its application configuration, navigation, theme, custom pages, global dependencies, and build process.
+
+## Why generated Federation content is excluded
+
+When a source catalog is itself a central view, its generated `federated/` directory is excluded from indexing. This prevents generated paths from being nested repeatedly and avoids treating copied output as newly authored ownership.
+
+Only content owned by the selected source catalog is indexed for the next composition level.