Understanding the xspec Project Dependency Graph

xspec reads every .mdx file in your project and constructs a project-wide dependency graph that maps the structural and semantic relationships between your specification requirements and your codebase. This graph is the foundation for every analysis command xspec provides: coverage gaps, change impact, review scoping, and arbitrary graph queries all operate on the same underlying data structure stored at .xspec/graph.json.

Nodes

The graph contains three kinds of nodes:

Node type	What it represents	Identified by
Requirement section	A single `<S>` tag in an MDX spec file	`path#id` (e.g. `specs/AUTH.mdx#auth.login`)
File root	The document as a whole — an implicit parent for all sections in a file	File path alone (e.g. `specs/AUTH.mdx`)
Code location	A file, function, class, or other named unit in your source code	File path + optional unit name

Every spec file automatically contributes a root node even if it contains no <S> sections. Code locations are registered when TypeScript markers reference them.

Edge Kinds

Edges express how nodes relate to one another. xspec distinguishes four kinds:

Edge kind	Source	How it is created
`contains`	Parent node	Structural nesting — a parent `<S>` automatically contains its children
`depends`	Requirement section	The `d` prop on an `<S>` tag, e.g. `<S id="auth.login" d="auth.session">`
`embeds`	Requirement section	An inline `{text(...)}` expression that pulls another node’s prose into the current one
`references`	Code location	A TypeScript marker in source code that points to a requirement ID

contains edges represent document structure. The other three — depends, embeds, and references — carry semantic meaning and are used when calculating coverage and impact.

contains edges are intentionally excluded from coverage reachability. A parent requirement being referenced does not automatically make its children covered. Each leaf must be reached independently.

Building the Graph

Run xspec build to parse your spec files and write the graph to .xspec/graph.json:

xspec build

The build step validates every requirement ID, resolves all d and {text(...)} references, and emits a type-annotated JSON file you can inspect or version-control.

You do not need to run xspec build manually before most read commands. The ids, show, coverage, impact, review, and query commands silently refresh graph data from your current files before reporting results.

Using the Graph

Once built, the graph powers a suite of read commands:

Command	What it does
`xspec ids`	Lists all requirement IDs in the project; `--tree` shows the hierarchy
`xspec show <id>`	Displays a single node with its edges, hashes, and metadata
`xspec coverage`	Reports which requirements are covered and which are not
`xspec impact`	Shows which requirements and code locations are affected by recent changes
`xspec review`	Scopes a review to requirements touched by a diff
`xspec query`	Runs a custom graph traversal query

The graph model means that any of these views is computed from the same source of truth — you never maintain separate coverage spreadsheets or impact matrices by hand.

Get Started

Core Concepts

Writing Specs

TypeScript Integration

Workflows

Understanding the xspec Project Dependency Graph

Nodes

Edge Kinds

Building the Graph

Using the Graph

​Nodes

​Edge Kinds

​Building the Graph

​Using the Graph

Nodes

Edge Kinds

Building the Graph

Using the Graph