> ## 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 build and check: Build and Validate

> Reference for xspec build (parse, validate, generate) and xspec check (full validation including staleness and policy) with the complete findings catalog.

`build` and `check` are your two validation commands. `build` parses your sources and produces all derived artifacts; `check` is a read-only gate that confirms everything is consistent and policy-compliant. Run them together as a CI pipeline step: `xspec build && xspec check`.

## xspec build

`build` parses every source file, validates structure, IDs, tags, and references, resolves all dependencies, generates TypeScript modules, emits Markdown (when enabled in your config), and writes the graph data used by all read commands. On success it produces no output — silence means clean.

A failed `build` modifies nothing. If any finding is reported (exit `1`) or a configuration error occurs (exit `2`), your workspace is left exactly as it was.

`build` does **not** evaluate policy rules — that is handled exclusively by `check`.

```sh theme={null}
$ xspec build
$ echo $?
0
```

### What build validates

* Structural validity of every source file
* ID uniqueness and well-formedness
* Tag syntax
* Reference resolution (`d` attributes, `text(...)` calls, TypeScript references)
* Dependency and import graph acyclicity

### What build generates

* TypeScript modules for every spec group
* Markdown output files (if `markdown.emit` is enabled)
* Graph data consumed by `ids`, `show`, `coverage`, `impact`, `query`, and `review`

## xspec check

`check` performs everything `build` validates and then adds a second layer of checks that are only meaningful on an already-built workspace. Because it writes nothing, it is safe to run in any environment, including read-only CI runners.

```sh theme={null}
$ xspec check
specs/AUTH.mdx:331-353: invalid structural ID (14.2): ...
1 finding
```

Every finding line contains the file and location, the condition code (numbered per SPEC §14), and a description of the required correction.

### Additional checks beyond build

* **Staleness** — generated files must match sources byte-for-byte; orphaned derived files with no corresponding source are reported
* **Reference completeness** — all references must resolve and be static
* **Cycle detection** — no dependency or import cycles
* **Journal integrity** — journal must be well-formed and fully replayable
* **Policy compliance** — all configured policy rules must pass
* **Review session integrity** — all active review sessions must be intact

## Validation findings catalog

| #  | Condition                                                                         |
| -- | --------------------------------------------------------------------------------- |
| 1  | Missing ID                                                                        |
| 2  | Invalid structural ID                                                             |
| 3  | Duplicate ID                                                                      |
| 4  | Invalid segment or tag                                                            |
| 5  | Unresolved `d` reference                                                          |
| 6  | Unresolved `text(...)` target                                                     |
| 7  | Unresolved TypeScript reference                                                   |
| 8  | Non-static reference; wrong `text(...)` arity; string-form `text()` in TypeScript |
| 9  | Dependency cycle or spec import cycle                                             |
| 10 | Stale or orphaned generated output — `check` only                                 |
| 11 | Cross-module text call                                                            |
| 12 | Policy violation — `check` only                                                   |
| 13 | Journal error                                                                     |
| 14 | Configuration error — exit `2`                                                    |
| 15 | Invalid import                                                                    |
| 16 | Invalid construct in spec file                                                    |
| 17 | Invalid prop on `<S>` / `<Spec>`                                                  |
| 18 | Unsupported node usage in TypeScript                                              |
| 19 | Invalid source path                                                               |
| 20 | Unparseable source                                                                |
| 21 | Corrupt review session — `check` and `review` subcommands                         |
| 22 | Symbolic link in a write path                                                     |

## CI gate pattern

Run `build` first to regenerate all derived artifacts, then `check` to verify the full constraint set. If either exits non-zero, the pipeline fails.

```sh theme={null}
xspec build && xspec check
```

You can also use `--json` on `check` to consume findings programmatically:

```sh theme={null}
xspec check --json
```