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

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

profile · string

Name of a specific coverage profile defined in your xspec config. When omitted, all configured profiles are evaluated.

--check · flag

Exit 1 if any node with coverage: required is uncovered. Without this flag the command always exits 0 and is purely informational.

--json · flag

Emit the full report as a single JSON document on stdout instead of the human-readable format.

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.

xspec build && xspec coverage --check

To gate on a specific profile only:

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.

$ xspec coverage --json