reqcov 0.1.0__py3-none-any.whl

reqcov/__init__.py

@@ -0,0 +1,3 @@
+"""reqcov — requirements coverage for pull requests."""
+
+__version__ = "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/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"
+"""

reqcov/coverage.py

@@ -0,0 +1,149 @@
+"""Build the coverage model and evaluate rules."""
+from __future__ import annotations
+
+import datetime as _dt
+import subprocess
+from typing import Dict, List
+
+from .config import Config
+from .files import find_files
+from .junit import load_results, match_results
+from .links import scan_files
+from .models import CoverageReport, Finding, Reference, RequirementCoverage, TestResult
+from .requirements import load_requirements
+
+
+def _git_sha(root: str) -> str:
+    try:
+        return subprocess.check_output(["git", "rev-parse", "--short", "HEAD"], cwd=root, stderr=subprocess.DEVNULL, text=True).strip()
+    except Exception:  # pragma: no cover
+        return ""
+
+
+def analyze(cfg: Config) -> CoverageReport:
+    findings: List[Finding] = []
+    root = cfg.root
+
+    req_files = find_files(root, cfg.requirements, cfg.exclude)
+    if not req_files:
+        findings.append(Finding("error", "NO_REQUIREMENTS", f"no requirement files matched {cfg.requirements}"))
+    requirements = load_requirements(root, req_files, cfg.id_pattern, findings)
+
+    # don't scan requirement files themselves as sources/tests
+    src_files = [f for f in find_files(root, cfg.sources, cfg.exclude) if f not in req_files]
+    test_files = [f for f in find_files(root, cfg.tests, cfg.exclude) if f not in req_files]
+    src_set = set(src_files)
+    test_files = [f for f in test_files if f not in src_set]  # tests win over sources only if not both
+
+    refs = scan_files(root, test_files, "test", cfg.markers, cfg.id_pattern)
+    refs += scan_files(root, src_files, "source", cfg.markers, cfg.id_pattern)
+
+    # junit results often live under build/ — never apply the exclude list to them
+    results = load_results(root, find_files(root, cfg.junit, ())) if cfg.junit else []
+
+    cov: Dict[str, RequirementCoverage] = {rid: RequirementCoverage(requirement=r) for rid, r in requirements.items()}
+    unknown: List[Reference] = []
+    for ref in refs:
+        rc = cov.get(ref.req_id)
+        if rc is None:
+            unknown.append(ref)
+            continue
+        if ref.kind == "test":
+            rc.tests.append(ref)
+        else:
+            rc.sources.append(ref)
+
+    # parent / child relationships
+    for rc in cov.values():
+        for p in rc.requirement.parents:
+            if p in cov:
+                cov[p].children.append(rc.requirement.id)
+            else:
+                rc.unknown_parents.append(p)
+
+    # test results
+    matched_result_ids = set()
+    for rc in cov.values():
+        seen = set()
+        for t in rc.tests:
+            for res in match_results(t.symbol, t.file, results):
+                key = id(res)
+                if key not in seen:
+                    seen.add(key)
+                    rc.results.append(res)
+                    matched_result_ids.add(key)
+    referenced_symbols = {r.symbol.split(".")[-1] for r in refs if r.kind == "test" and r.symbol}
+    orphan_tests = [
+        r for r in results if id(r) not in matched_result_ids and r.name.split("[")[0] not in referenced_symbols
+    ]
+
+    report = CoverageReport(
+        requirements=cov,
+        references=refs,
+        results=results,
+        findings=findings,
+        unknown_ids=unknown,
+        orphan_tests=orphan_tests,
+        generated_at=_dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
+        git_sha=_git_sha(root),
+        title=cfg.report.title,
+    )
+    evaluate_rules(report, cfg)
+    return report
+
+
+def evaluate_rules(report: CoverageReport, cfg: Config) -> None:
+    rules = cfg.rules
+    f = report.findings
+
+    for ref in report.unknown_ids:
+        f.append(
+            Finding(
+                "error" if rules.fail_on_unknown_ids else "warning",
+                "UNKNOWN_ID",
+                f"{ref.req_id} referenced by {ref.symbol or 'marker'} but not defined",
+                ref.file,
+                ref.line,
+            )
+        )
+
+    for rc in report.requirements.values():
+        r = rc.requirement
+        for p in rc.unknown_parents:
+            f.append(Finding("error", "UNKNOWN_PARENT", f"{r.id} traces to undefined parent {p}", r.file, r.line))
+        if r.level in rules.require_parent_for and not r.parents and r.status != "obsolete":
+            sev = "warning" if rules.allow_derived else "error"
+            f.append(Finding(sev, "DERIVED", f"{r.id} has no parent requirement (derived?)", r.file, r.line))
+        if r.level in rules.require_source_for and not rc.sources and r.status != "obsolete":
+            f.append(Finding("error", "NO_SOURCE", f"{r.id} is not implemented by any source marker", r.file, r.line))
+        if r.verification == "test" and r.status != "obsolete" and not rc.tests:
+            f.append(Finding("warning", "UNCOVERED", f"{r.id} has no linked test", r.file, r.line))
+        if rc.verification_status == "failing":
+            failed = [t for t in rc.results if t.status in ("failed", "error")]
+            f.append(
+                Finding(
+                    "error" if rules.fail_on_failing_tests else "warning",
+                    "TEST_FAILED",
+                    f"{r.id}: {len(failed)} linked test(s) failed ({', '.join(t.name for t in failed[:3])})",
+                    r.file,
+                    r.line,
+                )
+            )
+
+    pct = report.test_coverage_pct()
+    if pct + 1e-9 < rules.min_test_coverage:
+        f.append(Finding("error", "COVERAGE", f"test coverage of requirements {pct:.1f}% is below the required {rules.min_test_coverage:.1f}%"))
+    if rules.min_verified is not None and report.results:
+        v = report.verified_pct()
+        if v + 1e-9 < rules.min_verified:
+            f.append(Finding("error", "VERIFIED", f"verified requirements {v:.1f}% is below the required {rules.min_verified:.1f}%"))
+
+    for t in report.orphan_tests:
+        f.append(
+            Finding(
+                "error" if rules.fail_on_orphan_tests else "info",
+                "ORPHAN_TEST",
+                f"test {t.full_name} is not linked to any requirement",
+                t.file,
+            )
+        )

reqcov/files.py

@@ -0,0 +1,38 @@
+"""File discovery helpers."""
+from __future__ import annotations
+
+import fnmatch
+import glob
+import os
+from typing import Iterable, List
+
+
+def _excluded(rel: str, exclude: Iterable[str]) -> bool:
+    rel_posix = rel.replace(os.sep, "/")
+    for pat in exclude:
+        if fnmatch.fnmatch(rel_posix, pat) or fnmatch.fnmatch("/" + rel_posix, pat):
+            return True
+        # also match directory components ("**/build/**" should exclude "build/x")
+        parts = rel_posix.split("/")
+        core = pat.replace("**/", "").replace("/**", "")
+        if core and core in parts:
+            return True
+    return False
+
+
+def find_files(root: str, patterns: Iterable[str], exclude: Iterable[str] = ()) -> List[str]:
+    """Return sorted, de-duplicated file paths relative to root matching any pattern."""
+    found = set()
+    for pat in patterns:
+        abs_pat = os.path.join(root, pat)
+        for p in glob.glob(abs_pat, recursive=True):
+            if os.path.isfile(p):
+                rel = os.path.relpath(p, root)
+                if not _excluded(rel, exclude):
+                    found.add(rel)
+    return sorted(found)
+
+
+def read_text(root: str, rel: str) -> str:
+    with open(os.path.join(root, rel), "r", encoding="utf-8", errors="replace") as fh:
+        return fh.read()

reqcov/junit.py

@@ -0,0 +1,63 @@
+"""JUnit XML parsing (pytest, Ceedling, GoogleTest, CTest, Jest, Maven... all emit it)."""
+from __future__ import annotations
+
+import os
+import xml.etree.ElementTree as ET
+from typing import List
+
+from .models import TestResult
+
+
+def parse_junit(path: str) -> List[TestResult]:
+    results: List[TestResult] = []
+    try:
+        tree = ET.parse(path)
+    except ET.ParseError:
+        return results
+    root = tree.getroot()
+    for case in root.iter("testcase"):
+        name = case.get("name", "")
+        classname = case.get("classname", "") or ""
+        file_attr = case.get("file", "") or ""
+        status = "passed"
+        message = ""
+        for child in case:
+            tag = child.tag.lower()
+            if tag == "failure":
+                status, message = "failed", (child.get("message") or (child.text or "")).strip()[:500]
+            elif tag == "error":
+                status, message = "error", (child.get("message") or (child.text or "")).strip()[:500]
+            elif tag == "skipped":
+                status, message = "skipped", (child.get("message") or "").strip()[:500]
+        # GoogleTest puts "Suite.Name" in classname/name; Ceedling uses "file.c" classnames.
+        results.append(TestResult(name=name, classname=classname, status=status, file=file_attr, message=message))
+    return results
+
+
+def load_results(root: str, files: List[str]) -> List[TestResult]:
+    out: List[TestResult] = []
+    for rel in files:
+        out.extend(parse_junit(os.path.join(root, rel)))
+    return out
+
+
+def match_results(symbol: str, file: str, results: List[TestResult]) -> List[TestResult]:
+    """Find results for a test symbol detected next to a marker.
+
+    Matching is name based: exact test name, ``Suite.Name`` for GoogleTest, or a
+    parametrised pytest id (``test_x[case]``). Ceedling reports ``classname`` as the
+    test file, so we also accept a file-stem match combined with the function name.
+    """
+    if not symbol:
+        return []
+    short = symbol.split(".")[-1]
+    hits: List[TestResult] = []
+    for r in results:
+        rname = r.name
+        base = rname.split("[")[0]
+        if base == short or rname == symbol or f"{r.classname}.{rname}" == symbol:
+            hits.append(r)
+            continue
+        if "." in symbol and r.classname.endswith(symbol.split(".")[0]) and base == short:
+            hits.append(r)
+    return hits

reqcov/links.py

@@ -0,0 +1,95 @@
+"""Scan source and test files for requirement markers.
+
+Recognised marker shapes (any language, inside comments, decorators, strings...)::
+
+    // @req SRS-001
+    # @req SRS-001, SRS-002
+    /* @verifies SRS-003 */
+    @pytest.mark.req("SRS-004")
+    @pytest.mark.req("SRS-004", "SRS-005")
+    // @implements SRS-006        (in source files -> code trace)
+    TEST_REQ(SRS-007)             (any token followed by ids works if the verb is configured)
+
+The verb list is configurable (``markers`` in reqcov.yml). Ids are matched with ``id_pattern``.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+
+from .files import read_text
+from .models import Reference
+
+_DEF_PATTERNS = [
+    re.compile(r"^\s*(?:async\s+)?def\s+(\w+)\s*\("),  # python
+    re.compile(r"^\s*TEST(?:_F|_P)?\s*\(\s*(\w+)\s*,\s*(\w+)\s*\)"),  # googletest
+    re.compile(r"^\s*(?:static\s+)?void\s+(test_?\w*)\s*\("),  # unity / ceedling
+    re.compile(r"^\s*(?:pub\s+)?(?:async\s+)?fn\s+(\w+)\s*[<(]"),  # rust
+    re.compile(r"^\s*(?:it|test|describe)\s*\(\s*['\"`](.+?)['\"`]"),  # js/ts
+    re.compile(r"^\s*(?:public\s+|private\s+)?(?:static\s+)?void\s+(\w+)\s*\("),  # java / c#
+    re.compile(r"^\s*func\s+(Test\w+)\s*\("),  # go
+    re.compile(r"^\s*(?:template\s*<[^>]*>\s*)?(?:class|struct)\s+(\w+)"),  # C++ class / struct
+    # generic C/C++ definition: `static uint16_t crc16(`, `frame_status_t frame_validate(`, `Foo::bar(`
+    re.compile(r"^\s*(?:(?:static|inline|extern|constexpr|virtual)\s+)*[A-Za-z_][\w:<>]*(?:\s*\*+\s*|\s+)\**([A-Za-z_]\w*(?:::\w+)?)\s*\("),
+]
+_KEYWORDS = {"return", "else", "if", "while", "for", "switch", "case", "sizeof", "new", "delete", "throw", "goto", "do"}
+
+
+def _symbol_from_line(line: str) -> Optional[str]:
+    for pat in _DEF_PATTERNS:
+        m = pat.match(line)
+        if m:
+            groups = [g for g in m.groups() if g]
+            if any(g in _KEYWORDS for g in groups) or line.lstrip().split(" ")[0] in _KEYWORDS:
+                continue
+            return ".".join(groups)
+    return None
+
+
+def _find_symbol(lines: List[str], idx: int) -> str:
+    # forward first (marker as decorator / leading comment)
+    for j in range(idx, min(len(lines), idx + 8)):
+        s = _symbol_from_line(lines[j])
+        if s:
+            return s
+    # then backwards (marker inside body)
+    for j in range(idx - 1, max(-1, idx - 60), -1):
+        s = _symbol_from_line(lines[j])
+        if s:
+            return s
+    return ""
+
+
+def build_marker_regex(markers: List[str], id_pattern: str) -> re.Pattern:
+    verbs = "|".join(re.escape(m) for m in sorted(markers, key=len, reverse=True))
+    # verb, optional punctuation, then a span that must start with an id
+    return re.compile(
+        r"(?<![A-Za-z0-9_])@?(?P<verb>" + verbs + r")\b\s*[:=(\[]?\s*(?P<span>[\"'`]?" + id_pattern + r".*)$",
+        re.IGNORECASE,
+    )
+
+
+def scan_files(root: str, files: List[str], kind: str, markers: List[str], id_pattern: str) -> List[Reference]:
+    marker_re = build_marker_regex(markers, id_pattern)
+    id_re = re.compile(id_pattern)
+    refs: List[Reference] = []
+    for rel in files:
+        try:
+            text = read_text(root, rel)
+        except (OSError, UnicodeDecodeError):
+            continue
+        if "\x00" in text[:4096]:  # binary
+            continue
+        lines = text.splitlines()
+        for i, line in enumerate(lines):
+            for m in marker_re.finditer(line):
+                span = m.group("span")
+                # cut the span at a closing bracket / comment end to avoid grabbing trailing prose ids
+                span = re.split(r"\*/|-->|\)\s*$", span)[0]
+                ids = id_re.findall(span)
+                if not ids:
+                    continue
+                symbol = _find_symbol(lines, i)
+                for rid in dict.fromkeys(ids):  # unique, ordered
+                    refs.append(Reference(req_id=rid, file=rel, line=i + 1, kind=kind, marker=m.group("verb").lower(), symbol=symbol))
+    return refs