Understanding the xspec Project Dependency Graph

xspec parses MDX spec files and builds a typed, queryable dependency graph connecting requirements to code — powering coverage, impact, and review.

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.