Traceability Tooling

Universal traceability validation and rollup for requirements ↔ tests mapping. Designed to work across monorepos and git submodules.

Install

pip install tracetree

Quick Start

From a repo root with docs/traceability/:

tracetree init
tracetree validate
tracetree link
tracetree aggregate

Expected Structure (Defaults)

• docs/traceability/requirements.md
• docs/traceability/risk_controls.md
• docs/traceability/traceability_matrix.csv
• docs/traceability/soup_inventory.md
• docs/traceability/iec62304_mapping.csv
• docs/traceability/verification_plan.md

If you do not already have these files, run:

tracetree init

Generated reports (default):

• docs/traceability/generated/traceability_report.md
• docs/traceability/generated/traceability_report.json
• docs/traceability/generated/testid_links.md
• docs/traceability/generated/testid_links.json
• docs/traceability/generated/aggregate/traceability_rollup.md
• docs/traceability/generated/aggregate/traceability_rollup.json
• docs/traceability/generated/iec62304_traceability_table.md

Test discovery defaults:

• GTest: tests/, test/
• Pytest: tests/, test/
• JS/TS (Jest/Mocha/Vitest): tests/, test/, __tests__/, spec/
• Rust (#[test]): tests/, test/, src/

TestID matching:

• GTest: SuiteName.TestName
• Pytest: test_function_name
• JS/TS: string in test("name", ...) or it("name", ...)
• Rust: function name following #[test]

IEC 62304 mapping file format (iec62304_mapping.csv):

RequirementID,SoftwareItem,IntegrationSystemTest,Evidence
REQ-EXAMPLE-1,Example Module,verify_reliability.py,Test logs

Repo Configuration

Create .traceability/config.json to override defaults:

{
  "traceability_dir": "docs/traceability",
  "traceability_output_dir": "docs/traceability/generated",
  "requirements_file": "requirements.md",
  "risk_controls_file": "risk_controls.md",
  "matrix_file": "traceability_matrix.csv",
  "iec62304_mapping_file": "iec62304_mapping.csv",
  "gtest_roots": ["tests"],
  "pytest_roots": ["bindings/python/tests"],
  "js_roots": ["packages/web/tests"],
  "rust_roots": ["crates/core/tests", "crates/core/src"]
}

You can also point to a custom config with TRACEABILITY_CONFIG=/path/to/config.json.

Coverage Threshold

Default is 100%. Override with:

TRACEABILITY_REQ_COVERAGE=0.95 tracetree validate

Submodule Rollup

tracetree aggregate reads .gitmodules and validates each submodule that contains traceability files. Results are written to: docs/traceability/generated/aggregate/traceability_rollup.md. Combined source + generated files are copied to: docs/traceability/generated/aggregate/combined/.