Get Started with xspec: Install and First Coverage

Install xspec from source, create a config, write your first spec, reference it from TypeScript, and measure coverage — all in under ten minutes.

This guide walks you through the complete xspec workflow from a fresh machine to a passing coverage check. By the end you will have xspec installed, a working xspec.config.ts, a real spec file, a TypeScript source file that references it, and a CI-ready xspec coverage tested --check command that gates on full traceability.

1. Install xspec

   xspec is not yet published to npm, so you install it directly from the source repository. You need Node.js 22 or later before you begin.

   Clone the repository, install dependencies, build the project, and link the binary onto your PATH:

   git clone https://github.com/modularcloud/xspec.git
   cd xspec
   npm ci
   npm run build
   npm link
   

   Verify the installation:

   xspec --version
   

   npm link creates a global symlink so you can run xspec from any directory. If you prefer not to use a global link, you can invoke the binary directly with node /path/to/xspec/dist/cli.js instead.

2. Create your project config

   Navigate to the root of the project you want to add xspec to and create xspec.config.ts. This file tells xspec where your spec files live, where your application code lives, and how to define coverage profiles.

   // xspec.config.ts
   import { defineConfig } from "xspec"
   
   export default defineConfig({
     specs: { product: ["specs/**/*.mdx"] },
     code: { app: ["src/**/*.ts"], tests: ["test/**/*.ts"] },
     markdown: { emit: true },
     coverage: [
       {
         name: "tested",
         target: "product",
         boundary: "tests",
         mode: "direct",
       },
     ],
   })
   

   The config above declares:

   • A product spec group covering every MDX file under specs/.
   • An app code group for your source files and a tests group for your test files.
   • A tested coverage profile that measures which product requirements are reachable from the tests boundary.

   defineConfig is imported from the xspec package that you just built and linked. Your project does not need to list xspec as a dependency in its own package.json — the globally linked binary resolves the import automatically.

3. Write your first spec

   Create a specs/ directory at your project root and add your first MDX specification file. Use the <S> component to declare requirements; nest <S> elements to express hierarchy; use the tags prop to label requirements with cross-cutting concerns.

   {/* 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>
   

   Each id becomes a property path on the generated TypeScript module. Dotted segments (auth.login.valid) translate to nested property accesses (AUTH.auth.login.valid).

4. Build the typed modules

   Run xspec build from your project root to compile the spec files into typed TypeScript modules and assemble the project graph:

   xspec build
   

   This produces a specs/AUTH.xspec file (and a Markdown file if markdown.emit is true in your config). The .xspec file is the typed module you import in application and test code.

   Commit the generated .xspec files to version control. They are the source of truth for your dependency graph and must be present for TypeScript to resolve imports.

5. Reference requirements from TypeScript

   Open (or create) a source file and import the generated module. Place a property access wherever you want to declare that a given piece of logic implements or exercises a requirement:

   // src/auth.ts
   import AUTH from "../specs/AUTH.xspec"
   
   export function login(email: string, password: string): boolean {
     AUTH.auth.login.valid   // dependency marker
     return email.includes("@") && password.length > 0
   }
   

   The property access is the dependency marker. xspec records it in the graph at build time. If the requirement identifier changes in the spec, TypeScript will surface a type error here immediately.

   Add a corresponding reference in your test file so the tested coverage profile can find a path from the tests boundary to the requirement:

   // test/auth.test.ts
   import AUTH from "../specs/AUTH.xspec"
   import { login } from "../src/auth"
   
   AUTH.auth.login.valid   // marks this test as covering the requirement
   AUTH.auth.login.invalid
   
   // ... your test assertions
   
6. Measure and enforce coverage

   Run xspec coverage to see the current coverage report across all defined profiles:

   xspec coverage
   

   To enforce full coverage as a CI gate — exiting with code 1 if any requirement in the tested profile is uncovered — use the --check flag:

   xspec coverage tested --check
   

   Add this command to your CI pipeline to ensure every requirement is traced to at least one test before merging.

Make xspec build && xspec check your everyday inner loop. xspec build regenerates the typed modules and graph whenever you change a spec; xspec check validates the integrity of all cross-file references. Running both together gives you instant feedback before you commit.