Lightning-fast, reference-based requirement tracing
flashtrace verifies that every requirement in your Markdown specs is covered by the code and tests it demands - with zero runtime dependencies, anywhere Node.js runs.
## Login requirement
`req:auth/login#1`
Users must be able to log in
with email and password.
Needs: impl:auth/login#1// [impl:auth/login#1]
export function login(
email: string,
password: string,
) {
return session.open(
email, password);
}$ npx flashtrace
Summary
items 2 (1 from specs, 1 from code)
ok 2
defective 0
okHow it works
-
1
Write specs in Markdown
An item is a line holding only its ID in backticks. The heading above becomes its title, the paragraph below its description and Needs lists the IDs that must cover it.
## Login requirement `req:auth/login#1` Users must be able to log in. Needs: impl:auth/login#1 -
2
Tag your code
Drop the ID into a comment - flashtrace understands the comment syntax of dozens of languages, from C-Like (incl. JS/TS) to SQL to Powershell.
// [impl:auth/login#1] // [>>utest:auth/login#1] export function login(token) { … } -
3
Run flashtrace
One command traces every requirement to its coverage - transitively - and reports what is missing, orphaned, unwanted, outdated or duplicated.
$ npx flashtrace Summary items 3 (1 from specs, 2 from code) ok 3 defective 0 ok
Built to stay out of your way
Zero runtime dependencies
One self-contained script. Vendor it or install it - nothing else comes along.
Runs anywhere
Everything Node.js ≥ 18 runs on: your laptop, your CI, your air-gapped build box.
Many languages (40+)
A tag is just a comment, so one syntax spans them all: C-family, hash (Python, shell, ..), SQL, Lua, HTML, ... Learn more
Deep, transitive coverage
An item is only deep-covered when its whole tracing chain is. Broken links show up wherever they hide. Learn more
SemVer revisions & wildcards
Revisions match as SemVer versions - 2.4 equals 2.4.0 - and a 2.x wildcard accepts anything within revision 2. Learn more
Forwarding
Delegate a requirement’s obligation to another item with a forwarding tag - coverage follows the chain. Learn more
Git-aware scanning
Files ignored by git are excluded automatically - no config to keep in sync. Learn more
Rich, CI-friendly reports
A readable text report or deterministic, schema-backed JSON on stdout - and meaningful exit codes: 0 clean, 1 defects found, 2 usage error. Learn more
See it trace
Three scenarios, captured from real flashtrace runs. Flip each between its input files and the report it produces.
A requirement accepts anything within revision 2 - the 2.x wildcard resolves to impl:login#2.4 and the whole chain is deep-covered.
## Login
`req:login#1`
Users can sign in with a session token.
Needs: impl:login#2.x// [impl:login#2.4]
export function login(token: SessionToken) {
return openSession(token);
}$ flashtrace -v
✔ impl:login#2.4 login.ts:1 [deep-covered]
wanted by req:login#1 spec.md:3
✔ req:login#1 "Login" spec.md:3 [deep-covered]
needs impl:login#2.x (→ impl:login#2.4) ✔ login.ts:1
Summary
items 2 (1 from specs, 1 from code)
ok 2
defective 0
okThe spec needs test:auth/login#2, but only revision 1 exists - flashtrace flags the revision mismatch, and the outdated test as unwanted.
## Login requirement
`req:auth/login#1`
Users must be able to log in with email and password.
Needs: impl:auth/login#1, test:auth/login#2// [impl:auth/login#1]
export function login(email: string, password: string) {
return session.open(email, password);
}
// [test:auth/login#1]
test('login opens a session', () => { ... });$ flashtrace
✘ test:auth/login#1 login.ts:6
• unwanted: no item needs test:auth/login#1
✘ req:auth/login#1 "Login requirement" spec.md:3
• uncovered: needs test:auth/login#2, which does not exist (revision mismatch: existing revision(s) of test:auth/login: 1)
Summary
items 3 (1 from specs, 2 from code)
ok 1
defective 2
not okreq:login#1 delegates its coverage obligation to the auth design with a --> tag; it is deep-covered exactly when dsn:auth#2 is.
## Login
`req:login#1`
Login is specified in detail by the auth design.
`[req:login#1 --> dsn:auth#2]`
## Auth design
`dsn:auth#2`
Sessions are opened through the central auth service.
Needs: impl:auth#1// [impl:auth#1]
export function openSession(token: SessionToken) { ... }$ flashtrace -v
✔ impl:auth#1 auth.ts:1 [deep-covered]
wanted by dsn:auth#2 spec.md:11
✔ req:login#1 "Login" spec.md:3 [deep-covered]
→ dsn:auth#2 ✔ spec.md:11
✔ dsn:auth#2 "Auth design" spec.md:11 [deep-covered]
needs impl:auth#1 ✔ auth.ts:1
Summary
items 3 (2 from specs, 1 from code)
ok 3
defective 0
okInstall in seconds
Two ways in, both ending at the same single file. Current release: v0.12.1.
As a dev dependency
npm install flashtrace -D
npx flashtraceVendored, zero install
Download dist/flashtrace.mjs into your repository and run it directly.
node flashtrace.mjsNode.js ≥ 18 required. Read the Usage Guide for options and details.