reqcov 0.1.0__tar.gz

reqcov-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine005
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reqcov-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: reqcov
+Version: 0.1.0
+Summary: Automate requirements traceability: trace requirements to tests and code, fail CI on gaps, generate audit-ready traceability matrices.
+Author: reqcov contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Antoine005/reqcov
+Keywords: requirements,traceability,IEC 62304,ISO 26262,DO-178C,EN 50128,CI,github-actions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: Jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# reqcov — requirements coverage for pull requests
+
+**Codecov, but for your requirements.** reqcov reads the requirements you already keep in your
+repository (Markdown, YAML or Doorstop), finds the tests and code that reference them, merges
+the JUnit results of your test run, and tells every pull request which requirements are
+**uncovered**, **covered**, **verified** or **failing** — then writes the traceability matrix an
+auditor asks for (IEC 62304, ISO 26262, EN 50128, DO-178C, IEC 61508, ECSS).
+
+No server, no account, no new editor: a CLI + a GitHub Action.
+
+```text
+## ❌ Requirements coverage: 83.3%
+
+| Requirements | With test | Verified | Uncovered | Failing | Unknown ids | Orphan tests |
+|---:|---:|---:|---:|---:|---:|---:|
+| 8 | 5 | 5 | 1 | 0 | 0 | 1 |
+
+- SRS: 75% of 4 testable requirements have a test
+- SYS: 100% of 2 testable requirements have a test
+
+### ❌ 1 error(s)
+- `COVERAGE` test coverage of requirements 83.3% is below the required 100.0%
+```
+
+## How it works
+
+1. **Requirements** live in your repo, one id per requirement (`SYS-1`, `SRS-12`, `LLR-3`…):
+
+   ```markdown
+   ## SRS-11 — Over-temperature cut-off
+   The controller shall force the heater off when temperature ≥ 35 °C.
+   Parent: SYS-2
+   Verification: test
+   ```
+
+   YAML lists and [Doorstop](https://github.com/doorstop-dev/doorstop) items are also read.
+
+2. **Tests and code** reference ids with a marker — any language, in a comment, a decorator, a
+   macro:
+
+   ```python
+   @pytest.mark.req("SRS-11", "SYS-2")
+   def test_overtemp_cutoff(): ...
+   ```
+
+   ```c
+   /* @req LLR-12 */
+   void test_frame_bad_crc_is_rejected(void) { ... }
+
+   /* @implements LLR-11, LLR-12 */
+   frame_status_t frame_validate(const uint8_t *frame, size_t len) { ... }
+   ```
+
+   ```cpp
+   // @verifies SWR-2
+   TEST(RingBuffer, PushOnFullFails) { ... }
+   ```
+
+3. **JUnit XML** (pytest, Ceedling, GoogleTest, CTest, Jest, Maven…) turns *covered* into
+   *verified* or *failing*.
+
+4. **Rules** in `reqcov.yml` decide what fails the build: minimum coverage, unknown ids,
+   orphan tests, mandatory parent links per level, mandatory `@implements` per level.
+
+## Quick start
+
+```bash
+pip install reqcov
+reqcov init                       # writes reqcov.yml — edit the globs
+pytest --junitxml=reports/junit.xml
+reqcov check                      # exit 1 on rule violations, writes reqcov-report/
+open reqcov-report/index.html
+```
+
+`reqcov-report/` contains `index.html` (interactive matrix), `matrix.csv` (auditor-friendly),
+`coverage.json` (machine readable) and `summary.md` (the PR comment).
+
+## GitHub Action
+
+```yaml
+name: requirements
+on: [pull_request, push]
+jobs:
+  reqcov:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install -e . pytest && pytest --junitxml=reports/junit.xml
+      - uses: Antoine005/reqcov@v0
+        with:
+          junit: reports/junit.xml
+```
+
+The action posts (and keeps updating) one sticky comment on the pull request, writes the
+summary to the job page, emits annotations on the requirement lines that are uncovered or
+failing, and uploads the report directory as an artifact.
+
+## Configuration (`reqcov.yml`)
+
+```yaml
+id_pattern: "[A-Z][A-Z0-9_]*-\\d+"   # level = everything before the last dash
+requirements: [docs/requirements/**/*.md]
+sources:      [src/**/*]              # scanned for @implements markers
+tests:        [tests/**/*]            # scanned for @req / @verifies markers
+junit:        [reports/*.xml]
+markers: [req, requirement, implements, verifies, satisfies, trace]
+rules:
+  min_test_coverage: 100        # % of testable requirements with ≥ 1 test
+  min_verified: null            # % that must be verified (needs junit)
+  fail_on_unknown_ids: true
+  fail_on_orphan_tests: false
+  fail_on_failing_tests: true
+  require_parent_for: [SRS]     # levels that must trace up
+  require_source_for: []        # levels that must have an @implements
+  allow_derived: true           # missing parent = warning (false: error)
+report:
+  out_dir: reqcov-report
+  formats: [html, csv, json, md]
+  title: "Software Requirements Traceability"
+```
+
+### Requirement metadata
+
+| Field | Markdown body line | YAML key | Values |
+|---|---|---|---|
+| parents | `Parent: SYS-1, SYS-2` | `parent` / `parents` / `links` | ids |
+| verification | `Verification: test` | `verification` | `test` (default), `analysis`, `inspection`, `demonstration`, `none` |
+| status | `Status: draft` | `status` (Doorstop: `active: false` → obsolete) | free text; `obsolete` is ignored by rules |
+| tags | `Tags: safety, ui` | `tags` | list |
+
+Only requirements with `verification: test` count toward test coverage; the others are shown
+as `n/a` in the matrix so the auditor still sees them.
+
+## Examples
+
+- [`examples/pytest-project`](examples/pytest-project) — Python, SYS→SRS levels, one deliberate gap and one orphan test.
+- [`examples/ceedling-unity`](examples/ceedling-unity) — C, HLR→LLR, `@implements` in sources, a failing Unity test propagating to two requirements.
+- [`examples/googletest`](examples/googletest) — C++, one-line requirements, GoogleTest `Suite.Name` results.
+
+## Status and roadmap
+
+`0.1` — CLI, Markdown/YAML/Doorstop input, marker scanning, JUnit merge, HTML/CSV/JSON/MD
+reports, GitHub Action with sticky PR comment. Planned: coverage delta against the base
+branch, StrictDoc and ReqIF input, Jira issue links, GitLab CI template, signed PDF export for
+audit packages, hosted history and badges.
+
+## License
+
+MIT.

reqcov-0.1.0/README.md

@@ -0,0 +1,152 @@
+# reqcov — requirements coverage for pull requests
+
+**Codecov, but for your requirements.** reqcov reads the requirements you already keep in your
+repository (Markdown, YAML or Doorstop), finds the tests and code that reference them, merges
+the JUnit results of your test run, and tells every pull request which requirements are
+**uncovered**, **covered**, **verified** or **failing** — then writes the traceability matrix an
+auditor asks for (IEC 62304, ISO 26262, EN 50128, DO-178C, IEC 61508, ECSS).
+
+No server, no account, no new editor: a CLI + a GitHub Action.
+
+```text
+## ❌ Requirements coverage: 83.3%
+
+| Requirements | With test | Verified | Uncovered | Failing | Unknown ids | Orphan tests |
+|---:|---:|---:|---:|---:|---:|---:|
+| 8 | 5 | 5 | 1 | 0 | 0 | 1 |
+
+- SRS: 75% of 4 testable requirements have a test
+- SYS: 100% of 2 testable requirements have a test
+
+### ❌ 1 error(s)
+- `COVERAGE` test coverage of requirements 83.3% is below the required 100.0%
+```
+
+## How it works
+
+1. **Requirements** live in your repo, one id per requirement (`SYS-1`, `SRS-12`, `LLR-3`…):
+
+   ```markdown
+   ## SRS-11 — Over-temperature cut-off
+   The controller shall force the heater off when temperature ≥ 35 °C.
+   Parent: SYS-2
+   Verification: test
+   ```
+
+   YAML lists and [Doorstop](https://github.com/doorstop-dev/doorstop) items are also read.
+
+2. **Tests and code** reference ids with a marker — any language, in a comment, a decorator, a
+   macro:
+
+   ```python
+   @pytest.mark.req("SRS-11", "SYS-2")
+   def test_overtemp_cutoff(): ...
+   ```
+
+   ```c
+   /* @req LLR-12 */
+   void test_frame_bad_crc_is_rejected(void) { ... }
+
+   /* @implements LLR-11, LLR-12 */
+   frame_status_t frame_validate(const uint8_t *frame, size_t len) { ... }
+   ```
+
+   ```cpp
+   // @verifies SWR-2
+   TEST(RingBuffer, PushOnFullFails) { ... }
+   ```
+
+3. **JUnit XML** (pytest, Ceedling, GoogleTest, CTest, Jest, Maven…) turns *covered* into
+   *verified* or *failing*.
+
+4. **Rules** in `reqcov.yml` decide what fails the build: minimum coverage, unknown ids,
+   orphan tests, mandatory parent links per level, mandatory `@implements` per level.
+
+## Quick start
+
+```bash
+pip install reqcov
+reqcov init                       # writes reqcov.yml — edit the globs
+pytest --junitxml=reports/junit.xml
+reqcov check                      # exit 1 on rule violations, writes reqcov-report/
+open reqcov-report/index.html
+```
+
+`reqcov-report/` contains `index.html` (interactive matrix), `matrix.csv` (auditor-friendly),
+`coverage.json` (machine readable) and `summary.md` (the PR comment).
+
+## GitHub Action
+
+```yaml
+name: requirements
+on: [pull_request, push]
+jobs:
+  reqcov:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install -e . pytest && pytest --junitxml=reports/junit.xml
+      - uses: Antoine005/reqcov@v0
+        with:
+          junit: reports/junit.xml
+```
+
+The action posts (and keeps updating) one sticky comment on the pull request, writes the
+summary to the job page, emits annotations on the requirement lines that are uncovered or
+failing, and uploads the report directory as an artifact.
+
+## Configuration (`reqcov.yml`)
+
+```yaml
+id_pattern: "[A-Z][A-Z0-9_]*-\\d+"   # level = everything before the last dash
+requirements: [docs/requirements/**/*.md]
+sources:      [src/**/*]              # scanned for @implements markers
+tests:        [tests/**/*]            # scanned for @req / @verifies markers
+junit:        [reports/*.xml]
+markers: [req, requirement, implements, verifies, satisfies, trace]
+rules:
+  min_test_coverage: 100        # % of testable requirements with ≥ 1 test
+  min_verified: null            # % that must be verified (needs junit)
+  fail_on_unknown_ids: true
+  fail_on_orphan_tests: false
+  fail_on_failing_tests: true
+  require_parent_for: [SRS]     # levels that must trace up
+  require_source_for: []        # levels that must have an @implements
+  allow_derived: true           # missing parent = warning (false: error)
+report:
+  out_dir: reqcov-report
+  formats: [html, csv, json, md]
+  title: "Software Requirements Traceability"
+```
+
+### Requirement metadata
+
+| Field | Markdown body line | YAML key | Values |
+|---|---|---|---|
+| parents | `Parent: SYS-1, SYS-2` | `parent` / `parents` / `links` | ids |
+| verification | `Verification: test` | `verification` | `test` (default), `analysis`, `inspection`, `demonstration`, `none` |
+| status | `Status: draft` | `status` (Doorstop: `active: false` → obsolete) | free text; `obsolete` is ignored by rules |
+| tags | `Tags: safety, ui` | `tags` | list |
+
+Only requirements with `verification: test` count toward test coverage; the others are shown
+as `n/a` in the matrix so the auditor still sees them.
+
+## Examples
+
+- [`examples/pytest-project`](examples/pytest-project) — Python, SYS→SRS levels, one deliberate gap and one orphan test.
+- [`examples/ceedling-unity`](examples/ceedling-unity) — C, HLR→LLR, `@implements` in sources, a failing Unity test propagating to two requirements.
+- [`examples/googletest`](examples/googletest) — C++, one-line requirements, GoogleTest `Suite.Name` results.
+
+## Status and roadmap
+
+`0.1` — CLI, Markdown/YAML/Doorstop input, marker scanning, JUnit merge, HTML/CSV/JSON/MD
+reports, GitHub Action with sticky PR comment. Planned: coverage delta against the base
+branch, StrictDoc and ReqIF input, Jira issue links, GitLab CI template, signed PDF export for
+audit packages, hosted history and badges.
+
+## License
+
+MIT.

reqcov-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reqcov"
+version = "0.1.0"
+description = "Automate requirements traceability: trace requirements to tests and code, fail CI on gaps, generate audit-ready traceability matrices."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "reqcov contributors" }]
+keywords = ["requirements", "traceability", "IEC 62304", "ISO 26262", "DO-178C", "EN 50128", "CI", "github-actions"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = ["PyYAML>=6.0", "Jinja2>=3.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov"]
+
+[project.scripts]
+reqcov = "reqcov.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Antoine005/reqcov"
+
+[tool.setuptools.packages.find]
+include = ["reqcov*"]
+
+[tool.setuptools.package-data]
+reqcov = ["templates/*.html"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

reqcov-0.1.0/reqcov/__init__.py

@@ -0,0 +1,3 @@
+"""reqcov — requirements coverage for pull requests."""
+
+__version__ = "0.1.0"

reqcov-0.1.0/reqcov/cli.py

@@ -0,0 +1,122 @@
+"""Command line interface.
+
+    reqcov check   [--config reqcov.yml] [--root .] [--junit reports/*.xml] [--out dir] [--no-report]
+    reqcov report  ... same options, never fails the build
+    reqcov init    write an example reqcov.yml
+    reqcov list    print requirements found
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .config import EXAMPLE_CONFIG, Config
+from .coverage import analyze
+from .report import render_markdown, write_reports
+
+
+def _common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--config", "-c", help="path to reqcov.yml (default: auto-detect in root)")
+    p.add_argument("--root", "-r", default=".", help="repository root (default: .)")
+    p.add_argument("--junit", action="append", help="JUnit XML glob (repeatable, overrides config)")
+    p.add_argument("--out", "-o", help="report output directory (overrides config)")
+    p.add_argument("--format", "-f", action="append", choices=["html", "csv", "json", "md"], help="report formats (repeatable)")
+    p.add_argument("--no-report", action="store_true", help="do not write report files")
+    p.add_argument("--quiet", "-q", action="store_true")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="reqcov", description="Requirements coverage for pull requests.")
+    p.add_argument("--version", action="version", version=f"reqcov {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+    c = sub.add_parser("check", help="analyze and fail (exit 1) when rules are violated")
+    _common(c)
+    r = sub.add_parser("report", help="analyze and write reports, never fails")
+    _common(r)
+    i = sub.add_parser("init", help="write an example reqcov.yml")
+    i.add_argument("--root", "-r", default=".")
+    i.add_argument("--force", action="store_true")
+    l = sub.add_parser("list", help="list requirements found")
+    _common(l)
+    return p
+
+
+def _load(args) -> Config:
+    cfg = Config.load(args.config, root=args.root)
+    if getattr(args, "junit", None):
+        cfg.junit = args.junit
+    if getattr(args, "out", None):
+        cfg.report.out_dir = args.out
+    if getattr(args, "format", None):
+        cfg.report.formats = args.format
+    return cfg
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.cmd is None:
+        build_parser().print_help()
+        return 2
+
+    if args.cmd == "init":
+        path = os.path.join(args.root, "reqcov.yml")
+        if os.path.exists(path) and not args.force:
+            print(f"{path} already exists (use --force to overwrite)", file=sys.stderr)
+            return 1
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(EXAMPLE_CONFIG)
+        print(f"wrote {path}")
+        return 0
+
+    cfg = _load(args)
+    report = analyze(cfg)
+
+    if args.cmd == "list":
+        for level, rows in report.by_level().items():
+            print(f"[{level}]")
+            for rc in rows:
+                r = rc.requirement
+                print(f"  {r.id:<12} {rc.verification_status:<10} {r.title[:70]}")
+        return 0
+
+    if not args.no_report:
+        written = write_reports(report, cfg)
+    else:
+        written = {}
+
+    if not args.quiet:
+        print(render_markdown(report))
+        for fmt, p in written.items():
+            print(f"[reqcov] wrote {fmt}: {p}")
+
+    # GitHub Actions integration: job summary + annotations
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary_path:
+        with open(summary_path, "a", encoding="utf-8") as fh:
+            fh.write(render_markdown(report))
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        for f in report.findings:
+            if f.severity == "info":
+                continue
+            level = "error" if f.severity == "error" else "warning"
+            loc = f" file={f.file}" + (f",line={f.line}" if f.line else "") if f.file else ""
+            print(f"::{level}{loc}::[{f.code}] {f.message}")
+        out = os.environ.get("GITHUB_OUTPUT")
+        if out:
+            with open(out, "a", encoding="utf-8") as fh:
+                fh.write(f"coverage={report.test_coverage_pct():.1f}\n")
+                fh.write(f"errors={len(report.errors)}\n")
+                fh.write(f"report_dir={os.path.join(cfg.root, cfg.report.out_dir)}\n")
+
+    if args.cmd == "check" and report.errors:
+        if not args.quiet:
+            print(f"[reqcov] FAILED with {len(report.errors)} error(s)", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

reqcov-0.1.0/reqcov/config.py

@@ -0,0 +1,121 @@
+"""Configuration loading (reqcov.yml)."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+DEFAULT_CONFIG_NAMES = ("reqcov.yml", "reqcov.yaml", ".reqcov.yml")
+
+DEFAULT_ID_PATTERN = r"[A-Z][A-Z0-9_]*-\d+"
+
+
+@dataclass
+class Rules:
+    min_test_coverage: float = 100.0  # % of testable requirements with >= 1 linked test
+    min_verified: Optional[float] = None  # % verified (needs JUnit); None = not enforced
+    fail_on_unknown_ids: bool = True
+    fail_on_orphan_tests: bool = False
+    fail_on_failing_tests: bool = True
+    require_parent_for: List[str] = field(default_factory=list)  # levels that must have a parent
+    require_source_for: List[str] = field(default_factory=list)  # levels that must have an implements link
+    allow_derived: bool = True  # if False, missing parent is an error instead of warning
+
+
+@dataclass
+class ReportConfig:
+    out_dir: str = "reqcov-report"
+    formats: List[str] = field(default_factory=lambda: ["html", "csv", "json", "md"])
+    title: str = "Requirements Traceability"
+    project: str = ""
+
+
+@dataclass
+class Config:
+    root: str = "."
+    id_pattern: str = DEFAULT_ID_PATTERN
+    requirements: List[str] = field(default_factory=lambda: ["docs/requirements/**/*.md", "docs/requirements/**/*.yml"])
+    sources: List[str] = field(default_factory=lambda: ["src/**/*"])
+    tests: List[str] = field(default_factory=lambda: ["tests/**/*", "test/**/*"])
+    junit: List[str] = field(default_factory=list)
+    exclude: List[str] = field(default_factory=lambda: ["**/node_modules/**", "**/.git/**", "**/build/**", "**/.venv/**"])
+    markers: List[str] = field(default_factory=lambda: ["req", "requirement", "requirements", "implements", "verifies", "satisfies", "trace", "traces"])
+    rules: Rules = field(default_factory=Rules)
+    report: ReportConfig = field(default_factory=ReportConfig)
+
+    @staticmethod
+    def load(path: Optional[str] = None, root: Optional[str] = None) -> "Config":
+        root = root or "."
+        data: Dict[str, Any] = {}
+        cfg_path = path
+        if cfg_path is None:
+            for name in DEFAULT_CONFIG_NAMES:
+                candidate = os.path.join(root, name)
+                if os.path.exists(candidate):
+                    cfg_path = candidate
+                    break
+        if cfg_path and os.path.exists(cfg_path):
+            with open(cfg_path, "r", encoding="utf-8") as fh:
+                data = yaml.safe_load(fh) or {}
+        return Config.from_dict(data, root=root)
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any], root: str = ".") -> "Config":
+        cfg = Config(root=root)
+        if "id_pattern" in data:
+            cfg.id_pattern = str(data["id_pattern"])
+        for key in ("requirements", "sources", "tests", "junit", "exclude", "markers"):
+            if key in data and data[key] is not None:
+                val = data[key]
+                if isinstance(val, str):
+                    val = [val]
+                # accept list of {path: ...} too
+                cfg.__dict__[key] = [v["path"] if isinstance(v, dict) else str(v) for v in val]
+        rules = data.get("rules") or {}
+        for k, v in rules.items():
+            if hasattr(cfg.rules, k):
+                setattr(cfg.rules, k, v)
+        rep = data.get("report") or {}
+        for k, v in rep.items():
+            if hasattr(cfg.report, k):
+                setattr(cfg.report, k, v)
+        return cfg
+
+
+EXAMPLE_CONFIG = """# reqcov configuration — see https://github.com/Antoine005/reqcov
+version: 1
+
+# Regex for requirement identifiers. Level = everything before the last dash (SYS, SRS, HLR, LLR...).
+id_pattern: "[A-Z][A-Z0-9_]*-\\\\d+"
+
+# Where requirements live (Markdown headings, YAML lists, or Doorstop items).
+requirements:
+  - docs/requirements/**/*.md
+  - docs/requirements/**/*.yml
+
+# Files scanned for `@implements REQ-1` style markers (traces to code).
+sources:
+  - src/**/*
+
+# Files scanned for `@req REQ-1` / `@verifies REQ-1` markers (traces to tests).
+tests:
+  - tests/**/*
+
+# Optional JUnit XML results: turns "covered" into "verified" / "failing".
+junit:
+  - reports/**/*.xml
+
+rules:
+  min_test_coverage: 100      # % of testable requirements that must have at least one test
+  fail_on_unknown_ids: true   # a marker references an id that does not exist
+  fail_on_orphan_tests: false # a test has no requirement marker
+  fail_on_failing_tests: true # a linked test failed (needs junit)
+  require_parent_for: [SRS]   # these levels must trace up to a parent requirement
+
+report:
+  out_dir: reqcov-report
+  formats: [html, csv, json, md]
+  title: "Software Requirements Traceability"
+"""