xspec

Requirement traceability for specifications written in MDX.

xspec turns your spec documents into a typed, queryable dependency graph. Mark requirement sections with <S> tags; xspec compiles each document into a strongly typed TypeScript module, links requirements to the code that implements and tests them, and uses the resulting project-wide graph to validate references, enforce dependency policy, measure coverage, analyze the impact of changes, and drive staged reviews.

{/* specs/AUTH.mdx */}
<S id="auth">
Authentication.

<S id="auth.login" tags="happy-path">
Users sign in with an email address and a password.
</S>
</S>

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

export function login(email: string, password: string): boolean {
  AUTH.auth.login   // type-checked reference: this code implements that requirement
  return email.includes("@") && password.length > 0
}

xspec build                 # typed modules + Markdown + project graph
xspec check                 # validate everything; exit 1 on any finding
xspec coverage tested --check   # gate CI on requirement coverage
xspec impact --base main    # what does this change touch?

Why

• References that can't rot. Requirement references in code are real TypeScript — hover shows the requirement text, go-to-definition jumps into the .mdx, and a renamed or deleted requirement is a compile error, not silent drift.
• A graph, not a convention. Sections, declared dependencies (d), text embeddings ({text(...)}), and code references form one project-wide graph you can query, gate, and diff.
• Coverage as reachability. Named profiles ask precise questions — "is every product requirement referenced by a test?" — and --check turns them into CI gates.
• Impact you can trust. Hash-based change detection attributes every downstream effect to the edit that caused it; xspec rename/xspec move record identity mappings in a journal, so refactoring produces zero spurious impact.
• Reviews with memory. Changes, audits, and coverage gaps become durable, staged checklists that unlock bottom-up and flag resolutions invalidated by later edits.
• Deterministic by construction. Every output and generated file is byte-identical for identical input: no timestamps, no randomness, no network. Exit codes mean things (0 success, 1 findings, 2 usage/config errors). Every command speaks --json.

Getting started

Requires Node.js ≥ 22. Not yet published to npm — run from a checkout:

git clone https://github.com/modularcloud/xspec.git
cd xspec && npm ci && npm run build
npm link    # puts `xspec` on your PATH

Then follow docs/getting-started.md to set up a project in minutes.

Documentation

Usage guides live in docs/:

| | | |---|---| | Getting started | Install → first project → first coverage report | | Writing specs | The .mdx syntax: sections, IDs, d, text(), tags | | Configuration | xspec.config.ts: groups, Markdown, coverage profiles, policy | | TypeScript integration | Generated modules, markers, text(), compiler setup | | CLI reference | Every command, flag, exit code, and convention | | Coverage | Profiles, boundaries, modes, CI gating | | Impact analysis | Hashes, change categories, baselines, impacted code | | Reviews | Staged review sessions and strategies | | Renaming & moving | Identity-preserving refactoring and the journal | | Workspace files | What xspec writes and what to commit |

The authoritative behavioral specification is specs/SPEC.md; the docs are the guide, the spec is the law.

Development

This repository is built and maintained through Spec-Driven Generation (SDG): the specification is the master artifact, and the spec, tests, and implementation are generated and kept in lockstep by the process defined in specs/PROCESS.md (with Claude Code bindings in specs/CLAUDE-PROCESS.md and scaffolding under .claude/). Humans steer by editing goals and answering questions — not by hand-writing code — so issues and ideas are welcome as problem statements rather than patches.

Build and test instructions (for CI and process runs) are in AGENTS.md: npm ci, npm run build, npm test. The test harness under test/ is a separate program that drives the built xspec executable as a subprocess; certification fixtures keep the harness itself honest.

License

MIT