reqmd

reqmd is a command-line tool that traces requirements from Markdown documents to their coverage in source code. It automatically generates traceability links, ensuring seamless tracking between specifications and implementation.

Features

• Extracts requirement references from Markdown files
• Scans source files for coverage tags
• Generates and updates coverage footnotes in Markdown
• Uses branch references (main/master) for stable file URLs
• Fast & scalable – uses Go concurrency to process files efficiently
• Supports multiple paths with mixed markdown and source files

Installation

Install reqmd via Go:

go install github.com/voedger/reqmd@latest

or build from source:

git clone https://github.com/voedger/reqmd.git
cd reqmd
go build -o reqmd .

Usage

Tracing requirements

Scan directories containing both Markdown files and source code to generate coverage mapping:

reqmd [-v] trace [ (-e | --extensions) <extensions>] [--dry-run | -n] <paths>...

Options

• -v: Enable verbose output showing detailed processing information
• -e, --extensions: Comma-separated list of source file extensions to process (e.g., ".go,.ts,.js")
• -n, --dry-run: Perform a dry run without modifying files

Arguments

• <paths>: One or more paths to process. Each path can contain both markdown requirement files and source code with coverage tags
  • At least one path must be provided
  • When multiple paths are provided, they are processed in sequence

Examples

Process a single directory containing both markdown and source files:

reqmd trace project/

Process multiple directories with mixed content:

reqmd trace docs/ src/ tests/

Process only Go and TypeScript files in multiple directories:

reqmd trace -e .go,.ts docs/ src/ tests/

Process with verbose output:

reqmd trace -v docs/ src/ tests/

Example files

requirements.md

- APIv2 implementation shall provide a handler for POST requests. `~Post.handler~`covrd[^~Post.handler~].

handler.go

// [~server.api.v2/Post.handler~impl]
func handlePostRequest(w http.ResponseWriter, r *http.Request) {
    // Implementation
}

Generated coverage footnote for requirements.md:

[^~Post.handler~]: `[~server.api.v2~impl]`[pkg/http/handler.go:42:impl](https://github.com/repo/pkg/http/handler.go#L42)

Output files

Markdown files

Markdown files are updated with:

• Coverage annotations for requirement sites
• Coverage footnotes linking requirements to implementations

Technical documentation

Refer to docs/README.md for detailed technical documentation.

Requirements & dependencies

• Go 1.24+

Contributing

We welcome contributions. To get started:

1. Fork the repository
2. Clone your fork locally
3. Create a branch for your changes
4. Commit and push
5. Open a Pull Request

git clone https://github.com/yourusername/reqmd.git
cd reqmd
git checkout -b feature-new-enhancement

License

reqmd is released under the Apache 2.0 license. See LICENSE.txt

Acknowledgments

• Notation is inspired by OpenFastTrace.