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.

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

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

xspec build && xspec check

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

xspec check --json