@eventcatalog/core 4.10.13 → 4.10.15

package/dist/docs/development/developer-tools/eventcatalog-linter/00-overview.md

@@ -0,0 +1,76 @@
+---
+sidebar_position: 1
+slug: /development/developer-tools/eventcatalog-linter
+keywords:
+- EventCatalog linter
+- schema validation
+- reference validation
+- CI/CD
+- quality assurance
+sidebar_label: Overview
+title: EventCatalog Linter
+description: Catch broken references, typos, misplaced files and missing metadata in your EventCatalog before they reach a build or a reader.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The EventCatalog Linter is a command-line tool that checks your catalog for the mistakes EventCatalog itself would otherwise ignore or only surface at build time: a service that `sends` an event that doesn't exist, a typo like `owner:` instead of `owners:`, a `schemaPath` that points at nothing, or a file saved in a folder EventCatalog never reads.
+
+Run it locally while you write documentation, or in CI so every pull request is checked.
+
+```bash
+npx @eventcatalog/linter
+```
+
+```
+services/order-service/index.mdx
+   6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
+   9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
+  14:1 ⚠ warning Resource should have a markdown description (body content) beyond just frontmatter [description] (best-practices/description-required)
+
+✖ 3 problems (2 errors, 1 warning) in 1 file
+  178 files checked
+```
+
+## What it checks
+
+| Area | Examples |
+|------|----------|
+| **Frontmatter schemas** | Required fields, field types, version formats, unknown or misspelled keys |
+| **References** | Owners, messages, services, domains, channels, containers, flow steps and entity relationships point at resources (and versions) that exist |
+| **Files** | `schemaPath`, `schemas[]`, `specifications`, data product contracts and `public/` icons resolve to real files |
+| **Catalog structure** | Duplicate ids, markdown files in places EventCatalog won't load |
+| **Documentation quality** | Summaries, owners, body content and message schemas are present |
+| **Versioning** | References to deprecated resources |
+
+Every finding comes with a `line:column` position, the rule that produced it, and — where the linter can work it out — a suggestion for the fix.
+
+## Where to go next
+
+- **[Set up the linter](./01-setup.md)** — a guided walk-through from the first run to a CI check. Start here if you haven't used the linter before.
+- **[How-to guides](/docs/development/developer-tools/eventcatalog-linter/how-to)** — recipes for specific jobs: [configure rules](./how-to/01-configure-rules.md), [run in CI](./how-to/02-run-in-ci.md), [allow custom frontmatter](./how-to/03-use-custom-frontmatter.md), [reference resources from other catalogs](./how-to/04-reference-external-catalogs.md), [fix common problems](./how-to/05-fix-common-problems.md).
+- **[Reference](/docs/development/developer-tools/eventcatalog-linter/reference)** — every [CLI option](./reference/01-cli.md), the [configuration file](./reference/02-configuration.md), [all rules](./reference/03-rules.md) with their messages and options, [version formats](./reference/04-versions.md) and the [files the linter scans](./reference/05-supported-resources.md).
+
+## What's new
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+The latest release focuses on catching the mistakes people actually make and pointing at exactly where they are:
+
+- **Line and column numbers** on every finding, so terminals and editors can jump straight to the problem.
+- **Unknown frontmatter keys** are flagged with "did you mean" suggestions ([`schema/unknown-field`](./reference/03-rules.md#schemaunknown-field)). EventCatalog fails the build on these; the linter now catches them first.
+- **Misplaced files** — `events/OrderCreated.mdx` instead of `events/OrderCreated/index.mdx`, `event/` instead of `events/`, users saved as folders — are reported with the intended location ([`structure/unrecognised-file`](./reference/03-rules.md#structureunrecognised-file)).
+- **Broken file references** — `schemaPath`, specifications, contracts and icons that don't exist ([`refs/file-exists`](./reference/03-rules.md#refsfile-exists)).
+- **Clearer reference errors**: "this resource doesn't exist — did you mean `OrderCreated`?" is now distinct from "this resource exists, but not at version `2.1.0` — available: `2.0.0`, `1.0.0`".
+- **Version formats match EventCatalog**: `1`, `1.2`, `v1` and `V2` are accepted everywhere EventCatalog accepts them.
+- `eventcatalog-linter --init` scaffolds a fully commented config; `--quiet`, `--max-warnings` and `--no-color` were added; progress output stays out of CI logs; the summary reports how many files were actually checked.
+
+Read the [rules reference](./reference/03-rules.md) for the full list, or the [original announcement](/blog/eventcatalog-linter) for the background.
+
+## Supported resources
+
+The linter understands every resource type EventCatalog does: domains and subdomains, systems, services, events, commands, queries, channels, flows, entities, agents, containers, data products, diagrams, ADRs, users and teams — including versioned copies under `versioned/` and content pulled in through federation. See [Supported resources](./reference/05-supported-resources.md) for the exact folders and file names it scans.
+
+## Issues?
+
+If you have any issues or feedback, please open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord server](https://eventcatalog.dev/discord).

package/dist/docs/development/developer-tools/eventcatalog-linter/01-setup.md

@@ -0,0 +1,144 @@
+---
+sidebar_position: 2
+sidebar_label: Setup linter
+title: Set up the linter
+description: Run the EventCatalog Linter for the first time, read its output, fix a problem, create a configuration file, and add the check to CI.
+---
+
+This guide takes you from a fresh catalog to a linted, CI-checked one: run the linter, read what it reports, fix a problem, create a configuration file, and add a pull-request check. It takes about ten minutes.
+
+## What you need
+
+- An EventCatalog project. If you don't have one, `npx @eventcatalog/create-eventcatalog@latest my-catalog` creates one with example content.
+- Node.js 18 or later.
+
+## 1. Run the linter
+
+From the root of your catalog (the folder containing `eventcatalog.config.js`):
+
+```bash
+npx @eventcatalog/linter
+```
+
+You don't need to install anything first. The linter scans your `domains/`, `services/`, `events/` and other resource folders, validates every file, and prints what it found:
+
+```
+✔ No problems found!
+  178 files checked
+```
+
+If your catalog is already clean, congratulations — skip to [step 4](#4-create-a-configuration-file) to see how to customise it. Otherwise, keep reading.
+
+## 2. Read the output
+
+Let's introduce a couple of mistakes on purpose so there is something to look at. Open any service — for example `services/order-service/index.mdx` — and change `owners:` to `owner:`, then misspell one of the events it sends:
+
+```yaml title="services/order-service/index.mdx"
+---
+id: order-service
+name: Order Service
+version: 1.0.0
+summary: Handles orders
+owner:
+  - platform-team
+sends:
+  - id: OrderCreatd
+---
+```
+
+Run the linter again:
+
+```
+services/order-service/index.mdx
+   2:1 ✖ error At least one owner is required [owners] (best-practices/owner-required)
+   6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
+   9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
+
+✖ 3 problems (3 errors, 0 warnings) in 1 file
+  178 files checked
+```
+
+Each line has the same shape:
+
+| Part | Meaning |
+|------|---------|
+| `6:1` | Line and column in the file. Most terminals let you click `path:line:col`. |
+| `✖ error` / `⚠ warning` | Severity. Errors fail the run; warnings don't unless you ask them to. |
+| The message | What is wrong, and a suggestion when the linter can work one out. |
+| `[owner]` | The frontmatter field the finding is about. |
+| `(schema/unknown-field)` | The rule that produced it — look it up in the [rules reference](./reference/rules). |
+
+Notice that one typo produced two findings: `owner` is unknown **and** `owners` is missing. That's expected — fixing the typo clears both.
+
+## 3. Fix the problems
+
+Change `owner` back to `owners` and `OrderCreatd` to `OrderCreated`, then re-run. You should be back to `✔ No problems found!`.
+
+That loop — run, read, fix — is how you'll use the linter day to day. Because the message includes the line number and a suggestion, most fixes are a single edit. The [fix common problems](./how-to/fix-common-problems) guide covers the messages you're most likely to meet.
+
+## 4. Create a configuration file
+
+Defaults are sensible, but every team has its own standards. Let the linter write a starting point for you:
+
+```bash
+npx @eventcatalog/linter --init
+```
+
+```
+✔ Created .eventcatalogrc.js
+  178 catalog files found, CommonJS config written
+```
+
+Open `.eventcatalogrc.js`. Every rule is listed with a one-line description and its default severity:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    // Best practices
+    // Resources have a summary
+    'best-practices/summary-required': 'error',
+    // Resources have at least one owner
+    'best-practices/owner-required': 'error',
+    // Resources have markdown body content beyond the frontmatter
+    'best-practices/description-required': 'warn',
+    // ...
+  },
+  ignorePatterns: [],
+  overrides: [],
+};
+```
+
+Try changing one rule. Perhaps your team doesn't want body content to be a warning yet:
+
+```js
+'best-practices/description-required': 'off',
+```
+
+Run the linter again and the warning is gone. The three values are `'error'`, `'warn'` and `'off'`; the [configure rules guide](./how-to/configure-rules) covers options, ignore patterns and per-folder overrides.
+
+## 5. Add the check to your pipeline
+
+The linter exits with code `1` when it finds errors, which is all a CI system needs. For GitHub Actions:
+
+```yaml title=".github/workflows/lint-catalog.yml"
+name: Lint catalog
+on: [pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx @eventcatalog/linter --max-warnings 0
+```
+
+`--max-warnings 0` makes warnings fail the build too. If you'd rather let warnings through, drop the flag. In CI the linter automatically keeps its progress spinner out of the logs, so you only see findings. See [Run in CI](./how-to/run-in-ci) for GitLab and other pipelines.
+
+## Next steps
+
+- [Configure rules](./how-to/configure-rules) for your team's standards, including per-folder overrides.
+- [Reference resources from other catalogs](./how-to/reference-external-catalogs) if your services consume events documented elsewhere.
+- Browse the [rules reference](./reference/rules) to see everything the linter can catch.

package/dist/docs/development/developer-tools/eventcatalog-linter/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "EventCatalog Linter",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "doc",
+    "id": "development/developer-tools/eventcatalog-linter/overview"
+  }
+}

package/dist/docs/development/developer-tools/eventcatalog-linter/how-to/01-configure-rules.md

@@ -0,0 +1,130 @@
+---
+sidebar_position: 1
+sidebar_label: Configure rules
+title: Configure linter rules
+description: Change rule severities, pass rule options, ignore files, and apply different rules to different parts of the catalog.
+---
+
+Use this guide when the defaults don't match your team's standards. All configuration lives in a `.eventcatalogrc.js` file in the catalog root; see the [configuration reference](../reference/configuration) for the full shape.
+
+## Create the file
+
+The fastest start is the scaffold, which lists every rule with its description and default:
+
+```bash
+npx @eventcatalog/linter --init
+```
+
+Or write it by hand. Anything you leave out keeps its default, so a config can be as small as one line:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    'best-practices/description-required': 'off',
+  },
+};
+```
+
+:::tip ESM catalogs
+If your catalog's `package.json` has `"type": "module"`, write `export default { ... }` instead of `module.exports = { ... }`. `--init` detects this for you.
+:::
+
+## Change a rule's severity
+
+Each rule takes one of three values:
+
+| Value | Effect |
+|-------|--------|
+| `'error'` | Reported and fails the run (exit code 1) |
+| `'warn'` | Reported but doesn't fail the run, unless you pass `--fail-on-warning` or `--max-warnings` |
+| `'off'` | Not checked |
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    'best-practices/owner-required': 'warn', // soften
+    'refs/orphan-messages': 'error',         // tighten
+    'best-practices/schema-required': 'off', // disable
+  },
+};
+```
+
+Rule names are listed in the [rules reference](../reference/rules).
+
+## Pass options to a rule
+
+Some rules accept options. Use the array form `[severity, options]`:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    'schema/unknown-field': ['error', { allow: ['costCenter', 'legacy*'] }],
+    'refs/file-exists': ['error', { icons: false }],
+  },
+};
+```
+
+The [rules reference](../reference/rules) documents which rules take options and what they mean.
+
+## Ignore files
+
+`ignorePatterns` skips files entirely — they are neither validated nor counted:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  ignorePatterns: ['drafts/**', 'domains/Legacy/**'],
+};
+```
+
+`dependencies/**` is always ignored (it's where EventCatalog writes mocked external resources).
+
+:::note
+Patterns are matched against the path relative to the catalog root, and `**/` at the very start of a pattern currently requires at least one leading folder — write `drafts/**` rather than `**/drafts/**` to ignore a top-level `drafts` folder.
+:::
+
+## Apply different rules to different folders
+
+`overrides` re-configures rules for files matching a glob. Later overrides win over earlier ones, and all of them win over the top-level `rules`:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    'best-practices/owner-required': 'error',
+  },
+  overrides: [
+    {
+      files: ['domains/Legacy/**'],
+      rules: {
+        'best-practices/owner-required': 'warn',
+        'best-practices/summary-required': 'off',
+      },
+    },
+    {
+      files: ['**/containers/**'],
+      rules: {
+        'best-practices/description-required': 'off',
+      },
+    },
+  ],
+};
+```
+
+Options work inside overrides too: `'schema/unknown-field': ['warn', { allow: ['legacyId'] }]`.
+
+## Which rules to keep strict
+
+Rules fall into two groups. `schema/*`, `refs/*` and `structure/*` findings mean EventCatalog will fail the build, drop data or mis-render something — keep those as `'error'`. `best-practices/*`, `refs/orphan-messages` and `versions/no-deprecated-references` are documentation-quality opinions; tune them to your team's standards, and use overrides to relax them for legacy areas while enforcing them for new content.
+
+## Check what's in effect
+
+The config merges with the defaults at load time. If a rule doesn't behave the way you expect:
+
+1. Check the rule name against the [rules reference](../reference/rules) — a misspelled rule name is silently ignored.
+2. Check whether an override matches the file; overrides are applied in order.
+3. Run with `--quiet` to confirm whether a finding is an error or a warning.
+
+## Related
+
+- [Configuration reference](../reference/configuration)
+- [Rules reference](../reference/rules)
+- [Allow custom frontmatter](./use-custom-frontmatter)

package/dist/docs/development/developer-tools/eventcatalog-linter/how-to/02-run-in-ci.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 2
+sidebar_label: Run in CI
+title: Run the linter in CI
+description: Fail pull requests on catalog problems with GitHub Actions, GitLab CI, or any pipeline that can run npx.
+---
+
+Use this guide to make the linter a required check on every change to your catalog.
+
+## How the linter signals failure
+
+- Exit code `1` when any **error** is reported, or when warnings exceed `--max-warnings`.
+- Exit code `0` otherwise, including when only warnings are reported.
+- Progress output (the spinner) is written to stderr and switched off automatically when the process is not attached to a terminal or `CI=true` is set, so logs contain only findings.
+
+Pick the strictness you want:
+
+```bash
+npx @eventcatalog/linter                    # fail on errors only
+npx @eventcatalog/linter --max-warnings 0   # fail on any warning too
+npx @eventcatalog/linter --max-warnings 10  # tolerate up to 10 warnings
+npx @eventcatalog/linter --quiet            # hide warnings from the log entirely
+```
+
+`--fail-on-warning` is the same as `--max-warnings 0`.
+
+## GitHub Actions
+
+```yaml title=".github/workflows/lint-catalog.yml"
+name: Lint catalog
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx @eventcatalog/linter --max-warnings 0
+```
+
+If the catalog lives in a subfolder of the repository, pass the path: `npx @eventcatalog/linter ./catalog`.
+
+## GitLab CI
+
+```yaml title=".gitlab-ci.yml"
+lint-catalog:
+  stage: test
+  image: node:20
+  script:
+    - npx @eventcatalog/linter --max-warnings 0
+```
+
+## Pin the version
+
+`npx @eventcatalog/linter` resolves the latest release every time. For reproducible builds, add it to your catalog's `package.json` and run the local copy:
+
+```bash
+npm install --save-dev @eventcatalog/linter
+```
+
+```json title="package.json"
+{
+  "scripts": {
+    "lint": "eventcatalog-linter --max-warnings 0"
+  }
+}
+```
+
+Then use `npm run lint` in the pipeline. The version is bumped through your normal dependency-update process.
+
+## Run before every commit
+
+If you use a pre-commit tool such as Husky or lefthook, call the same script. The linter checks the whole catalog rather than only changed files, which keeps reference checks accurate — a change to one service can break a reference in another.
+
+## Keep CI green while you adopt the linter
+
+On an existing catalog the first run may report a lot. Two approaches that work well:
+
+1. **Start permissive, tighten over time.** Set noisy rules to `'warn'` in `.eventcatalogrc.js`, run with `--max-warnings <current count>`, and lower the number as you fix things.
+2. **Scope by folder.** Use [`overrides`](./configure-rules#apply-different-rules-to-different-folders) to relax rules for legacy areas while enforcing them fully for new content.
+
+Either way, keep `schema/*`, `refs/*` and `structure/*` as errors — those are the findings that mean EventCatalog will silently drop or fail to build something.
+
+## Related
+
+- [CLI reference](../reference/cli) — every option and exit code
+- [Configure rules](./configure-rules)

package/dist/docs/development/developer-tools/eventcatalog-linter/how-to/03-use-custom-frontmatter.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 3
+sidebar_label: Allow custom frontmatter
+title: Allow custom frontmatter fields
+description: Add your own metadata to resources without tripping the unknown-field rule.
+---
+
+Use this guide when you need extra fields in frontmatter — a cost centre, a data classification, a Jira key — and the linter reports them as unknown.
+
+## Why the linter complains
+
+EventCatalog validates frontmatter against a schema and rejects top-level keys it doesn't know at build time. The linter's [`schema/unknown-field`](../reference/rules#schemaunknown-field) rule mirrors that, so a typo like `owner:` is caught before the build, and so is any custom field:
+
+```
+services/order-service/index.mdx
+  8:1 ✖ error Unknown property "costCenter". Custom properties must start with "x-". [costCenter] (schema/unknown-field)
+```
+
+## Option 1: use the `x-` prefix (recommended)
+
+EventCatalog reserves the `x-` prefix for custom properties. Both EventCatalog and the linter accept any key that starts with it, at any level of the frontmatter:
+
+```yaml title="services/order-service/index.mdx"
+---
+id: order-service
+name: Order Service
+version: 1.0.0
+x-cost-center: CC-1234
+x-jira-project: ORD
+sends:
+  - id: OrderCreated
+    x-internal: true
+---
+```
+
+Custom properties are rendered in the catalog and available to your own components — see [Custom properties on resources](/docs/development/customization/custom-properties).
+
+## Option 2: allow specific keys
+
+If you can't rename a field yet, tell the rule to ignore it. `allow` takes exact key names or `prefix*` patterns and applies to both the top-level and nested rules:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    'schema/unknown-field': ['error', { allow: ['costCenter', 'legacy*'] }],
+  },
+};
+```
+
+:::warning
+Allowed keys are still unknown to EventCatalog. Top-level ones will fail `eventcatalog build`; nested ones are silently ignored. Treat `allow` as a stepping stone to the `x-` prefix, not a destination.
+:::
+
+## Turn off the suggestions
+
+The rule adds "Did you mean …?" hints and tells you when a key belongs to a different resource type. To keep only the bare message:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    'schema/unknown-field': ['error', { suggestions: false }],
+  },
+};
+```
+
+## Relax nested-field checks
+
+Unknown keys inside nested objects (`sends[0].too`) are reported by a separate rule, [`schema/unknown-nested-field`](../reference/rules#schemaunknown-nested-field), which defaults to `warn` because EventCatalog ignores them rather than failing. Adjust it independently:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    'schema/unknown-nested-field': 'off',
+  },
+};
+```
+
+## Related
+
+- [Custom properties on resources](/docs/development/customization/custom-properties)
+- [Rules reference: schema rules](../reference/rules#schema-validation)

package/dist/docs/development/developer-tools/eventcatalog-linter/how-to/04-reference-external-catalogs.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 4
+sidebar_label: Reference external catalogs
+title: Reference resources documented in other catalogs
+description: Stop the linter reporting missing resources when a service sends or receives messages that another team documents.
+---
+
+Use this guide when your catalog references resources that live somewhere else — typically another team's catalog — and the linter reports them as missing:
+
+```
+services/order-service/index.mdx
+  11:9 ✖ error Referenced event/command/query "PaymentAuthorised" does not exist [receives[0]] (refs/resource-exists)
+```
+
+## Declare the resources as dependencies
+
+EventCatalog lets you list external resources in the `dependencies` section of `eventcatalog.config.js`. EventCatalog renders a placeholder page for each one, and the linter treats them as existing:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  dependencies: {
+    events: [
+      { id: 'PaymentAuthorised' },
+      { id: 'PaymentDeclined', version: '2.0.0' },
+    ],
+    services: [{ id: 'payment-service' }],
+  },
+};
+```
+
+- Without a `version`, the dependency satisfies any reference to that id (it behaves like `latest`).
+- With a `version`, references must match that version, using the same [matching rules](../reference/versions) as local resources.
+- Dependency messages are never reported as orphans.
+
+Any resource type can be listed: `events`, `commands`, `queries`, `services`, `domains`, `systems`, `channels`, `flows`, `entities`, `containers`, `data-products`, `diagrams`, `agents`, `adrs`, `users`, `teams`.
+
+The linter reads `eventcatalog.config.js` from the directory you point it at. Both CommonJS and ES module configs are supported on current Node.js versions; if the file can't be loaded, the linter prints a warning and continues without dependencies.
+
+## Federated content
+
+If you use [EventCatalog Federation](/docs/federation/overview), resources materialised under `federated/<catalog>/` are scanned like local ones. Owners, services and messages from federated catalogs resolve without any extra configuration.
+
+## Ignore the generated `dependencies` folder
+
+EventCatalog writes placeholder files for dependencies into a `dependencies/` folder. The linter ignores that folder by default, so you don't need to add it to `ignorePatterns`.
+
+## Related
+
+- [Mocking out dependencies (legacy federation guide)](/docs/federation/legacy-federation/setup-team-catalog#mocking-out-dependencies-in-your-catalog)
+- [Version formats and matching](../reference/versions)