@eventcatalog/core 5.2.1 → 5.4.1

package/dist/docs/development/guides/fitness-functions/03-global-and-resource-functions.md

@@ -0,0 +1,198 @@
+---
+sidebar_position: 3
+sidebar_label: Global and resource functions
+title: Global and resource fitness functions
+description: Put fitness functions at the root of your catalog for catalog-wide rules, or next to a domain, system, service or message so they're given that resource.
+---
+
+A fitness function can live in two places: the `fitness/` folder at the root of your catalog, or a `fitness/` folder inside a resource's folder. Where you put it decides which resource it's given when it runs. It doesn't limit what it can read: every function can query the whole catalog.
+
+## Global fitness functions
+
+Functions in the root `fitness/` folder are global. They aren't given a resource, so `resource` is `undefined`, and they check whatever they read from `catalog`.
+
+```
+fitness/
+└── event-ownership.fitness.ts
+```
+
+Use them for standards that apply to everything, like ownership or schema rules. A platform team typically owns this folder.
+
+## Resource fitness functions
+
+Functions in a `fitness/` folder inside a resource's folder are given that resource as `resource`. This lets the team that owns a domain, system or service keep its rules next to its documentation.
+
+```
+domains/
+└── Ordering/
+    ├── index.mdx
+    └── fitness/
+        └── domain-boundaries.fitness.ts   # resource is the Ordering domain
+```
+
+The resource includes its frontmatter, as the SDK returns it, plus a `type` field. Check `type` before using fields that only some resources have, and TypeScript narrows the resource for you:
+
+```ts title="domains/Ordering/fitness/domain-boundaries.fitness.ts"
+import { defineFitnessFunction } from '@eventcatalog/fitness';
+
+export default defineFitnessFunction({
+  id: 'ordering-domain-boundaries',
+  name: 'Ordering services only use Ordering data stores',
+  description: 'Services in the Ordering domain must not read from or write to data stores that belong to other domains.',
+
+  async run({ resource, catalog }) {
+    if (resource?.type !== 'domain') return [];
+
+    // The data stores and services that belong to the domain, through its systems
+    const ownedStores = new Set<string>();
+    const services = [...(resource.services ?? [])];
+    for (const pointer of resource.systems ?? []) {
+      const system = await catalog.getSystem(pointer.id, pointer.version);
+      system?.containers?.forEach((container) => ownedStores.add(container.id));
+      services.push(...(system?.services ?? []));
+    }
+
+    const violations = [];
+    for (const pointer of services) {
+      const service = await catalog.getService(pointer.id, pointer.version);
+      if (!service) continue;
+
+      for (const store of [...(service.readsFrom ?? []), ...(service.writesTo ?? [])]) {
+        if (ownedStores.has(store.id)) continue;
+        violations.push({
+          message: `${service.name} uses ${store.id}, which belongs to another domain`,
+          resources: [
+            { type: 'service', id: service.id, version: service.version },
+            { type: 'container', id: store.id },
+          ],
+          suggestion: 'Consume an event or call an API owned by the other domain instead',
+        });
+      }
+    }
+    return violations;
+  },
+});
+```
+
+The function starts from the domain it's given, then uses `catalog` to read the domain's [systems](/docs/development/guides/systems/introduction), their services, and the [data stores](/docs/development/guides/resources/data/introduction) those services [read from and write to](/docs/development/guides/resources/data/add-read-write-relationships). The resource sets where the rule starts, not how far it can look.
+
+A service function works the same way. This one warns when a service has too many dependencies:
+
+```ts title="services/OrderService/fitness/max-dependencies.fitness.ts"
+import { defineFitnessFunction } from '@eventcatalog/fitness';
+
+const MAX_DEPENDENCIES = 6;
+
+export default defineFitnessFunction({
+  id: 'order-service-max-dependencies',
+  name: 'Order Service stays loosely coupled',
+  severity: 'warning',
+
+  run({ resource }) {
+    if (resource?.type !== 'service') return [];
+
+    const dependencies = [...(resource.receives ?? []), ...(resource.readsFrom ?? []), ...(resource.writesTo ?? [])];
+    if (dependencies.length <= MAX_DEPENDENCIES) return [];
+
+    return [
+      {
+        message: `${resource.name} has ${dependencies.length} dependencies (the limit is ${MAX_DEPENDENCIES})`,
+        resources: [{ type: 'service', id: resource.id, version: resource.version }],
+        details: 'Counts the messages it receives and the data stores it reads from or writes to.',
+        suggestion: 'Split the service, or move work behind events another service handles',
+      },
+    ];
+  },
+});
+```
+
+`run` can be synchronous when it doesn't need to read the catalog.
+
+In the results, resource functions are labelled with the resource's id:
+
+```
+✗ ordering / Ordering services only use Ordering data stores  1 violation
+    • Order Service uses payment-database, which belongs to another domain
+      Resources: order-service (service), payment-database (container)
+      Suggestion: Consume an event or call an API owned by the other domain instead
+! order-service / Order Service stays loosely coupled         1 warning
+    • Order Service has 7 dependencies (the limit is 6)
+      Resources: order-service (service)
+      Counts the messages it receives and the data stores it reads from or writes to.
+      Suggestion: Split the service, or move work behind events another service handles
+```
+
+## Which resource a function is given
+
+EventCatalog works out the resource from the folder that contains `fitness/`. That folder must have an `index.mdx` or `index.md` with an `id`, and it must sit inside one of these folders:
+
+| Folder | Resource type |
+|---|---|
+| `domains/`, `subdomains/` | `domain` |
+| `systems/` | `system` |
+| `services/` | `service` |
+| `agents/` | `agent` |
+| `events/` | `event` |
+| `commands/` | `command` |
+| `queries/` | `query` |
+| `flows/` | `flow` |
+| `channels/` | `channel` |
+| `entities/` | `entity` |
+| `containers/` | `container` |
+| `data-products/` | `data-product` |
+| `adrs/` | `adr` |
+| `diagrams/` | `diagram` |
+
+Resources can be nested, as they can anywhere in EventCatalog. A function is given the resource whose folder holds its `fitness/` folder, not that resource's parents:
+
+```
+domains/Ordering/
+├── fitness/                               # the Ordering domain
+└── systems/order-management-system/
+    ├── fitness/                           # the order-management-system system
+    └── services/OrderService/
+        ├── fitness/                       # the OrderService service
+        └── events/OrderCreated/
+            └── fitness/                   # the OrderCreated event
+```
+
+Inside a `fitness/` folder you can organise files into subfolders. They're given the same resource:
+
+```
+domains/Ordering/fitness/
+├── boundaries/
+│   └── data-stores.fitness.ts             # still the Ordering domain
+└── helpers.ts
+```
+
+## Versions
+
+A resource function is given the version of the resource in its folder. In the resource's main folder, that's the version in its `index.mdx`, usually the latest. To check an older version, put the function in that version's folder:
+
+```
+services/OrderService/
+├── index.mdx                              # version 1.0.0
+├── fitness/
+│   └── max-dependencies.fitness.ts        # given OrderService 1.0.0
+└── versioned/
+    └── 0.0.1/
+        ├── index.mdx
+        └── fitness/
+            └── legacy.fitness.ts          # given OrderService 0.0.1
+```
+
+Each file runs once, against the version it sits alongside. A function in the main folder doesn't run against the versions under `versioned/`. See [versioning resources](/docs/development/guides/versioning-resources) for how versions are stored.
+
+## Rules for fitness files
+
+- Only files ending in `.fitness.ts` are run. Other files in a `fitness/` folder, like `helpers.ts`, are not, so you can use them for code your functions share and import it with a relative path.
+- A `*.fitness.ts` file outside a `fitness/` folder isn't run. EventCatalog lists it as a warning at the end of the results so you can move it. It doesn't fail the check.
+- `node_modules/`, `dist/` and folders that start with a `.` are ignored.
+- Fitness functions in `federated/` aren't run. If your catalog [federates](/docs/federation/overview) other catalogs, only your own catalog's functions run, never theirs.
+- If EventCatalog can't work out a function's resource, for example because the folder has no `index.mdx`, has no `id`, or isn't in one of the folders above, the function isn't run and is reported as an `Error`.
+- Ids must be unique across the catalog. If two files use the same `id`, the first one (in path order) runs and the others are reported as errors.
+
+## Related
+
+- [Create a fitness function](./02-create-fitness-function.md)
+- [API reference](./05-api-reference.md): the `resource` and `catalog` types

