> ## 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.

# 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.

<Note>
  `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.
</Note>

## Building the Graph

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

```sh theme={null}
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.

<Tip>
  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.
</Tip>

## 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.