What is xspec and Why It Matters

Understand xspec’s core model — typed requirement references, a graph-based dependency model, reachability coverage, and hash-based impact analysis.

xspec is a developer tool that turns MDX specification documents into a typed, queryable dependency graph. You write requirements as nested <S> components in plain MDX files; xspec compiles those files into TypeScript modules whose properties map one-to-one with your requirement identifiers. When you import that module in your application or test code, the TypeScript compiler can verify that every reference is valid, every rename is caught, and every deleted requirement produces a build error rather than a silent gap in coverage.

The core value propositions

Software teams spend enormous effort writing requirements in one place and code in another, then manually trying to keep the two in sync. xspec replaces that manual effort with a compiler-enforced link. Here is what that unlocks:

References that cannot rot. Because requirement identifiers become TypeScript property accesses, a rename or deletion in your spec file immediately surfaces as a type error in every file that references it. There is no runtime discovery of stale links.

Graph, not convention. xspec builds an explicit directed graph between requirements and the code that references them. Coverage and impact analysis run over that graph, so results are precise and reproducible rather than dependent on file-naming conventions or folder structure.

Coverage as reachability. The xspec coverage command measures which requirements are reachable from a defined boundary — for example, your test files. This is conceptually closer to what “tested” actually means than line-based coverage, and it lets you define multiple named coverage profiles in a single config.

Hash-based impact analysis. xspec impact --base main computes which requirements are transitively affected by the changes since a given Git ref. You can use this in pull-request workflows to focus review and testing on exactly the requirements that matter for a given diff.

Reviews with memory. Because specs live in version control alongside code, pull requests contain both the requirement change and the implementation change in the same diff. Reviewers see context; history is preserved.

Deterministic output. xspec build is a pure function of its inputs. Given the same spec files and config, it always produces the same typed modules and graph. This makes caching, incremental builds, and reproducible CI straightforward.

How the pieces fit together

The typical workflow connects three artifacts: an MDX spec file, a generated TypeScript module, and your application or test code.

You write a spec like this:

{/* specs/AUTH.mdx */}
<S id="auth">
Authentication.
<S id="auth.login">
Users sign in with an email address and a password.
<S id="auth.login.valid" tags="happy-path">
A user submitting valid credentials is signed in.
</S>
<S id="auth.login.invalid" tags="negative">
Invalid credentials are rejected with a generic error message.
</S>
</S>
<S id="auth.lockout" tags="negative temporal">
Five consecutive failed attempts lock the account for 15 minutes.
</S>
</S>

After running xspec build, you get a typed module at specs/AUTH.xspec. You import it in your source or test code to declare which requirements a given piece of logic implements or exercises:

// src/auth.ts
import AUTH from "../specs/AUTH.xspec"

export function login(email: string, password: string): boolean {
  AUTH.auth.login.valid   // dependency marker — the compiler validates this path
  return email.includes("@") && password.length > 0
}

If you later rename auth.login.valid to auth.login.success in the spec, TypeScript will error on the stale reference in src/auth.ts — before the code ships and before any test runs.

The AUTH.auth.login.valid expression is a property access used purely as a dependency marker. xspec records the reference in the graph at build time; you do not need to call a function or assign the result.

What xspec is not

xspec does not replace your testing framework, your issue tracker, or your documentation site. It is a traceability layer that sits alongside those tools. Specs describe what the system should do; your tests verify it; xspec makes the connection between the two explicit and machine-checkable.

Quickstart

Follow the step-by-step guide to install xspec and trace your first requirement end to end.

CLI Reference

See the full reference for every xspec command and option.