xspec

Requirement traceability for specifications written in MDX.

xspec turns your spec documents into a typed, queryable dependency graph. You mark requirement sections with <S> tags, and xspec compiles each document into a strongly typed TypeScript module. It links requirements to the code that implements and tests them, then 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?
xspec occurrences --to "specs/AUTH.mdx#auth.login"   # every reference, with byte positions
xspec rename specs/AUTH.mdx auth.login auth.signIn --preview   # see a refactoring before running it

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 that you can query, gate, and diff.

• Coverage as reachability. Named profiles ask precise questions, such as "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 and xspec move record identity mappings in a journal, so refactoring produces zero spurious impact, and --preview lists every edit before anything changes.

• Reviews with memory. Changes, audits, and coverage gaps become durable, staged checklists. Items unlock bottom-up, and resolutions that later edits invalidate get flagged.

• Built for tools. xspec is headless, and editors, visualizers, and agents build on its machine interface:

  • structural views of each document, positioned on its raw bytes;
  • every reference with exact byte positions;
  • a machine-readable inventory of which files xspec reads and owns;
  • findings with stable codes and source ranges;
  • a versioned JSON contract.

  These keep answering mid-edit, when the workspace is temporarily invalid.

• 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 or configuration errors. Every command speaks --json.

Getting started

Requires Node.js ≥ 22. Install it from npm as a development dependency:

npm install --save-dev @modularcloud/xspec
npx @modularcloud/xspec version

The package provides the xspec command and the defineConfig function that your xspec.config.ts imports with import { defineConfig } from "@modularcloud/xspec", so your editor and tsc type-check your configuration. You can also install it globally with npm install -g @modularcloud/xspec, or try it without installing via npx @modularcloud/xspec <command>. Always give npm and npx the full scoped name: the unscoped name belongs to an unrelated package.

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

Documentation

Usage guides live in docs/:

| Guide | What it covers | |---|---| | 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, type checking | | TypeScript integration | Generated modules, markers, text(), compiler setup | | CLI reference | Every command, flag, exit code, finding 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, previews, and the journal | | Workspace files | What xspec writes and what to commit | | Machine interface | Building editors and tools: view, occurrences, at, inventory, version, JSON forms |

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, and certification fixtures keep the harness itself honest.

License

MIT