@eventcatalog/core 4.10.12 → 4.10.14

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)

package/dist/docs/development/developer-tools/eventcatalog-linter/how-to/05-fix-common-problems.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 5
+sidebar_label: Fix common problems
+title: Fix common linter findings
+description: What the most frequent linter messages mean and the quickest way to resolve each one.
+---
+
+Use this guide as a lookup table when the linter reports something and you want the fix, not the theory. Findings are grouped by rule; every rule is documented in full in the [rules reference](../reference/rules).
+
+## "Unknown property … Did you mean …?"
+
+```
+6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
+```
+
+A frontmatter key isn't part of the schema — almost always a typo. Rename it to the suggestion. If it's a deliberate custom field, prefix it with `x-` (see [Allow custom frontmatter](./use-custom-frontmatter)).
+
+If the message says the key "is valid on service resources, but not on event resources", you've copied frontmatter from one resource type to another; remove the key or use the equivalent for that type (for example events use `producers`/`consumers`, services use `sends`/`receives`).
+
+## "… is not recognised as an EventCatalog resource and will be ignored"
+
+```
+1:1 ⚠ warning File "events/OrderCreated.mdx" is not recognised … Did you mean "events/OrderCreated/index.mdx"? (structure/unrecognised-file)
+```
+
+The file is in a place EventCatalog never reads. Move it to the suggested path. The common shapes:
+
+| You have | You need |
+|----------|----------|
+| `events/OrderCreated.mdx` | `events/OrderCreated/index.mdx` |
+| `event/…`, `Services/…`, `comands/…` | `events/…`, `services/…`, `commands/…` |
+| `users/john/index.mdx` | `users/john.mdx` (users and teams are flat files) |
+| `events/OrderCreated/versioned/index.mdx` | `events/OrderCreated/versioned/1.0.0/index.mdx` |
+| `services/order-service/notes.mdx` | `services/order-service/docs/notes.mdx` (only `index.mdx` is a resource) |
+
+See [Supported resources](../reference/supported-resources) for every folder the linter scans.
+
+## "Referenced … does not exist"
+
+```
+9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
+```
+
+The id doesn't match any resource of the expected type. Check for:
+
+- **A typo** — the message suggests the closest id.
+- **The wrong type** — "`payment-service` exists as a service, not a event/command/query" means the id is real but you referenced it from a field that expects a different type.
+- **A resource from another catalog** — declare it in `dependencies` (see [Reference external catalogs](./reference-external-catalogs)).
+- **A resource the linter can't see** — it may be misplaced (look for an accompanying `structure/unrecognised-file` warning) or matched by an `ignorePatterns` entry.
+
+## "… does not have a version matching …"
+
+```
+9:14 ✖ error Referenced event "OrderCreated" does not have a version matching "3.0.0". Available versions: 2.0.0, 1.0.0 [sends[0]] (refs/valid-version-range)
+```
+
+The resource exists, but not at that version. Either pick one of the listed versions, use a range (`^2.0.0`, `2.x`) or `latest`, or add the missing version under `versioned/`. Version formats and matching are described in the [versions reference](../reference/versions).
+
+If the message says the reference "has an invalid version reference", the value isn't a version, range or `latest` at all — for example `two` or `version-1`.
+
+## "Referenced schema file … does not exist"
+
+```
+7:13 ✖ error Referenced schema file "schema.json" does not exist (looked for "events/OrderCreated/schema.json") [schemaPath] (refs/file-exists)
+```
+
+The path in `schemaPath`, `schemas[]`, `specifications` or a data product contract doesn't resolve to a file. Paths are relative to the resource's own folder — so a versioned copy under `versioned/1.0.0/` needs its own `schema.json` next to it. The "looked for" path shows exactly where the linter checked.
+
+For `styles.icon`, paths starting with `/` are checked against the catalog's `public/` folder. If your static assets live elsewhere, set `['error', { publicDir: 'static' }]` or disable icon checks with `{ icons: false }`.
+
+## "version: Expected string, but received undefined"
+
+```
+2:1 ✖ error version: Expected string, but received undefined [version] (schema/valid-type)
+```
+
+A required field is missing — here `version`. Add it. The same rule reports fields of the wrong type, such as `owners: platform-team` (a string) instead of a list.
+
+## "Invalid semantic version format"
+
+```
+4:10 ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+```
+
+Use a format EventCatalog understands: semver (`1.2.3`, `1.0.0-beta`), a number-like version (`1`, `1.2`, `v1`, `V2`) or `latest`. Values like `one`, `1.0.0.0` or `version-1` are rejected.
+
+## "… has no producer and no consumer"
+
+```
+2:5 ⚠ warning event "OrderCreated" has no producer and no consumer [id] (refs/orphan-messages)
+```
+
+Nothing sends or receives the message, so it won't appear in any visualiser. Add it to a service's `sends` or `receives`, list `producers`/`consumers` on the message itself, or — if it's intentionally standalone — set the rule to `'off'` for that folder using an override.
+
+## "At least one owner is required" / "Summary is required"
+
+Add `owners:` (a list of user or team ids) or `summary:` to the resource. If a resource type genuinely shouldn't need these in your catalog, relax the rule for that folder:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  overrides: [{ files: ['**/containers/**'], rules: { 'best-practices/owner-required': 'off' } }],
+};
+```
+
+## "Duplicate … also defined in …"
+
+Two files declare the same type, `id` and `version`. Usually one is a leftover copy or a versioned file whose `version` wasn't updated — delete one or correct the version.
+
+## "Parse error: …"
+
+```
+5:14 ✖ error Parse error: unexpected end of the stream within a flow collection (@eventcatalog/parse-error)
+```
+
+The frontmatter isn't valid YAML. The position points at the failing token; look for unbalanced brackets, a missing space after a colon, or inconsistent indentation.
+
+## Related
+
+- [Rules reference](../reference/rules)
+- [Configure rules](./configure-rules)

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

@@ -0,0 +1,12 @@
+{
+  "label": "How-to guides",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/developer-tools/eventcatalog-linter/how-to",
+    "title": "Linter how-to guides",
+    "description": "Task-focused guides for configuring rules, running the linter in CI, and fixing what it reports."
+  }
+}