@underwoodinc/requirements-tracer

Link every automated test to a requirement ID in a YAML registry, audit that link in CI, and publish a searchable HTML report on pull requests.

Companion to the Requirements Tracer GitHub Action. Requires Node.js 22+. MIT license.

Full documentation: github.com/Underwood-Inc/requirements-tracer-action/tree/main/docs · onboarding guide

Install

npm install -D @underwoodinc/[email protected]

Add scripts to package.json:

{
  "scripts": {
    "trace:audit": "trace audit --root . --config .traceability.yaml",
    "trace:report": "trace report --root . --config .traceability.yaml",
    "trace:scan": "trace scan --root . --config .traceability.yaml"
  }
}

What you need in the repo

| File | Purpose | |------|---------| | requirements-registry.yaml | Source of truth for requirement IDs (or shards via registryGlobs) | | .traceability.yaml | Test globs, kinds, trace-ID regex, report output paths | | Tagged tests | test('[FR-001] loads home view', …) — ID in the description string |

Kinds (FR, NFR, SEC, BR, custom keys like META, A11Y) are all first-class — not FR-only.

Minimal registry

schema_version: 1
requirements:
  FR-001:
    kind: FR
    title: Application loads home view
    status: active
  SEC-001:
    kind: SEC
    title: Session cookie is HttpOnly
    status: active

Minimal config

schema_version: 1
traceIdPattern: "\\[((?:[A-Z][A-Z0-9]*-)+\\d+)(?:,\\s*((?:[A-Z][A-Z0-9]*-)+\\d+))*\\]"
requireTraceId: error
kinds:
  FR:  { label: Functional }
  SEC: { label: Security }
testGlobs:
  - "**/*.test.ts"
  - "**/*.spec.ts"
output:
  reportDir: traceability-report
  reportEntry: index.html

CLI commands

npx trace audit --root .          # validate trace IDs; exit 1 on errors
npx trace report --root .         # write HTML + summary.json
npx trace scan --root .           # JSON dump of parsed tests
npx trace comment --root . --new  # PR comment (CI only)

Flags: --config .traceability.yaml, --registry requirements-registry.yaml, --strict (orphans / deprecated / unknown JSDoc tags → errors).

Report outputs

Written to output.reportDir (default traceability-report/):

| File | Purpose | |------|---------| | index.html | Self-contained searchable report (@untested, @sec, #tags, …) | | summary.json | Machine-readable counts for CI and automation | | audit.json | Raw audit findings |

GitHub Actions (recommended)

permissions:
  contents: read
  pull-requests: write   # PR comments
  checks: write          # inline diff annotations

jobs:
  traceability:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: Underwood-Inc/[email protected]
        with:
          tracer-package: '@underwoodinc/[email protected]'
          token: ${{ secrets.GITHUB_TOKEN }}

The Action runs audit (with GitHub line annotations) → report → artifact upload → PR comment with a direct download link.

Custom PR comment? Set post-comment: 'false' and read summary.json from your report directory. Match report-dir to .traceability.yaml → output.reportDir. See ci-integration.md.

Programmatic API

Merge registry shards from Node scripts, Vite plugins, or custom report pipelines:

import {
  loadRequirementsRegistrySync,
  registryToJsonDocument,
} from '@underwoodinc/requirements-tracer/load-registry';

const registry = loadRequirementsRegistrySync({
  rootDir: process.cwd(),
  registryGlobs: ['requirements/*.yaml', 'src/**/*.fr.yaml'],
});

Optional JSDoc on tests

/**
 * @description Verifies checkout rejects expired sessions.
 * @owner platform
 * @priority high
 */
test('[SEC-001] expired JWT returns 401', () => { /* … */ });

Tag vocabulary: jsdoc-tags.md

Reference adopter

hello-desktop — minimal registry, Action wiring, and tagged Vitest tests.

Links

| Resource | URL | |----------|-----| | GitHub Action + source | https://github.com/Underwood-Inc/requirements-tracer-action | | Documentation index | https://github.com/Underwood-Inc/requirements-tracer-action/tree/main/docs | | npm | https://www.npmjs.com/package/@underwoodinc/requirements-tracer |

License

MIT — Underwood-Inc