> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Steps>
  <Step title="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`:

    ```sh theme={null}
    git clone https://github.com/modularcloud/xspec.git
    cd xspec
    npm ci
    npm run build
    npm link
    ```

    Verify the installation:

    ```sh theme={null}
    xspec --version
    ```

    <Note>
      `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.
    </Note>
  </Step>

  <Step title="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.

    ```ts theme={null}
    // 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.

    <Tip>
      `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.
    </Tip>
  </Step>

  <Step title="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.

    ```mdx theme={null}
    {/* 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`).
  </Step>

  <Step title="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:

    ```sh theme={null}
    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.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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:

    ```ts theme={null}
    // 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:

    ```ts theme={null}
    // 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
    ```
  </Step>

  <Step title="Measure and enforce coverage">
    Run `xspec coverage` to see the current coverage report across all defined profiles:

    ```sh theme={null}
    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:

    ```sh theme={null}
    xspec coverage tested --check
    ```

    Add this command to your CI pipeline to ensure every requirement is traced to at least one test before merging.
  </Step>
</Steps>

<Tip>
  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.
</Tip>