package/dist/docs/development/guides/fitness-functions/04-run-in-ci.md

@@ -0,0 +1,223 @@
+---
+sidebar_position: 4
+sidebar_label: Run in CI
+title: Run fitness functions locally and in CI
+description: The eventcatalog fitness check command, its options, output and exit codes, the report it writes, and how to run it in GitHub Actions or GitLab CI.
+---
+
+`eventcatalog fitness check` runs every fitness function in your catalog. Run it locally while you write rules, and in CI so every change to the catalog is checked.
+
+## The command
+
+```bash
+npx eventcatalog fitness check
+```
+
+The command is part of `@eventcatalog/core`, the same package that runs `eventcatalog dev` and `eventcatalog build`. Run it from the root of your catalog. It always checks the whole catalog. Catalogs created with `create-eventcatalog` also have an `npm run fitness` script that runs it.
+
+The [EventCatalog CLI](/docs/cli) has the same command. Use it to check a catalog without installing EventCatalog, or to point at a catalog in another folder with `--dir`:
+
+```bash
+npx @eventcatalog/cli --dir ./my-catalog fitness check
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `-o, --output <path>` | `.eventcatalog/fitness/results.json` | Where to write the report, relative to the catalog |
+| `--format <format>` | `text` | `text` prints the results for people to read. `json` prints the full report instead |
+
+If your catalog has a `.env` file, it's loaded before your functions run, so they can read settings from `process.env`.
+
+## What it does
+
+1. Finds every `*.fitness.ts` file in a `fitness/` folder, [at the root or in a resource's folder](./03-global-and-resource-functions.md).
+2. Runs them one at a time, in path order, so every run's results are in the same order.
+3. Prints the results, writes the report, and exits with a code that tells CI whether the check passed.
+
+## Reading the output
+
+```
+EventCatalog Fitness
+
+✗ ordering / Ordering services only use Ordering data stores  1 violation
+    • Order Service uses payment-database, which belongs to another domain
+      Resources: order-service (service), payment-database (container)
+      Suggestion: Consume an event or call an API owned by the other domain instead
+! order-service / Order Service stays loosely coupled         1 warning
+    • Order Service has 7 dependencies (the limit is 6)
+      Resources: order-service (service)
+      Counts the messages it receives and the data stores it reads from or writes to.
+      Suggestion: Split the service, or move work behind events another service handles
+✗ Critical services are documented                            Error
+    Cannot read properties of undefined (reading 'owners')
+    in fitness/critical-services.fitness.ts
+✗ Every event has an owner                                    1 violation
+    • Order Amended has no owners
+      Resources: order-amended (event)
+      Suggestion: Add a team or user to the owners field in the frontmatter
+! Every event has a schema                                    1 warning
+    • Order Amended has no schema
+      Resources: order-amended (event)
+
+5 fitness functions evaluated
+
+0 passed
+2 warnings
+2 failed
+1 error
+
+Report written to .eventcatalog/fitness/results.json
+```
+
+Each function gets one line. Functions [next to a resource](./03-global-and-resource-functions.md#resource-fitness-functions) are labelled with the resource's id first.
+
+| Symbol | Result | Meaning |
+|---|---|---|
+| `✓` | `Passed` | The function returned no violations |
+| `!` | `n warnings` | A `warning` function found violations |
+| `✗` | `n violations` | An `error` function found violations |
+| `✗` | `Error` | The function couldn't be run. Its error and file are shown under it |
+
+Under each function are its violations: the message, the resources it's about, any `details`, and the suggestion. A resource that doesn't match anything in the catalog is shown as `not found in the catalog`.
+
+Output is coloured when the command runs in a terminal. Set `NO_COLOR` to turn colour off.
+
+## Warnings and errors
+
+Each function has a `severity`:
+
+- **`error`** (the default): violations fail the check.
+- **`warning`**: violations are reported, but the check still passes.
+
+Use `warning` for a rule you're introducing to an existing catalog. Teams see the violations without their builds failing, and you can change it to `error` once they're fixed.
+
+## Exit codes
+
+| Code | When |
+|---|---|
+| `0` | Every function passed, or only `warning` functions found violations |
+| `1` | An `error` function found violations, or a function couldn't be run |
+| `2` | The check itself couldn't run, for example because the catalog folder doesn't exist |
+
+A catalog with no fitness functions exits with `0`.
+
+## When a function throws
+
+A function that can't be run is reported with the status `Error`, not as a violation. This happens when:
+
+- `run` throws an exception or returns a promise that rejects,
+- `run` returns something other than an array of violations, or a violation without a `message`,
+- the file has no default export, fails to load (a syntax error, for example), or the export isn't a valid fitness function,
+- another function already uses the same `id`,
+- EventCatalog can't find the resource the function sits alongside.
+
+The other functions still run. Any error fails the check with exit code `1`, so a broken rule can't pass unnoticed. The error message is printed in the terminal, and the message and stack trace are in the report.
+
+## The report
+
+Every run writes a JSON report, to `.eventcatalog/fitness/results.json` by default. It's written even when there are no fitness functions, so a missing file always means the check didn't run.
+
+The report has a summary, every function's result with its violations and errors, and any fitness files that weren't run.
+
+For a catalog with one failing function, it looks like this:
+
+```json title=".eventcatalog/fitness/results.json"
+{
+  "schemaVersion": 1,
+  "evaluatedAt": "2026-10-18T14:34:11.778Z",
+  "catalogRevision": "5b0bede",
+  "summary": { "total": 1, "passed": 0, "warnings": 0, "failed": 1, "errors": 0 },
+  "functions": [
+    {
+      "id": "event-ownership",
+      "name": "Every event has an owner",
+      "description": "Events without an owner have nobody to ask before they change.",
+      "severity": "error",
+      "status": "failed",
+      "source": "fitness/event-ownership.fitness.ts",
+      "scope": null,
+      "violations": [
+        {
+          "message": "Order Amended has no owners",
+          "resources": [{ "type": "event", "id": "order-amended", "version": "1.0.0", "resolved": true }],
+          "suggestion": "Add a team or user to the owners field in the frontmatter"
+        }
+      ]
+    }
+  ],
+  "diagnostics": []
+}
+```
+
+`catalogRevision` is the git commit the catalog was checked at, or `null` when it isn't in a git repository. See [the report reference](./05-api-reference.md#the-report) for every field.
+
+Write it somewhere else with `--output`:
+
+```bash
+npx eventcatalog fitness check --output reports/fitness.json
+```
+
+Or print it to standard output with `--format json` (it's still written to the file too):
+
+```bash
+npx eventcatalog fitness check --format json > fitness.json
+```
+
+The report is written again on every run, so add `.eventcatalog/fitness/` to your `.gitignore` unless you want to commit it. Catalogs created with `create-eventcatalog` already ignore it.
+
+## GitHub Actions
+
+```yaml title=".github/workflows/fitness.yml"
+name: Architecture fitness
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  fitness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx eventcatalog fitness check
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: fitness-report
+          path: .eventcatalog/fitness/results.json
+```
+
+`if: always()` keeps the report when the check fails, which is when you'll want to look at it.
+
+If the catalog lives in a subfolder of the repository, set the working directory for the step:
+
+```yaml
+      - run: npx eventcatalog fitness check
+        working-directory: ./catalog
+```
+
+Or use the EventCatalog CLI with `--dir`: `npx @eventcatalog/cli --dir ./catalog fitness check`.
+
+## GitLab CI
+
+```yaml title=".gitlab-ci.yml"
+fitness:
+  stage: test
+  image: node:20
+  script:
+    - npm ci
+    - npx eventcatalog fitness check
+  artifacts:
+    when: always
+    paths:
+      - .eventcatalog/fitness/results.json
+```
+
+## Related
+
+- [Create a fitness function](./02-create-fitness-function.md)
+- [API reference](./05-api-reference.md)

package/dist/docs/development/guides/fitness-functions/05-api-reference.md

@@ -0,0 +1,271 @@
+---
+sidebar_position: 5
+sidebar_label: API reference
+title: Fitness function API reference
+description: defineFitnessFunction, the run context, the resource and catalog it is given, the violation format, and the schema of the results report.
+---
+
+Everything on this page is exported from `@eventcatalog/fitness`. Import the types you need:
+
+```ts
+import { defineFitnessFunction } from '@eventcatalog/fitness';
+import type { FitnessContext, FitnessViolation } from '@eventcatalog/fitness';
+```
+
+## `defineFitnessFunction`
+
+```ts
+defineFitnessFunction<T extends FitnessFunction>(definition: T): T
+```
+
+Defines a fitness function. Make it the default export of a `*.fitness.ts` file in a [`fitness/` folder](./03-global-and-resource-functions.md):
+
+```ts
+export default defineFitnessFunction({
+  id: 'event-ownership',
+  name: 'Every event has an owner',
+  async run({ resource, catalog }) {
+    return [];
+  },
+});
+```
+
+It returns the definition unchanged, and throws if the definition is invalid (the runner reports that as an `Error` for the file).
+
+### `FitnessFunction`
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | Identifies the function. Must be unique across the catalog |
+| `name` | `string` | Yes | Shown in the results |
+| `description` | `string` | No | What the function checks. Included in the report |
+| `severity` | `'error' \| 'warning'` | No | `error` (the default) fails the check when violations are found. `warning` reports them without failing it |
+| `run` | `(context: FitnessContext) => FitnessViolation[] \| Promise<FitnessViolation[]>` | Yes | Checks the architecture and returns the violations it finds. An empty array means the check passed |
+
+```ts
+type FitnessFunction = {
+  id: string;
+  name: string;
+  description?: string;
+  severity?: 'error' | 'warning';
+  run(context: FitnessContext): Promise<FitnessViolation[]> | FitnessViolation[];
+};
+```
+
+## The run context
+
+`run` is given one argument:
+
+```ts
+type FitnessContext = {
+  resource?: CatalogResource;
+  catalog: ReadOnlyCatalog;
+};
+```
+
+### `resource`
+
+The resource the function sits alongside, as the SDK returns it, with a `type` field added. For `domains/Ordering/fitness/boundaries.fitness.ts` it's the Ordering domain. For functions in the root `fitness/` folder it's `undefined`.
+
+`CatalogResource` is a union of every resource type, so checking `type` narrows it:
+
+```ts
+async run({ resource }) {
+  if (resource?.type !== 'service') return [];
+  resource.receives; // resource is a Service here
+  return [];
+}
+```
+
+| `type` | SDK type |
+|---|---|
+| `'domain'` | `Domain` |
+| `'system'` | `System` |
+| `'service'` | `Service` |
+| `'agent'` | `Agent` |
+| `'event'` | `Event` |
+| `'command'` | `Command` |
+| `'query'` | `Query` |
+| `'flow'` | `Flow` |
+| `'channel'` | `Channel` |
+| `'entity'` | `Entity` |
+| `'container'` | `Container` |
+| `'data-product'` | `DataProduct` |
+| `'adr'` | `Adr` |
+| `'diagram'` | `Diagram` |
+
+The SDK types are exported from `@eventcatalog/sdk`. See [which resource a function is given](./03-global-and-resource-functions.md#which-resource-a-function-is-given) for how the folder maps to a resource.
+
+### `catalog`
+
+Read-only access to the whole catalog. Its methods are the [EventCatalog SDK](/docs/sdk) methods that read the catalog, with the same arguments and return values. Methods that write to the catalog aren't on it.
+
+```ts
+const events = await catalog.getEvents({ latestOnly: true });
+const service = await catalog.getService('order-service');
+const graph = await catalog.getGraph({ type: 'domain', id: 'ordering' }, { flat: true });
+```
+
+Every call returns a copy, so changing a resource you read doesn't change what the next call, or the next function, sees.
+
+A getter like `getService` returns `undefined` when the resource doesn't exist. Check for it before using the result.
+
+| Area | Methods |
+|---|---|
+| **Messages** | `getEvent`, `getEvents`, `eventHasVersion`, `getExamplesFromEvent`, `getCommand`, `getCommands`, `commandHasVersion`, `getExamplesFromCommand`, `getQuery`, `getQueries`, `queryHasVersion`, `getExamplesFromQuery`, `getMessageBySchemaPath`, `getProducersAndConsumersForMessage`, `getConsumersOfSchema`, `getProducersOfSchema`, `getSchemaForMessage` |
+| **Architecture** | `getDomain`, `getDomains`, `domainHasVersion`, `getUbiquitousLanguageFromDomain`, `getSystem`, `getSystems`, `systemHasVersion`, `getService`, `getServices`, `serviceHasVersion`, `getSpecificationFilesForService`, `getAgent`, `getAgents`, `agentHasVersion`, `getChannel`, `getChannels`, `channelHasVersion`, `getFlow`, `getFlows`, `flowHasVersion`, `getEntity`, `getEntities`, `entityHasVersion`, `getDataStore`, `getDataStores`, `dataStoreHasVersion`, `getDataProduct`, `getDataProducts`, `dataProductHasVersion`, `getDiagram`, `getDiagrams`, `diagramHasVersion`, `getAdr`, `getAdrs`, `adrHasVersion` |
+| **People and docs** | `getTeam`, `getTeams`, `getUser`, `getUsers`, `getOwnersForResource`, `getCustomDoc`, `getCustomDocs`, `getChangelog` |
+| **Relationships** | `getGraph`, `getResourcesByProperty`, `getResourcePath`, `getResourceFolderName`, `getEventCatalogConfigurationFile` |
+
+`getGraph` walks the relationships from a resource. See the [architecture graph](/docs/development/guides/architecture-graph) for what it returns.
+
+## Violations
+
+`run` returns an array of violations:
+
+```ts
+type FitnessViolation = {
+  message: string;
+  resources?: FitnessResourceReference[];
+  details?: string;
+  suggestion?: string;
+};
+```
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `message` | `string` | Yes | What's wrong. One line, shown as the violation |
+| `resources` | `FitnessResourceReference[]` | No | The resources the violation is about |
+| `details` | `string` | No | More explanation, shown under the resources |
+| `suggestion` | `string` | No | How to fix it |
+
+```ts
+return [
+  {
+    message: 'Order Service uses payment-database, which belongs to another domain',
+    resources: [
+      { type: 'service', id: 'order-service', version: '1.0.0' },
+      { type: 'container', id: 'payment-database' },
+    ],
+    suggestion: 'Consume an event or call an API owned by the other domain instead',
+  },
+];
+```
+
+### Resource references
+
+```ts
+type FitnessResourceReference = {
+  type: string;
+  id: string;
+  version?: string;
+};
+```
+
+EventCatalog looks up every reference in the catalog and records in the report whether it was found (`resolved`). Without a `version`, it resolves to the latest version and records that version, so the report says exactly which version was checked.
+
+`type` can be any of these:
+
+| `type` | Also accepted |
+|---|---|
+| `domain` | `subdomain` |
+| `system` | |
+| `service` | |
+| `agent` | |
+| `event` | |
+| `command` | |
+| `query` | |
+| `flow` | |
+| `channel` | |
+| `entity` | |
+| `container` | `dataStore` |
+| `data-product` | `dataProduct` |
+| `adr` | |
+| `diagram` | |
+| `team` | |
+| `user` | |
+
+Types are matched without regard to case. A reference with an unknown type, or to a resource that doesn't exist, is kept in the report with `resolved: false` and shown as `not found in the catalog`. It doesn't stop the function.
+
+## Errors
+
+A function is reported with the status `error`, and fails the check, when:
+
+- it throws, or the promise it returns rejects,
+- it returns something other than an array,
+- a violation isn't an object, or has no `message`, or `details`, `suggestion`, `resources` or a reference has the wrong type,
+- the file has no default export, fails to load, or the export isn't a valid definition,
+- its `id` is already used by another function,
+- the resource it sits alongside can't be found.
+
+The other functions still run. The report records the error's `message` and, for exceptions, its `stack`, with paths relative to the catalog.
+
+To report something you found as a problem in the architecture, return a violation. Throw only when the function itself can't do its job.
+
+## The report
+
+`eventcatalog fitness check` writes the results to `.eventcatalog/fitness/results.json` (change it with [`--output`](./04-run-in-ci.md#the-command)). These types are exported for tools that read it.
+
+```ts
+type FitnessReport = {
+  schemaVersion: 1;
+  evaluatedAt: string;               // ISO 8601
+  catalogRevision: string | null;    // short git commit, or null outside a git repository
+  summary: {
+    total: number;
+    passed: number;
+    warnings: number;
+    failed: number;
+    errors: number;
+  };
+  functions: FitnessFunctionResult[];
+  diagnostics: { source: string; message: string }[];
+};
+
+type FitnessFunctionResult = {
+  id: string;
+  name: string;
+  description?: string;
+  severity: 'error' | 'warning';
+  status: 'passed' | 'warning' | 'failed' | 'error' | 'not_run';
+  source: string;                    // path of the file, relative to the catalog
+  scope: { type: CatalogResourceType; id: string; version?: string } | null;
+  violations: {
+    message: string;
+    resources: { type: string; id: string; version?: string; resolved: boolean }[];
+    details?: string;
+    suggestion?: string;
+  }[];
+  error?: { message: string; stack?: string };
+};
+```
+
+| `status` | Meaning |
+|---|---|
+| `passed` | The function ran and found no violations |
+| `warning` | A `warning` function found violations |
+| `failed` | An `error` function found violations |
+| `error` | The function couldn't be run. See `error` |
+| `not_run` | The function has no result |
+
+`scope` is the resource the function sits alongside, or `null` for functions in the root `fitness/` folder. Its `version` is left out for resources that don't have one. `diagnostics` lists fitness files that weren't run because they aren't in a `fitness/` folder.
+
+## Running fitness functions from code
+
+`@eventcatalog/fitness` also exports what the command uses, for running checks from your own scripts:
+
+| Export | Description |
+|---|---|
+| `runFitnessCheck({ dir, output?, format?, color? })` | Does what `eventcatalog fitness check` does: runs the functions, writes the report, prints the results, and returns the exit code (`0`, `1` or `2`) |
+| `evaluateFitness({ dir })` | Runs the functions and returns the `FitnessReport`, without writing or printing anything |
+| `formatFitnessReport(report, { color? })` | The text the command prints for a report |
+| `writeFitnessReport(report, path)` | Writes a report as JSON |
+| `getFitnessExitCode(report)` | `1` when a function failed or couldn't be run, otherwise `0` |
+| `discoverFitnessFiles(dir)` | The fitness files in a catalog and the resource each one sits alongside |
+
+```ts
+import { evaluateFitness } from '@eventcatalog/fitness';
+
+const report = await evaluateFitness({ dir: './my-catalog' });
+console.log(`${report.summary.failed} failed`);
+```