@eventcatalog/core 4.10.12 → 4.10.14

package/dist/docs/federation/how-to/use-local-sources.md

@@ -0,0 +1,138 @@
+---
+sidebar_position: 2
+sidebar_label: Use local sources
+title: Use local catalogs during development
+description: Run the federation pipeline against catalogs on your local filesystem.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Use filesystem sources to test cross-catalog relationships, ownership conflicts, rules, assets, and custom components before pushing source changes to GitHub.
+
+## Configure a filesystem source
+
+Set `source` to a `file:` locator:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    sources: [
+      {
+        id: 'acme/payments',
+        source: 'file:../payments-catalog',
+      },
+    ],
+  },
+};
+```
+
+The path after `file:` is resolved from the central catalog directory.
+
+Use `path` when the catalog is inside the selected filesystem source:
+
+```js title="eventcatalog.config.js"
+{
+  id: 'acme/payments',
+  source: 'file:../architecture-catalogs',
+  path: 'payments',
+}
+```
+
+Filesystem sources do not support `ref`.
+
+## Switch the same sources between local and GitHub
+
+Keep each source `id` and `path` stable, and select only the locator with an environment variable:
+
+```js title="eventcatalog.config.js"
+const federationSource =
+  process.env.EVENTCATALOG_FEDERATION_LOCAL === 'true'
+    ? 'file:..'
+    : 'github:acme/architecture-catalogs';
+
+export default {
+  federation: {
+    sources: [
+      {
+        id: 'acme/orders',
+        source: federationSource,
+        path: 'orders',
+      },
+      {
+        id: 'acme/payments',
+        source: federationSource,
+        path: 'payments',
+      },
+    ],
+  },
+};
+```
+
+Run against the local catalogs:
+
+```bash
+EVENTCATALOG_FEDERATION_LOCAL=true npx eventcatalog federate
+```
+
+Run against GitHub:
+
+```bash
+npx eventcatalog federate
+```
+
+## Add a local npm script
+
+For macOS and Linux, add a script to the central catalog:
+
+```json title="package.json"
+{
+  "scripts": {
+    "federate": "eventcatalog federate",
+    "federate:local": "EVENTCATALOG_FEDERATION_LOCAL=true eventcatalog federate"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run federate:local
+```
+
+On Windows, set `EVENTCATALOG_FEDERATION_LOCAL` using your shell's environment variable syntax or use a cross-platform environment helper.
+
+## Rerun after source changes
+
+Filesystem federation is currently one-shot. When a source catalog changes, rerun:
+
+```bash
+EVENTCATALOG_FEDERATION_LOCAL=true npx eventcatalog federate
+```
+
+The EventCatalog development watcher does not automatically rerun Federation for changes in another catalog.
+
+## Understand local revisions
+
+Federation creates a content-derived revision such as `local:92400b8dfbe1` for each local source. The value changes when indexed source content changes and is recorded in `eventcatalog.lock`.
+
+This revision identifies the state used by that run. It does not prevent later local edits from being selected by the next run.
+
+## Test a diagnostic
+
+To test organization-wide validation locally:
+
+1. Add a relationship in one catalog that points to a missing ID.
+2. Run local Federation with `--verbose`.
+3. Confirm the `federation/missing-resource` warning names the source catalog, referring resource, and missing resource.
+4. Add the resource to its owning catalog.
+5. Rerun Federation and confirm the warning disappears.
+
+> **_PLACEHOLDER_** — Terminal screenshot showing a locally triggered federation diagnostic.
+
+## Next steps
+
+- [Configure validation rules](/docs/federation/how-to/configure-validation-rules)
+- [Understand ownership and references](/docs/federation/explanation/ownership-and-references)
+- [Troubleshoot local source errors](/docs/federation/reference/troubleshooting#filesystem-source-errors)

package/dist/docs/{plugins/eventcatalog-federation → federation/legacy-federation}/00-introduction.md

@@ -10,6 +10,15 @@ description: Merge multiple EventCatalog instances into a single catalog
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import PluginLicense from '@site/src/components/MDX/PluginLicense';
 import Beta from '@site/src/components/MDX/Beta';
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+:::warning Legacy Federation
+
+This page documents the legacy `@eventcatalog/generator-federation` implementation. For new projects, use the [current built-in EventCatalog Federation](/docs/federation/overview).
+
+:::
 
 <!-- <Beta /> -->
 <AddedIn version="2.18.0" />
@@ -48,9 +57,9 @@ You can get a free 30-day trial Scale license key for the plugin.
 
 You can read more documentation:
 
-- [Configuring your main catalog](/docs/plugins/eventcatalog-federation/configuration)
+- [Configuring your main catalog](/docs/federation/legacy-federation/configuration)
     - This is the main catalog for your organization. It will pull in and merge documentation from your teams catalogs.
-- [Configuring your team catalogs](/docs/plugins/eventcatalog-federation/setup-team-catalog)
+- [Configuring your team catalogs](/docs/federation/legacy-federation/setup-team-catalog)
     - This is the documentation for how to setup your team catalogs
 
 ## Commercial Use

package/dist/docs/{plugins/eventcatalog-federation → federation/legacy-federation}/01-installation.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 keywords:
 - EventCatalog Federation
 sidebar_label: Installation
@@ -10,10 +10,19 @@ description: Installation of the EventCatalog Federation plugin
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import PluginLicense from '@site/src/components/MDX/PluginLicense';
 import Beta from '@site/src/components/MDX/Beta';
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+:::warning Legacy Federation
+
+This page documents the legacy `@eventcatalog/generator-federation` implementation. For new projects, use the [current built-in EventCatalog Federation](/docs/federation/overview).
+
+:::
 
 <PluginLicense url="#commercial-use" />
 
-The EventCatalog Federation plugin is designed for your [main catalog](/docs/plugins/eventcatalog-federation/configuration).
+The EventCatalog Federation plugin is designed for your [main catalog](/docs/federation/legacy-federation/configuration).
 
 This plugin will allow you to merge multiple EventCatalog instances into a single catalog.
 
@@ -178,4 +187,3 @@ npm run dev
 
 If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
 
-

package/dist/docs/{plugins/eventcatalog-federation → federation/legacy-federation}/02-plugin-configuration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
 keywords:
 - EventCatalog Federation
 sidebar_label: Plugin Configuration
@@ -7,6 +7,16 @@ title: Plugin Configuration
 description: Configuration of the EventCatalog Federation plugin
 ---
 
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+:::warning Legacy Federation
+
+This page documents the legacy `@eventcatalog/generator-federation` implementation. For new projects, use the [current built-in EventCatalog Federation](/docs/federation/overview).
+
+:::
+
 API Configuration for the EventCatalog Federation plugin
 
 
@@ -205,4 +215,3 @@ You can view an example configuration in the [EventCatalog Federation plugin Git
 
 
 
-

package/dist/docs/{plugins/eventcatalog-federation → federation/legacy-federation}/03-examples.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 4
 keywords:
 - components
 sidebar_label: Examples
@@ -7,6 +7,16 @@ title: Examples
 description: Examples of using the Federation plugin
 ---
 
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+:::warning Legacy Federation
+
+This page documents the legacy `@eventcatalog/generator-federation` implementation. For new projects, use the [current built-in EventCatalog Federation](/docs/federation/overview).
+
+:::
+
 You can find many examples of using the Federation plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
 
 ## Examples

package/dist/docs/{plugins/eventcatalog-federation → federation/legacy-federation}/04-configuration.md

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 5
 keywords:
 - EventCatalog components
 sidebar_label: Configuring main catalog
@@ -9,10 +10,19 @@ description: Configuring federation in your EventCatalog
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import PluginLicense from '@site/src/components/MDX/PluginLicense';
 import Beta from '@site/src/components/MDX/Beta';
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+:::warning Legacy Federation
+
+This page documents the legacy `@eventcatalog/generator-federation` implementation. For new projects, use the [current built-in EventCatalog Federation](/docs/federation/overview).
+
+:::
 
 <!-- <Beta /> -->
 <AddedIn version="2.18.0" />
-<PluginLicense url="/docs/plugins/eventcatalog-federation/intro#commercial-use" />
+<PluginLicense url="/docs/federation/legacy-federation/introduction#commercial-use" />
 
 EventCatalog Federation is powered by the [EventCatalog Federation Generator](https://github.com/event-catalog/generators), this let's you define the repositories you want to merge into your main catalog.
 

package/dist/docs/{plugins/eventcatalog-federation → federation/legacy-federation}/05-setup-team-catalog.md

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 6
 keywords:
 - EventCatalog components
 sidebar_label: Configuring team catalogs
@@ -9,10 +10,19 @@ description: Configuring federation in your EventCatalog
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import PluginLicense from '@site/src/components/MDX/PluginLicense';
 import Beta from '@site/src/components/MDX/Beta';
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+:::warning Legacy Federation
+
+This page documents the legacy `@eventcatalog/generator-federation` implementation. For new projects, use the [current built-in EventCatalog Federation](/docs/federation/overview).
+
+:::
 
 <!-- <Beta /> -->
 <AddedIn version="2.18.0" />
-<PluginLicense url="/docs/plugins/eventcatalog-federation/intro#commercial-use" />
+<PluginLicense url="/docs/federation/legacy-federation/introduction#commercial-use" />
 
 Multiple teams can own their own EventCatalog, this is useful if you have multiple teams that want to own their own EventCatalog / Documentation.
 
@@ -93,4 +103,3 @@ dependencies: {
 }
 // rest of your config
 ```
-

package/dist/docs/federation/legacy-federation/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Legacy Federation",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "federation/legacy-federation",
+    "title": "Legacy Federation",
+    "description": "Documentation for the legacy @eventcatalog/generator-federation implementation."
+  }
+}

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

