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

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

--base · 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.

--json · flag

Emit the impact report as a single JSON document on stdout.

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

$ 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