> ## 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 impact: Track Changes Across the Graph

> Reference for xspec impact: compare your workspace against a git baseline to identify changed requirements and directly or transitively impacted code.

`impact` compares your current workspace against a previous git baseline to show you which requirements changed and which code units are directly or transitively affected. It is always informational — it exits `0` whether or not impacted nodes are found — so you can use it freely in scripts without worrying about false failures.

## Synopsis

```sh theme={null}
xspec impact --base <git-ref>
```

`--base` is required. Provide any valid git ref: a commit SHA, a branch name, a tag, or a relative ref like `HEAD~1`.

## Flags

<ParamField path="--base" type="git-ref" required>
  The git reference to use as the comparison baseline. xspec checks out the graph data at that ref and maps identities forward through the journal before diffing.
</ParamField>

<ParamField path="--json" type="flag">
  Emit the impact report as a single JSON document on stdout.
</ParamField>

## How it works

xspec reads the graph data recorded at the baseline ref and maps node identities forward through the journal (which records renames and moves). It then diffs the baseline graph against the current workspace graph and classifies every changed requirement into a change category.

## Change categories

| Category                 | Meaning                                                                        |
| ------------------------ | ------------------------------------------------------------------------------ |
| **Added**                | Node exists in the current workspace but not in the baseline                   |
| **Removed**              | Node existed at the baseline but is absent from the current workspace          |
| **Text changed**         | The node's own text content changed                                            |
| **Subtree changed**      | Text or structure changed within the node's descendants                        |
| **Metadata changed**     | Tags, coverage attribute, or structural position changed without a text change |
| **Dependencies changed** | The node's outgoing dependency edges changed                                   |

Each changed node includes attribution: the file, line range, and identity where the change originates.

## Impacted code

For every changed requirement, `impact` traces outgoing edges to find all code and test nodes that reference or embed the requirement, both directly and transitively.

| Kind           | Meaning                                                                              |
| -------------- | ------------------------------------------------------------------------------------ |
| **Direct**     | The code node has an edge to the changed requirement in a single hop                 |
| **Transitive** | The code node reaches the changed requirement through one or more intermediate nodes |

Each impacted code entry includes a witness path showing the shortest route from the code node to the changed requirement. Ties in path length are broken byte-lexicographically.

## Reading the human report

```
changed requirements: 2

  specs/AUTH.mdx#auth.login.valid  [text changed]
    direct impact:
      src/auth.ts#login
        via: src/auth.ts#login → references specs/AUTH.mdx#auth.login.valid
    transitive impact:
      test/auth.test.ts#testValidLogin
        via: test/auth.test.ts#testValidLogin → embeds src/auth.ts#login
             src/auth.ts#login → references specs/AUTH.mdx#auth.login.valid

  specs/AUTH.mdx#auth.lockout  [metadata changed]
    direct impact: none
    transitive impact: none
```

## JSON output shape

With `--json` the report contains a top-level `changes` array. Each entry has:

* `node` — the requirement identity
* `category` — the change category string
* `direct` — array of directly impacted code nodes, each with a `path` array
* `transitive` — array of transitively impacted code nodes, each with a `path` array

```sh theme={null}
$ xspec impact --base main --json
```

## Baseline error conditions

| Condition                           | Exit code | Explanation                                                    |
| ----------------------------------- | --------- | -------------------------------------------------------------- |
| `--base` not provided               | `2`       | The flag is required                                           |
| Ref does not exist or is unreadable | `2`       | xspec cannot check out graph data at that ref                  |
| Journal replay fails                | `1`       | The journal between baseline and HEAD is corrupt or incomplete |
| Sources fail validation at HEAD     | `1`       | The auto-refresh of graph data found errors                    |