@eventcatalog/core 4.10.12 → 4.10.14

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

@@ -0,0 +1,109 @@
+---
+sidebar_position: 1
+sidebar_label: CLI
+title: Linter CLI reference
+description: Command, options, exit codes, output format and environment behaviour of eventcatalog-linter.
+---
+
+## Usage
+
+```
+eventcatalog-linter [options] [directory]
+```
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `directory` | The catalog to lint — the folder containing `eventcatalog.config.js` | `.` |
+
+Run it with `npx @eventcatalog/linter`, or install `@eventcatalog/linter` and use the `eventcatalog-linter` binary.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Show verbose output |
+| `-q, --quiet` | Report errors only. Warnings are dropped from the output and from the counts |
+| `--fail-on-warning` | Exit with code 1 when any warning is reported. Equivalent to `--max-warnings 0` |
+| `--max-warnings <number>` | Exit with code 1 when more than `<number>` warnings are reported. Must be a non-negative integer |
+| `--no-color` | Disable coloured output |
+| `--init` | Write a commented `.eventcatalogrc.js` to the catalog directory and exit without linting. See [configuration](./configuration#scaffold-a-configuration-file) |
+| `--force` | With `--init`, overwrite an existing `.eventcatalogrc.js` |
+| `-V, --version` | Print the linter version |
+| `-h, --help` | Print help |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No errors. Warnings may have been reported, provided they don't exceed `--max-warnings` |
+| `1` | At least one error was reported, warnings exceeded `--max-warnings` / `--fail-on-warning` was set, an option was invalid, or the linter itself failed |
+
+`--init` exits `0` after writing the file and `1` if the file already exists (without `--force`).
+
+## Output
+
+Findings are grouped by file and sorted by position:
+
+```
+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
+
+✖ 3 problems (2 errors, 1 warning) in 1 file
+  178 files checked, 3 files ignored
+```
+
+| Part | Meaning |
+|------|---------|
+| `6:1` | 1-based line and column of the finding. Keys are reported at the key; references at the value; missing fields at the nearest parent (line 2 for a missing top-level field); body-content findings at the first line after the frontmatter; YAML parse errors at the failing token |
+| `✖ error` / `⚠ warning` | Severity after applying your configuration |
+| `[owner]` | The frontmatter field path, including array indexes (`sends[0].to[1]`) |
+| `(schema/unknown-field)` | The rule name. Parse failures use `(@eventcatalog/parse-error)` |
+| `in 1 file` | Number of files with at least one finding |
+| `178 files checked` | Number of files scanned and validated, after `ignorePatterns` |
+| `3 files ignored` | Number of recognised files skipped by `ignorePatterns` (omitted when zero) |
+
+When nothing is found:
+
+```
+✔ No problems found!
+  178 files checked
+```
+
+When the directory contains no recognisable catalog files, the linter prints `⚠ No EventCatalog files found` and exits `0`.
+
+## Progress output and terminals
+
+A progress spinner is written to **stderr** while the linter runs. It is shown only when stderr is an interactive terminal, the `CI` environment variable is not set, and `TERM` is not `dumb`. In pipelines and when piping output, nothing is written to stderr, so logs contain only findings.
+
+Colour follows [chalk](https://github.com/chalk/chalk) conventions: `--no-color`, `NO_COLOR=1` or `FORCE_COLOR=0` disable it; `FORCE_COLOR=1` enables it in non-TTY output.
+
+## Files the linter reads
+
+| File | Purpose |
+|------|---------|
+| `.eventcatalogrc.js` | Rule configuration. Optional; see [configuration](./configuration) |
+| `eventcatalog.config.js` | Read for `dependencies` so references to external resources resolve. Optional |
+| Resource `index.md` / `index.mdx` files | See [supported resources](./supported-resources) |
+| Files referenced from frontmatter | `schemaPath`, `schemas[]`, `specifications`, contracts and `public/` icons are checked for existence by [`refs/file-exists`](./rules#refsfile-exists) |
+
+The linter never modifies your catalog.
+
+## Programmatic use
+
+The package exports the pieces the CLI is built from — `scanCatalogFiles`, `parseAllFiles`, `validateCatalog`, `validateUnrecognisedFiles`, `attachLocations`, `loadConfig`, `applyRuleSeverity`, `reportErrors`, the rule registry (`RULES`) and version helpers — for use from your own scripts:
+
+```ts
+import { scanCatalogFiles, parseAllFiles, validateCatalog, loadConfig } from '@eventcatalog/linter';
+
+const rootDir = process.cwd();
+const config = loadConfig(rootDir);
+const files = await scanCatalogFiles(rootDir);
+const { parsed } = await parseAllFiles(files);
+const findings = validateCatalog(parsed, undefined, config);
+```
+
+The public API is not yet frozen; expect it to be consolidated into a single `lint()` entry point in a future release.

package/dist/docs/development/developer-tools/eventcatalog-linter/reference/02-configuration.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 2
+sidebar_label: Configuration
+title: Linter configuration reference
+description: The shape of .eventcatalogrc.js — rules, options, ignore patterns, overrides — and how it merges with the defaults.
+---
+
+The linter looks for `.eventcatalogrc.js` in the directory it lints. The file is optional; without it every rule runs at its default severity.
+
+## Scaffold a configuration file
+
+```bash
+npx @eventcatalog/linter --init          # writes .eventcatalogrc.js
+npx @eventcatalog/linter --init --force  # overwrites an existing one
+```
+
+The generated file lists every rule grouped by category, with a description, its default severity and an example of its options. It uses `export default` when the catalog's `package.json` has `"type": "module"` and `module.exports` otherwise.
+
+## Shape
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    '<rule-name>': '<severity>',
+    '<rule-name>': ['<severity>', { /* options */ }],
+  },
+  ignorePatterns: ['<glob>', '<glob>'],
+  overrides: [
+    {
+      files: ['<glob>', '<glob>'],
+      rules: {
+        '<rule-name>': '<severity>',
+        '<rule-name>': ['<severity>', { /* options */ }],
+      },
+    },
+  ],
+};
+```
+
+Every top-level key is optional.
+
+### `rules`
+
+An object keyed by rule name. Rule names are listed in the [rules reference](./rules).
+
+| Value | Effect |
+|-------|--------|
+| `'error'` | Report and fail the run |
+| `'warn'` | Report; fail only with `--fail-on-warning` / `--max-warnings` |
+| `'off'` | Don't check |
+| `[severity, options]` | As above, with rule-specific options. See each rule for its options |
+
+Unknown rule names are ignored silently.
+
+### `ignorePatterns`
+
+Glob patterns, matched against each file's path relative to the catalog root (forward slashes). Matching files are not validated, not counted, and not reported by `structure/unrecognised-file`.
+
+`dependencies/**` is always ignored in addition to what you list.
+
+Supported syntax is deliberately simple: `*` matches within a path segment and `**` matches across segments. A pattern beginning with `**/` needs at least one leading folder to match, so prefer `drafts/**` to `**/drafts/**` for a top-level folder.
+
+### `overrides`
+
+An ordered list. Each entry has `files` (glob patterns, same syntax as `ignorePatterns`) and `rules` (same shape as the top-level `rules`). For a given file, the top-level rules are applied first, then every override whose `files` matches, in order — later entries win.
+
+## Merging with the defaults
+
+At load time the linter merges your file over the built-in defaults:
+
+- `rules` — your entries override the default severity for that rule; rules you don't mention keep their default.
+- `ignorePatterns` — your patterns are appended to the default `['dependencies/**']`.
+- `overrides` — used as given (the default is an empty list).
+
+If the file exists but can't be loaded (syntax error, wrong module format), the linter prints a warning and continues with the defaults.
+
+## Module format
+
+`.eventcatalogrc.js` is loaded with Node's `require`. Use `module.exports` in a CommonJS project. In a project with `"type": "module"`, use `export default`; this is supported on Node.js 20.19 / 22.12 and later, where `require` can load ES modules. `--init` picks the right form automatically.
+
+## `eventcatalog.config.js`
+
+The linter also reads your catalog's `eventcatalog.config.js`, but only for `dependencies`, so that references to resources documented in other catalogs resolve. See [Reference external catalogs](../how-to/reference-external-catalogs). Nothing else in that file affects linting.
+
+## Full example
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    // Findings that mean EventCatalog will fail or silently drop something
+    'schema/unknown-field': ['error', { allow: ['legacy*'] }],
+    'refs/resource-exists': 'error',
+    'refs/file-exists': ['error', { publicDir: 'static' }],
+    'structure/unrecognised-file': 'error',
+
+    // Documentation quality
+    'best-practices/description-required': 'warn',
+    'best-practices/schema-required': 'warn',
+    'refs/orphan-messages': 'warn',
+  },
+
+  ignorePatterns: ['drafts/**'],
+
+  overrides: [
+    {
+      files: ['domains/Legacy/**'],
+      rules: {
+        'best-practices/owner-required': 'warn',
+        'best-practices/summary-required': 'off',
+      },
+    },
+    {
+      files: ['**/containers/**'],
+      rules: {
+        'best-practices/description-required': 'off',
+      },
+    },
+  ],
+};
+```

package/dist/docs/development/developer-tools/eventcatalog-linter/reference/03-rules.md

@@ -0,0 +1,287 @@
+---
+sidebar_position: 3
+sidebar_label: Rules
+title: Linter rules reference
+description: Every rule the EventCatalog Linter can report — what it checks, its default severity, its options, an example message and how to fix it.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Rules are grouped into five categories. Each rule can be set to `'error'`, `'warn'` or `'off'` in [`.eventcatalogrc.js`](./configuration); rules marked **options** also accept `[severity, { ... }]`.
+
+| Rule | Default | Options |
+|------|---------|---------|
+| [`schema/required-fields`](#schemarequired-fields) | error | |
+| [`schema/valid-type`](#schemavalid-type) | error | |
+| [`schema/valid-semver`](#schemavalid-semver) | error | |
+| [`schema/valid-email`](#schemavalid-email) | error | |
+| [`schema/validation-error`](#schemavalidation-error) | error | |
+| [`schema/unknown-field`](#schemaunknown-field) | error | `allow`, `suggestions` |
+| [`schema/unknown-nested-field`](#schemaunknown-nested-field) | warn | `allow`, `suggestions` |
+| [`refs/owner-exists`](#refsowner-exists) | error | |
+| [`refs/resource-exists`](#refsresource-exists) | error | |
+| [`refs/valid-version-range`](#refsvalid-version-range) | error | |
+| [`refs/channel-exists`](#refschannel-exists) | error | |
+| [`refs/container-exists`](#refscontainer-exists) | error | |
+| [`refs/file-exists`](#refsfile-exists) | error | `icons`, `publicDir` |
+| [`refs/orphan-messages`](#refsorphan-messages) | warn | |
+| [`best-practices/summary-required`](#best-practicessummary-required) | error | |
+| [`best-practices/owner-required`](#best-practicesowner-required) | error | |
+| [`best-practices/description-required`](#best-practicesdescription-required) | warn | |
+| [`best-practices/schema-required`](#best-practicesschema-required) | warn | |
+| [`versions/no-deprecated-references`](#versionsno-deprecated-references) | warn | |
+| [`structure/duplicate-resource-ids`](#structureduplicate-resource-ids) | error | |
+| [`structure/unrecognised-file`](#structureunrecognised-file) | warn | |
+
+YAML that cannot be parsed at all is reported as `(@eventcatalog/parse-error)`. It is always an error and cannot be configured.
+
+## Schema validation
+
+These rules validate frontmatter against the same schemas EventCatalog uses.
+
+### `schema/required-fields`
+
+A required field is missing from the frontmatter. Which fields are required depends on the resource type; `id`, `name` and `version` are required almost everywhere.
+
+```
+2:1 ✖ error name: Required [name] (schema/required-fields)
+```
+
+**Fix:** add the field.
+
+### `schema/valid-type`
+
+A field has the wrong type — a string where a list is expected, a missing required field reported as `undefined`, and so on.
+
+```
+2:1 ✖ error version: Expected string, but received undefined [version] (schema/valid-type)
+7:9 ✖ error owners: Expected array, but received string [owners] (schema/valid-type)
+```
+
+**Fix:** correct the value's shape. Lists in YAML are written with `- ` items or `[a, b]`.
+
+### `schema/valid-semver`
+
+A `version` (or a version inside a reference) isn't a format EventCatalog understands.
+
+```
+4:10 ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+```
+
+**Fix:** use semver (`1.2.3`, `1.0.0-beta`), a number-like version (`1`, `1.2`, `v1`, `V2`), `latest`, or a range (`^1.0.0`, `1.x`). See the [versions reference](./versions).
+
+### `schema/valid-email`
+
+An `email` field on a user or team isn't a valid email address.
+
+**Fix:** correct the address.
+
+### `schema/validation-error`
+
+A schema problem that doesn't fit the categories above. The message carries the underlying detail.
+
+### `schema/unknown-field`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+A top-level frontmatter key isn't part of the resource's schema. EventCatalog rejects unknown top-level keys at build time unless they start with `x-`, so this rule catches typos and stray custom fields before the build does. The message suggests the closest known key, or tells you when the key belongs to a different resource type.
+
+```
+6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
+8:1 ✖ error Unknown property "costCenter". Custom properties must start with "x-". [costCenter] (schema/unknown-field)
+5:1 ✖ error Unknown property "sends". "sends" is valid on service, agent, domain resources, but not on event resources. [sends] (schema/unknown-field)
+```
+
+**Options**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `allow` | `string[]` | `[]` | Keys, or `prefix*` patterns, to accept. Matched against the key name and the full path |
+| `suggestions` | `boolean` | `true` | Include "Did you mean" and other-resource-type hints |
+
+```js
+'schema/unknown-field': ['error', { allow: ['costCenter', 'legacy*'], suggestions: true }]
+```
+
+Keys starting with `x-` are always allowed, as are the `catalog`, `versions` and `latestVersion` fields the SDK writes into generated content.
+
+**Fix:** rename the key, or prefix it with `x-`. See [Allow custom frontmatter](../how-to/use-custom-frontmatter).
+
+### `schema/unknown-nested-field`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+The same check for keys inside nested objects and arrays (`sends[0].too`, `detailsPanel.ownerz`). EventCatalog silently ignores these rather than failing, which is why the default is `warn` — but a typo here usually means a relationship or setting is being dropped. Options are the same as `schema/unknown-field`, and an `allow` list set on either rule applies to both.
+
+```
+12:9 ⚠ warning Unknown property "sends[0].too". Did you mean "to"? [sends[0].too] (schema/unknown-nested-field)
+```
+
+Arbitrary keys are permitted where the schema allows them — flow step `custom.properties`, channel `parameters`, and any `producers`/`consumers` object.
+
+## Reference validation
+
+These rules check that everything your frontmatter points at actually exists. References can be plain ids (`- order-service`) or objects (`- id: order-service`, optionally with `version`). Version matching follows the [versions reference](./versions).
+
+### `refs/owner-exists`
+
+An entry in `owners` (or an ADR's `decisionMakers`) doesn't match any user or team.
+
+```
+6:5 ✖ error Referenced user/team "platfrom-team" does not exist. Did you mean "platform-team"? [owners[0]] (refs/owner-exists)
+```
+
+**Fix:** correct the id, or add the user (`users/<id>.mdx`) or team (`teams/<id>.mdx`).
+
+### `refs/resource-exists`
+
+A referenced resource id doesn't exist among the resource types the field accepts — `sends`/`receives` (events, commands, queries), `services`, `domains`, `entities`, `flows`, flow steps, ADR `appliesTo`, data product `inputs`/`outputs`, and so on. The message adds a "did you mean" suggestion for near-miss ids, or points out when the id exists as a different resource type.
+
+```
+9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
+9:5 ✖ error Referenced flow "PlaceOrder" does not exist. "PlaceOrder" exists as a command, not a flow. [appliesTo[0]] (refs/resource-exists)
+```
+
+This rule fires whether or not the reference has a version — if the id itself is unknown, the version is irrelevant.
+
+**Fix:** correct the id, create the resource, or declare it as an external [dependency](../how-to/reference-external-catalogs).
+
+### `refs/valid-version-range`
+
+The referenced resource exists, but no version of it satisfies the reference. The message lists the versions that do exist, newest first. It also fires when the version reference isn't a version, range or `latest` at all.
+
+```
+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)
+9:14 ✖ error Referenced event "OrderCreated" has an invalid version reference "two". Use a version (1.0.0, v1), a range (^1.0.0, 1.x) or "latest". Available versions: 1.0.0 [sends[0]] (refs/valid-version-range)
+```
+
+**Fix:** reference an existing version or a range that matches one, or add the version under `versioned/`.
+
+### `refs/channel-exists`
+
+A channel referenced from `sends[].to`, `receives[].from`, a message's `channels`, or a channel's `routes`/`channels` doesn't exist (or doesn't exist at that version).
+
+```
+11:9 ✖ error Referenced channel "orders-topic" does not exist. Did you mean "orders"? [sends[0].to[0]] (refs/channel-exists)
+```
+
+### `refs/container-exists`
+
+A container referenced from `writesTo`, `readsFrom`, a system's `containers`, or a container-typed flow step doesn't exist. `dataStore` is accepted as a legacy alias for `container`.
+
+```
+13:5 ✖ error Referenced container "orders-db" does not have a version matching "9.0.0". Available versions: 1.0.0 [writesTo[0]] (refs/container-exists)
+```
+
+### `refs/file-exists`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+A file referenced from frontmatter doesn't exist. The linter resolves each path the way EventCatalog does:
+
+| Field | Resolved against |
+|-------|------------------|
+| `schemaPath` | the resource's own folder |
+| `schemas[].file`, `schemas[].path` | the resource's own folder |
+| `schemas[].ref` | `file://<relative>` against the resource folder; `file:///<absolute>` as given. Other refs (schema registries) are skipped |
+| `specifications.openapiPath` / `asyncapiPath` / `graphqlPath`, `specifications[].path` | the resource's own folder; `http(s)://` values are skipped |
+| data product `outputs[].contract.path` | the resource's own folder |
+| `styles.icon` starting with `/` | the catalog's `public/` folder; icon names and URLs are skipped |
+
+Because paths resolve against the resource's own folder, a versioned copy under `versioned/1.0.0/` must have its own schema file next to it.
+
+```
+7:13 ✖ error Referenced schema file "schema.json" does not exist (looked for "events/OrderCreated/schema.json") [schemaPath] (refs/file-exists)
+15:9 ✖ error Referenced icon "/icons/go.svg" does not exist (looked for "public/icons/go.svg") [styles.icon] (refs/file-exists)
+```
+
+**Options**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `icons` | `boolean` | `true` | Check `styles.icon` paths |
+| `publicDir` | `string` | `'public'` | Folder, relative to the catalog root, that `/`-prefixed icon paths are served from |
+
+```js
+'refs/file-exists': ['error', { icons: false, publicDir: 'static' }]
+```
+
+### `refs/orphan-messages`
+
+An event, command or query that nothing produces or consumes: no service, agent or domain lists it in `sends`/`receives`, and the message itself has no `producers`/`consumers`. Messages declared as external dependencies are never orphans.
+
+```
+2:5 ⚠ warning event "OrderCreated" has no producer and no consumer [id] (refs/orphan-messages)
+```
+
+**Fix:** connect the message to a service, or turn the rule off for intentionally standalone messages.
+
+## Best practices
+
+Documentation-quality checks. They don't affect whether EventCatalog builds, so tune them to your team's standards.
+
+### `best-practices/summary-required`
+
+The resource has no `summary`, or it's blank. Users are exempt (the user schema has no summary field).
+
+```
+2:1 ✖ error Summary is required for better documentation [summary] (best-practices/summary-required)
+```
+
+### `best-practices/owner-required`
+
+The resource has no `owners`, or the list is empty. Users and teams are exempt.
+
+```
+2:1 ✖ error At least one owner is required [owners] (best-practices/owner-required)
+```
+
+### `best-practices/description-required`
+
+The file has no markdown body after the frontmatter.
+
+```
+14:1 ⚠ warning Resource should have a markdown description (body content) beyond just frontmatter [description] (best-practices/description-required)
+```
+
+### `best-practices/schema-required`
+
+An event, command or query has no `schemaPath`.
+
+```
+2:1 ⚠ warning event should have a schemaPath defined for consumers to understand the contract [schemaPath] (best-practices/schema-required)
+```
+
+## Versioning
+
+### `versions/no-deprecated-references`
+
+A reference points at a resource marked `deprecated`. A reference without a version (or `latest`) is flagged if any version of the target is deprecated; a versioned reference is flagged only if that version is. Owner and team-member references are not checked.
+
+```
+9:5 ⚠ warning Referenced event "OrderCreated" (version: 1.0.0) is deprecated [sends[0]] (versions/no-deprecated-references)
+```
+
+## Catalog structure
+
+### `structure/duplicate-resource-ids`
+
+Two files declare the same resource type, `id` and `version`.
+
+```
+2:5 ✖ error Duplicate event "OrderCreated" (version: 1.0.0) — also defined in domains/Orders/events/OrderCreated/index.mdx [id] (structure/duplicate-resource-ids)
+```
+
+### `structure/unrecognised-file`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+A `.md`/`.mdx` file lives under a resource folder but matches none of the locations EventCatalog loads resources from, so it will be silently ignored. The message suggests where the file probably belongs. Markdown that EventCatalog loads through other means — `docs/` folders, `pages/`, `changelog.md`, `ubiquitous-language.md` — and build artifacts are not reported. Files matched by `ignorePatterns` are skipped.
+
+```
+1:1 ⚠ warning File "events/OrderCreated.mdx" is not recognised as an EventCatalog resource and will be ignored. Did you mean "events/OrderCreated/index.mdx"? (structure/unrecognised-file)
+1:1 ⚠ warning File "event/OrderCreated/index.mdx" is not recognised … Did you mean "events/OrderCreated/index.mdx"? (structure/unrecognised-file)
+1:1 ⚠ warning File "users/john/index.mdx" is not recognised … users are flat files. Did you mean "users/john.mdx"? (structure/unrecognised-file)
+```
+
+Recognised locations are listed in [Supported resources](./supported-resources). Because a misplaced file means the catalog is missing content, consider promoting this rule to `'error'`.

package/dist/docs/development/developer-tools/eventcatalog-linter/reference/04-versions.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 4
+sidebar_label: Versions
+title: Version formats and matching
+description: The version formats the linter accepts on resources and in references, and how a reference is matched against the versions that exist.
+---
+
+The linter accepts exactly the version formats EventCatalog accepts, and matches references the same way EventCatalog does when it builds pages and visualisations.
+
+## Resource versions
+
+The `version` field on a resource (`version: 1.0.0`) may be:
+
+| Format | Examples | Notes |
+|--------|----------|-------|
+| Semantic version | `1.0.0`, `2.1.3-beta`, `1.0.0+build.5` | Compared as semver |
+| Number-like | `1`, `1.2`, `v1`, `V2.1` | Coerced to semver for comparison (`v1` ≡ `1.0.0`, `1.2` ≡ `1.2.0`) |
+| `latest` | `latest` | Accepted, but a resource without a comparable version can't satisfy range references |
+
+Values that are none of these — `one`, `1.0.0.0`, `version-1` — are reported by [`schema/valid-semver`](./rules#schemavalid-semver).
+
+:::note
+YAML parses `version: 1` as a number, and EventCatalog's schema requires a string. Quote number-like versions: `version: "1"`.
+:::
+
+## Version references
+
+Wherever frontmatter points at another resource, a `version` may be given:
+
+```yaml
+sends:
+  - id: OrderCreated            # no version → latest
+  - id: OrderCreated
+    version: latest             # explicit latest
+  - id: OrderCreated
+    version: 2.1.0              # exact
+  - id: OrderCreated
+    version: v2                 # number-like, same as 2.0.0
+  - id: OrderCreated
+    version: ^2.0.0             # semver range
+  - id: OrderCreated
+    version: 2.x                # x-range
+```
+
+| Reference | Matches |
+|-----------|---------|
+| _(omitted)_ or `latest` | Any version of the resource — the newest is used |
+| Exact (`2.1.0`, `V2`) | A version that is the same after coercion (`V2` matches `2`, `v2.0`, `2.0.0`) |
+| Semver range (`^2.0.0`, `~2.1.0`, `>=1.5`, `1.0.0 - 2.0.0`) | Any version satisfying the range. `V` is normalised to `v` first |
+| X-range (`2.x`, `0.0.x`) | Any version with that prefix |
+
+A reference value that is none of these is reported by [`refs/valid-version-range`](./rules#refsvalid-version-range) as invalid.
+
+## How matching is decided
+
+For a reference with an id and version:
+
+1. Is there any resource of an accepted type with that id? If not → [`refs/resource-exists`](./rules#refsresource-exists), regardless of the version.
+2. Is the version omitted or `latest`? → match.
+3. Does any existing version equal the reference exactly, or after coercion? → match.
+4. Does any existing version satisfy the reference as a semver range or x-range? → match.
+5. Otherwise → [`refs/valid-version-range`](./rules#refsvalid-version-range), listing the existing versions newest first.
+
+A resource with no `version` in its frontmatter is indexed as `latest`. It matches references without a version, but not range references (`^1.0.0`), because `latest` has no numeric value to compare.
+
+## External dependencies
+
+Resources declared in `eventcatalog.config.js` `dependencies` take part in matching too. A dependency without a `version` matches any reference to its id; with a `version`, the rules above apply.
+
+## Ordering
+
+When the linter lists "available versions" it sorts newest first using semver comparison, so `V3` sorts above `2` above `v1`. If any version can't be compared numerically, the list falls back to reverse alphabetical order — the same rule EventCatalog uses to pick the latest version of a resource.
+
+## Related
+
+- [Versioning resources](/docs/development/guides/versioning-resources)
+- [Reference external catalogs](../how-to/reference-external-catalogs)

package/dist/docs/development/developer-tools/eventcatalog-linter/reference/05-supported-resources.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 5
+sidebar_label: Supported resources
+title: Supported resources and file locations
+description: The resource types the linter validates and the folders and file names it scans to find them.
+---
+
+The linter validates every resource type EventCatalog supports. It finds resources by scanning the same file locations EventCatalog loads from; anything else under a resource folder is reported by [`structure/unrecognised-file`](./rules#structureunrecognised-file).
+
+## Resource types and locations
+
+Paths are relative to the catalog root. `<id>` is the resource's folder name and `<version>` a folder under `versioned/`. Both `index.md` and `index.mdx` are accepted.
+
+| Resource type | Locations |
+|---------------|-----------|
+| Domain | `domains/<id>/index.mdx`, `domains/<id>/subdomains/<id>/index.mdx`, plus `versioned/<version>/index.mdx` under each |
+| System | `systems/**/index.mdx` at any depth, including inside domains. Nested resource folders (`services/`, `containers/`, …) are loaded as their own types |
+| Service | `services/<id>/index.mdx`, and inside a domain, subdomain or system: `domains/<d>/services/<id>/`, `domains/<d>/subdomains/<s>/services/<id>/`, `**/systems/**/services/<id>/` |
+| Event | `**/events/<id>/index.mdx` |
+| Command | `**/commands/<id>/index.mdx` |
+| Query | `**/queries/<id>/index.mdx` |
+| Channel | `**/channels/**/index.mdx` (channels may be nested, e.g. `channels/public/orders/`) |
+| Flow | `**/flows/**/index.mdx` |
+| Entity | `**/entities/<id>/index.mdx` |
+| Agent | `**/agents/<id>/index.mdx` |
+| Container | `**/containers/**/index.mdx` |
+| Data product | `**/data-products/<id>/index.mdx` |
+| Diagram | `**/diagrams/**/index.mdx` |
+| ADR | `**/adrs/<id>/index.mdx` |
+| User | `users/<id>.mdx` — a flat file, not a folder |
+| Team | `teams/<id>.mdx` — a flat file, not a folder |
+
+Every folder-based type also accepts `versioned/<version>/index.mdx` beneath the resource folder for historic versions.
+
+## Federated content
+
+Resources materialised by [Federation](/docs/federation/overview) under `federated/<catalog>/…` are scanned with the same patterns, so owners, services and messages from other catalogs resolve.
+
+## Resource ids
+
+The `id` in the frontmatter is what references resolve against. The folder or file name is used only as a fallback when `id` is missing, so `services/UserService/index.mdx` with `id: user-service` is referenced as `user-service`.
+
+## Files that are not resources
+
+These markdown files are loaded by EventCatalog through other collections and are deliberately not treated as resources or reported as unrecognised:
+
+| Location | What it is |
+|----------|------------|
+| `**/docs/**/*.md(x)` | Resource documentation pages |
+| `docs/**/*.md(x)` | Catalog-level documentation |
+| `**/pages/*.md(x)` | Custom pages |
+| `**/changelog.md(x)` | Resource changelogs |
+| `domains/**/ubiquitous-language.md(x)` | Ubiquitous language dictionaries |
+
+Build artifacts (`dist/`, `node_modules/`, `.astro/`) and the `dependencies/` folder EventCatalog generates are skipped.
+
+## What is validated per resource
+
+All resources are checked for frontmatter schema conformance, unknown keys, owners, summary, body content, duplicate ids and file references. Type-specific reference checks:
+
+| Resource | References checked |
+|----------|--------------------|
+| Domain | `services`, `agents`, `domains` (subdomains), `systems`, `entities`, `data-products`/`dataProducts`, `flows`, `sends`, `receives` (incl. channels in `to`/`from`) |
+| System | `services`, `flows`, `entities`, `containers`, `relationships` |
+| Service, Agent | `sends`, `receives` (incl. channels), `writesTo`, `readsFrom`, `flows`, `entities` (services only) |
+| Event, Command, Query | `producers`, `consumers`, `channels`, `messageChannels`; orphan detection; `schemaPath` / `schemas[]` files |
+| Channel | `channels`, `routes`, `messages` |
+| Flow | each step's `message`, `service`, `agent`, `flow`, `container`, `dataProduct` |
+| Entity | `properties[].references`, `services`, `domains` |
+| Container | `services`, `servicesThatWriteToContainer`, `servicesThatReadFromContainer`, `dataProductsThatWriteToContainer`, `dataProductsThatReadFromContainer` |
+| Data product | `inputs`, `outputs` (any linkable type), `outputs[].contract.path` file |
+| ADR | `decisionMakers`, typed `appliesTo`, `supersedes`, `supersededBy`, `amends`, `amendedBy`, `related` |
+| User | `associatedTeams`, `owned*` lists |
+| Team | `members`, `owned*` lists |
+| All | `owners`, `diagrams`, `resourceGroups[].items` |