@@ -0,0 +1,12 @@
+{
+  "label": "Reference",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "federation/reference",
+    "title": "Federation reference",
+    "description": "Lookup information for federation configuration, commands, diagnostics, generated files, and troubleshooting."
+  }
+}

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

@@ -0,0 +1,122 @@
+---
+sidebar_position: 2
+sidebar_label: CLI
+title: Federation CLI reference
+description: Command, option, environment variable, and output reference for eventcatalog federate.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Run Federation from the central catalog directory:
+
+```bash
+npx eventcatalog federate
+```
+
+The command loads `federation.sources` and `federation.rules` from `eventcatalog.config.js`.
+
+## Requirements
+
+- A central EventCatalog project
+- An EventCatalog Enterprise offline license file
+- At least one configured source, unless you are cleaning previous output
+- Git for GitHub sources that do not publish an index
+- Network and repository access for GitHub sources
+
+## Options
+
+| Option | Description | Default |
+| --- | --- | --- |
+| `--no-cache` | Disable content cache reads for this run and refresh fetched entries. | Reuse valid cached content |
+| `--verbose`, `-v` | Show the attributes for warning diagnostics. Error attributes are always shown. | Concise warning summary |
+| `--help`, `-h` | Show command help. |  |
+
+## Examples
+
+Run Federation:
+
+```bash
+npx eventcatalog federate
+```
+
+Show every warning:
+
+```bash
+npx eventcatalog federate --verbose
+```
+
+Refresh content without reading existing cache entries:
+
+```bash
+npx eventcatalog federate --no-cache
+```
+
+Pass options through an npm script:
+
+```bash
+npm run federate -- --verbose
+```
+
+Select local sources through a configuration environment variable:
+
+```bash
+EVENTCATALOG_FEDERATION_LOCAL=true npx eventcatalog federate
+```
+
+`EVENTCATALOG_FEDERATION_LOCAL` is not a built-in Federation variable. It is an example of using your own environment variable inside `eventcatalog.config.js`.
+
+## Environment variables
+
+Place the Enterprise `license.jwt` file in the central catalog root. You can commit it with the catalog or write it during CI/CD. If you store it elsewhere, set `EC_LICENSE` to its file path. Email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) to request an offline trial key.
+
+| Variable | Description |
+| --- | --- |
+| `EC_LICENSE` | Optional path to the Enterprise offline license file. Defaults to `license.jwt` in the catalog root. |
+| `EVENTCATALOG_GITHUB_TOKEN` | Preferred GitHub token for private repositories and authenticated content requests. |
+| `GITHUB_TOKEN` | GitHub token fallback when `EVENTCATALOG_GITHUB_TOKEN` is not set. |
+
+The command loads variables from `.env` in the central catalog before Federation starts.
+
+## Command stages
+
+The command reports progress for:
+
+1. Configured source discovery
+2. Source fetching and indexing
+3. Central catalog ownership indexing
+4. Graph resolution and diagnostics
+5. Content hydration and cache reuse
+6. Public asset composition
+7. Lockfile recording
+
+## Warning and error output
+
+Without `--verbose`, warnings produce a summary and a hint to rerun with verbose output.
+
+With `--verbose`, each diagnostic includes:
+
+- Severity
+- Human-readable message
+- Stable `federation/*` rule ID
+- Rule-specific attributes
+
+Errors always include their details and stop before new generated output is installed.
+
+## No configured sources
+
+When no sources are configured and no previous Federation state exists, the command reports that there is nothing to do.
+
+When previous output exists, running with an empty source list removes the previous `federated/` output, managed public files, and lockfile.
+
+## Generated files
+
+A successful run can update:
+
+- `federated/`
+- `public/` for managed remote public assets
+- `.eventcatalog-cache/federation/content/`
+- `eventcatalog.lock`
+
+See [Generated output reference](/docs/federation/reference/generated-output).

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',
+      },
+    ],
+  },
+};
+```