> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# xspec coverage: Measure Requirement Coverage

> Reference for xspec coverage: run coverage profiles, view covered and uncovered nodes with shortest covering paths, and gate CI on requirement coverage.

`coverage` measures how much of your requirement graph is covered by your code and tests. It runs one or all of your configured coverage profiles and reports counts alongside every node's status and the shortest path that covers it.

## Synopsis

```sh theme={null}
xspec coverage [<profile>] [--check]
```

Pass a profile name to run a single profile, or omit it to run all configured profiles. Add `--check` to make the command fail when any required node is uncovered — useful as a CI gate.

## Flags

<ParamField path="profile" type="string">
  Name of a specific coverage profile defined in your xspec config. When omitted, all configured profiles are evaluated.
</ParamField>

<ParamField path="--check" type="flag">
  Exit `1` if any node with `coverage: required` is uncovered. Without this flag the command always exits `0` and is purely informational.
</ParamField>

<ParamField path="--json" type="flag">
  Emit the full report as a single JSON document on stdout instead of the human-readable format.
</ParamField>

## Output

The report is organized into three sections for each profile: **covered**, **uncovered**, and **ignored**.

```
profile: default
─────────────────────────────────────────
covered: 3  uncovered: 1  ignored: 2

covered nodes:
  auth.login.valid
    via: test/auth.test.ts#testValidLogin
      → embeds specs/AUTH.mdx#auth.login.valid

  auth.login.invalid
    via: test/auth.test.ts#testInvalidLogin
      → embeds specs/AUTH.mdx#auth.login.invalid

  auth.lockout
    via: test/auth.test.ts#testLockout
      → embeds specs/AUTH.mdx#auth.lockout

uncovered nodes:
  auth.login  [required]

ignored nodes:
  auth  (reason: coverage: none)
  auth.login (subtree-only, ignored by profile filter)
```

## Node status meanings

| Status        | Meaning                                                                                                                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Covered**   | At least one incoming edge from an in-scope code or test node exists in the graph, satisfying the profile's matching rules. The report shows one shortest covering path; ties are broken byte-lexicographically. |
| **Uncovered** | No in-scope covering edge exists. Nodes marked `coverage: required` are highlighted.                                                                                                                             |
| **Ignored**   | Explicitly excluded from the profile by a filter, or carrying `coverage: none`. The report includes the reason for each ignored node.                                                                            |

## CI gating pattern

Use `--check` to fail your build when required coverage drops. Pair it with `xspec build` to ensure the graph is current before checking coverage.

```sh theme={null}
xspec build && xspec coverage --check
```

To gate on a specific profile only:

```sh theme={null}
xspec build && xspec coverage integration --check
```

## JSON output

With `--json`, the full report structure is emitted as a JSON document. Each profile produces an object with `covered`, `uncovered`, and `ignored` arrays. Each entry in `covered` includes the node identity and the full shortest covering path. Each entry in `uncovered` includes the identity and the required flag. Each entry in `ignored` includes the identity and the reason string.

```sh theme={null}
$ xspec coverage --json
```