reqthread 0.2.0__py3-none-any.whl

reqthread/gates.py

@@ -0,0 +1,138 @@
+"""Gate rules. Each gap carries a stable id so a build can be ratcheted against a baseline."""
+import datetime as dt
+from collections import defaultdict
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Gap:
+    rule: int
+    subject: str      # entity id the gap is about
+    qualifier: str    # distinguishes several gaps of one rule on one subject
+    message: str
+
+    @property
+    def id(self):
+        return f"rule{self.rule}:{self.subject}:{self.qualifier}"
+
+    def as_dict(self):
+        return {"id": self.id, "rule": self.rule, "subject": self.subject, "message": self.message}
+
+
+RULES = {
+    1: "Every software safety requirement has a verifying test at each declared test level.",
+    2: "Every software safety requirement derives from a system-level requirement.",
+    3: "Every code unit traces to a requirement or design element, or is marked infrastructure.",
+    4: "Every test verifying a safety requirement passed at baseline and failed nowhere.",
+    7: "Every static-analysis finding is fixed or covered by an unexpired deviation.",
+    11: "Every hazard is mitigated by at least one requirement, directly or through one of its causes.",
+    12: "Every cause is mitigated by a requirement, or its residual risk is formally accepted.",
+    13: "Every requirement that mitigates a hazard or cause is a safety requirement with an integrity level.",
+}
+
+
+def evaluate(bundle):
+    by_id = {e["id"]: e for e in bundle["entities"]}
+    out_links, in_links = defaultdict(list), defaultdict(list)
+    for l in bundle["links"]:
+        out_links[l["from"]].append(l)
+        in_links[l["to"]].append(l)
+
+    def ents(kind):
+        return [e for e in bundle["entities"] if e["kind"] == kind]
+
+    gaps = []
+    ssrs = [r for r in ents("requirement") if r["level"] in ("software", "derived") and r["status"] != "retired"]
+    ssr_ids = {r["id"] for r in ssrs}
+
+    # Rule 1
+    for r in ssrs:
+        if "test" not in r.get("verification", []):
+            continue
+        tests = [by_id[l["from"]] for l in in_links[r["id"]] if l["type"] == "verifies"]
+        for lvl in r.get("test_levels", []):
+            if not any(t["level"] == lvl for t in tests):
+                gaps.append(Gap(1, r["id"], lvl, f"{r['key']} has no verifying test at level '{lvl}'"))
+
+    # Rule 2
+    for r in ssrs:
+        parents = [by_id[l["to"]] for l in out_links[r["id"]] if l["type"] == "derives_from"]
+        ok = any(p["level"] == "system" for p in parents) if r["level"] == "software" else bool(parents)
+        if not ok:
+            want = "a system-level requirement" if r["level"] == "software" else "any requirement"
+            gaps.append(Gap(2, r["id"], "source", f"{r['key']} does not derive from {want}"))
+
+    # Rule 3 — a function is covered by its own trace, or by a file-level unit for the same path.
+    def traced(unit):
+        return unit["infrastructure"] is not None or any(
+            l["type"] in ("satisfies", "implements") for l in out_links[unit["id"]])
+
+    file_units = {u["path"]: u for u in ents("code_unit") if u["symbol"] is None}
+    for u in ents("code_unit"):
+        if traced(u):
+            continue
+        parent = file_units.get(u["path"]) if u["symbol"] is not None else None
+        if parent is not None and traced(parent):
+            continue
+        gaps.append(Gap(3, u["id"], "trace", f"{u['id'].removeprefix('code:')} traces to no requirement or design element"))
+
+    # Rule 4
+    results_by_test = defaultdict(list)
+    for res in ents("test_result"):
+        results_by_test[res["test"]].append(res)
+    verifying_tests = {l["from"] for l in bundle["links"] if l["type"] == "verifies" and l["to"] in ssr_ids}
+    for tid in sorted(verifying_tests):
+        verified = sorted({l["to"] for l in out_links[tid] if l["type"] == "verifies" and l["to"] in ssr_ids})
+        keys = ", ".join(by_id[v]["key"] for v in verified)
+        name = tid.removeprefix("test:")
+        results = results_by_test.get(tid, [])
+        for res in results:
+            if res["outcome"] in ("fail", "error"):
+                env = res["environment"]
+                gaps.append(Gap(4, tid, f"{env}:{res['outcome']}",
+                                f"{name} {res['outcome']}s on {env.removeprefix('env:')} (verifies {keys})"))
+        if not any(r["outcome"] == "pass" for r in results):
+            why = "only skipped" if results else "has no result"
+            gaps.append(Gap(4, tid, "not-passed", f"{name} {why} at baseline (verifies {keys})"))
+
+    # Rule 7
+    as_of = dt.datetime.fromisoformat(bundle["created_at"].replace("Z", "+00:00")).date()
+    for f in ents("finding"):
+        where = f"{f['location']['path']}:{f['location'].get('line', '?')}"
+        if f["state"] == "open":
+            gaps.append(Gap(7, f["id"], "open", f"{f['rule_id']} at {where} is open"))
+        elif f["state"] == "deviated":
+            devs = [by_id[l["from"]] for l in in_links[f["id"]] if l["type"] == "justifies"]
+            live = [d for d in devs if d["expires_at"] is None or dt.date.fromisoformat(d["expires_at"]) >= as_of]
+            if not live:
+                gaps.append(Gap(7, f["id"], "deviation", f"{f['rule_id']} at {where} has no unexpired deviation"))
+
+    # Rules 11-13: hazard analysis
+    live = lambda e: e["status"] != "retired"
+    hazards = [h for h in ents("hazard") if live(h)]
+    causes = [c for c in ents("cause") if live(c)]
+    mitigators = lambda eid: [by_id[l["from"]] for l in in_links[eid] if l["type"] == "mitigates" and live(by_id[l["from"]])]
+    cause_hazards = {c["id"]: [l["to"] for l in out_links[c["id"]] if l["type"] == "leads_to"] for c in causes}
+    for h in hazards:
+        direct = mitigators(h["id"])
+        via = [c for c in causes if h["id"] in cause_hazards[c["id"]] and (mitigators(c["id"]) or c["accepted"])]
+        if not direct and not via:
+            gaps.append(Gap(11, h["id"], "unmitigated", f"{h['key']} ({h['title']}) has no mitigating requirement"))
+    for c in causes:
+        if not mitigators(c["id"]) and not c["accepted"]:
+            gaps.append(Gap(12, c["id"], "unmitigated", f"{c['key']} ({c['title']}) has no mitigating requirement and no accepted-risk record"))
+    for r in ents("requirement"):
+        if live(r) and any(l["type"] == "mitigates" for l in out_links[r["id"]]) and not r.get("integrity_level"):
+            gaps.append(Gap(13, r["id"], "integrity", f"{r['key']} mitigates a hazard but has no integrity level"))
+
+    return sorted(gaps, key=lambda g: (g.rule, g.subject, g.qualifier))
+
+
+def ratchet(current, baseline):
+    """Split current gaps into (new, existing) relative to baseline gaps; also return fixed baseline gaps."""
+    base_ids = {g.id for g in baseline}
+    cur_ids = {g.id for g in current}
+    new = [g for g in current if g.id not in base_ids]
+    existing = [g for g in current if g.id in base_ids]
+    fixed = [g for g in baseline if g.id not in cur_ids]
+    return new, existing, fixed

reqthread/ingest.py

@@ -0,0 +1,221 @@
+"""Parsers for CI outputs: JUnit XML, lcov, Cobertura XML, SARIF."""
+import datetime as dt
+import json
+import pathlib
+import re
+import xml.etree.ElementTree as ET
+from collections import defaultdict
+from dataclasses import dataclass
+
+OUTCOME_RANK = {"error": 3, "fail": 2, "pass": 1, "skip": 0}
+
+
+# ------------------------------------------------------------------ paths
+
+def normalize_path(raw, repo_root, known_paths=()):
+    """Map a path reported by a tool to a repo-relative POSIX path, or None if it lies outside the repo."""
+    raw = raw.removeprefix("file://")
+    p = pathlib.PurePosixPath(raw)
+    root = pathlib.PurePosixPath(pathlib.Path(repo_root).resolve().as_posix())
+    if p.is_absolute():
+        try:
+            return p.relative_to(root).as_posix()
+        except ValueError:
+            for k in known_paths:   # tool ran in another checkout location
+                if raw.endswith("/" + k):
+                    return k
+            return None
+    rel = pathlib.PurePosixPath(*[part for part in p.parts if part != "."]).as_posix()
+    return None if rel.startswith("..") else rel
+
+
+# ------------------------------------------------------------------ JUnit
+
+@dataclass
+class JunitCase:
+    classname: str
+    name: str
+    outcome: str
+    timestamp: str | None
+
+
+def _iso_utc(ts):
+    if not ts:
+        return None
+    try:
+        t = dt.datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if t.tzinfo is None:
+        t = t.astimezone()   # naive timestamps from pytest are local time
+    return t.astimezone(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def parse_junit(path):
+    root = ET.parse(path).getroot()
+    suites = [root] if root.tag == "testsuite" else root.iter("testsuite")
+    cases = []
+    for suite in suites:
+        ts = _iso_utc(suite.get("timestamp"))
+        for tc in suite.findall("testcase"):
+            if tc.find("error") is not None:
+                outcome = "error"
+            elif tc.find("failure") is not None:
+                outcome = "fail"
+            elif tc.find("skipped") is not None:
+                outcome = "skip"
+            else:
+                outcome = "pass"
+            cases.append(JunitCase(tc.get("classname", ""), tc.get("name", ""), outcome, ts))
+    return cases
+
+
+def junit_match_keys(test_path, symbol):
+    """Keys a JUnit testcase may use for a test: pytest dotted module path, or the bare symbol."""
+    keys = {symbol}
+    if test_path.endswith(".py"):
+        module = test_path[:-3].replace("/", ".")
+        keys.add(f"{module}.{symbol}")
+    return keys
+
+
+def match_junit(cases, tests):
+    """tests: {test_entity_id: (path, symbol)}. Returns ({test_id: outcome}, unmatched_case_labels)."""
+    exact, by_last = defaultdict(set), defaultdict(set)
+    for tid, (path, symbol) in tests.items():
+        for k in junit_match_keys(path, symbol):
+            exact[k].add(tid)
+        by_last[symbol.rsplit(".", 1)[-1]].add(tid)
+
+    def only(candidates):
+        # Ambiguity is never resolved by guessing: crediting a result to the wrong test is worse than none.
+        return next(iter(candidates)) if len(candidates) == 1 else None
+
+    outcomes, unmatched = {}, []
+    for c in cases:
+        name = re.sub(r"\[.*\]$", "", c.name)   # pytest parametrisation
+        tid = only(exact.get(f"{c.classname}.{name}", set())) if c.classname else None
+        tid = tid or only(exact.get(name, set()))
+        if tid is None:
+            tid = only(by_last.get(re.split(r"\.|::", name)[-1], set()))
+        if tid is None:
+            unmatched.append(f"{c.classname}.{c.name}" if c.classname else c.name)
+            continue
+        prev = outcomes.get(tid)
+        if prev is None or OUTCOME_RANK[c.outcome] > OUTCOME_RANK[prev[0]]:   # error > fail > pass > skip
+            outcomes[tid] = (c.outcome, c.timestamp)
+    return outcomes, unmatched
+
+
+# ------------------------------------------------------------------ coverage
+
+@dataclass
+class FileCoverage:
+    lines: dict      # line -> hits
+    branches: dict   # line -> (covered, total)
+
+
+def parse_lcov(path, repo_root, known_paths=()):
+    files, current, unmapped = {}, None, []
+    for raw in pathlib.Path(path).read_text().splitlines():
+        if raw.startswith("SF:"):
+            rel = normalize_path(raw[3:], repo_root, known_paths)
+            if rel is None:
+                unmapped.append(raw[3:])
+            current = files.setdefault(rel, FileCoverage({}, {})) if rel else None
+        elif current is None:
+            continue
+        elif raw.startswith("DA:"):
+            line, hits = raw[3:].split(",")[:2]
+            current.lines[int(line)] = current.lines.get(int(line), 0) + int(hits)
+        elif raw.startswith("BRDA:"):
+            parts = raw[5:].split(",")
+            line, taken = parts[0], parts[-1]
+            cov, tot = current.branches.get(int(line), (0, 0))
+            current.branches[int(line)] = (cov + (taken not in ("-", "0")), tot + 1)
+    return files, unmapped
+
+
+def parse_cobertura(path, repo_root, known_paths=()):
+    root = ET.parse(path).getroot()
+    sources = [s.text.strip() for s in root.iter("source") if s.text and s.text.strip()] or [""]
+    files, unmapped = {}, []
+    for cls in root.iter("class"):
+        fname = cls.get("filename", "")
+        rel = None
+        for src in sources:
+            candidate = fname if not src or fname.startswith("/") else f"{src.rstrip('/')}/{fname}"
+            rel = normalize_path(candidate, repo_root, known_paths)
+            if rel:
+                break
+        if rel is None:
+            unmapped.append(fname)
+            continue
+        fc = files.setdefault(rel, FileCoverage({}, {}))
+        for ln in cls.iter("line"):
+            n = int(ln.get("number"))
+            fc.lines[n] = fc.lines.get(n, 0) + int(ln.get("hits", "0"))
+            m = re.search(r"\((\d+)/(\d+)\)", ln.get("condition-coverage", ""))
+            if ln.get("branch") == "true" and m:
+                fc.branches[n] = (int(m.group(1)), int(m.group(2)))
+    return files, unmapped
+
+
+def unit_metrics(fc, start, end):
+    """Statement and branch counts for one code unit's line range, or None if nothing instrumented."""
+    lines = [h for ln, h in fc.lines.items() if start <= ln <= end]
+    if not lines:
+        return None
+    metrics = {"statement": {"covered": sum(1 for h in lines if h > 0), "total": len(lines)}}
+    br = [v for ln, v in fc.branches.items() if start <= ln <= end]
+    if br:
+        metrics["branch"] = {"covered": sum(c for c, _ in br), "total": sum(t for _, t in br)}
+    return metrics
+
+
+# ------------------------------------------------------------------ SARIF
+
+@dataclass
+class SarifResult:
+    tool: str
+    tool_version: str | None
+    rule_id: str
+    message: str
+    path: str
+    line: int | None
+    level: str
+    fingerprint: str | None
+    suppressed_in_source: bool
+
+
+def parse_sarif(path, repo_root, known_paths=()):
+    doc = json.loads(pathlib.Path(path).read_text())
+    out, unmapped = [], []
+    for run in doc.get("runs", []):
+        driver = run.get("tool", {}).get("driver", {})
+        tool = driver.get("name", "unknown")
+        version = driver.get("semanticVersion") or driver.get("version")
+        rule_levels = {r.get("id"): r.get("defaultConfiguration", {}).get("level")
+                       for r in driver.get("rules", [])}
+        for r in run.get("results", []):
+            locs = r.get("locations") or [{}]
+            phys = locs[0].get("physicalLocation", {})
+            uri = phys.get("artifactLocation", {}).get("uri", "")
+            rel = normalize_path(uri, repo_root, known_paths) if uri else None
+            if rel is None:
+                unmapped.append(uri or "<no location>")
+                continue
+            rule_id = r.get("ruleId") or "unknown"
+            fps = r.get("partialFingerprints") or r.get("fingerprints") or {}
+            out.append(SarifResult(
+                tool=tool,
+                tool_version=version,
+                rule_id=rule_id,
+                message=(r.get("message") or {}).get("text", ""),
+                path=rel,
+                line=phys.get("region", {}).get("startLine"),
+                level=r.get("level") or rule_levels.get(rule_id) or "warning",
+                fingerprint=next(iter(sorted(fps.values())), None) if fps else None,
+                suppressed_in_source=bool(r.get("suppressions")),
+            ))
+    return out, unmapped

reqthread/report.py

@@ -0,0 +1,224 @@
+"""Self-contained static HTML report: gate result, traceability matrix, code units, findings, manifest."""
+from collections import defaultdict
+from html import escape
+
+from .gates import RULES
+
+CSS = """
+:root{--bg:#fbfaf7;--fg:#1d1d1b;--muted:#6b6862;--line:#e3dfd6;--card:#fff;--ok:#1f7a4a;--bad:#b42318;--warn:#a15c07;--chip:#f1eee6}
+@media (prefers-color-scheme:dark){:root{--bg:#161614;--fg:#ecebe6;--muted:#a3a097;--line:#34332f;--card:#1e1e1b;--ok:#4cc38a;--bad:#ff7b6b;--warn:#f0b35a;--chip:#2a2926}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:1200px;margin:0 auto;padding:24px 16px 64px}h1{font-size:22px;margin:0 0 4px}h2{font-size:16px;margin:32px 0 8px}
+.meta{color:var(--muted);font-size:13px}.meta code{font-size:12px}
+.banner{margin:20px 0;padding:14px 16px;border-radius:8px;border:1px solid var(--line);background:var(--card);display:flex;gap:16px;align-items:center;flex-wrap:wrap}
+.badge{font-weight:700;padding:3px 10px;border-radius:999px;color:#fff}.pass{background:var(--ok)}.fail{background:var(--bad)}
+.wrap{overflow-x:auto;border:1px solid var(--line);border-radius:8px;background:var(--card)}
+table{border-collapse:collapse;width:100%;min-width:760px;font-size:13px}th,td{text-align:left;padding:7px 10px;border-bottom:1px solid var(--line);vertical-align:top}
+th{font-weight:600;color:var(--muted);white-space:nowrap}tr:last-child td{border-bottom:0}
+code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px}
+.chip{display:inline-block;background:var(--chip);border-radius:4px;padding:0 6px;margin:1px 2px 1px 0;white-space:nowrap}
+.ok{color:var(--ok)}.bad{color:var(--bad)}.warn{color:var(--warn)}.muted{color:var(--muted)}.new{color:var(--bad);font-weight:600}
+ul.plain{margin:0;padding-left:18px}.nw{white-space:nowrap}
+"""
+
+
+def _e(s):
+    return escape(str(s), quote=True)
+
+
+def _short(eid):
+    return eid.split(":", 1)[1]
+
+
+def _pct(m):
+    if not m or not m["total"]:
+        return "—"
+    v = 100 * m["covered"] / m["total"]
+    cls = "ok" if m["covered"] == m["total"] else ("warn" if v >= 80 else "bad")
+    return f'<span class="nw"><span class="{cls}">{v:.0f}%</span> <span class="muted">{m["covered"]}/{m["total"]}</span></span>'
+
+
+def render(bundle, gaps, new_ids=None, fixed=None, warnings=None):
+    ents = {e["id"]: e for e in bundle["entities"]}
+    by_kind = defaultdict(list)
+    for e in bundle["entities"]:
+        by_kind[e["kind"]].append(e)
+    out_l, in_l = defaultdict(list), defaultdict(list)
+    for l in bundle["links"]:
+        out_l[l["from"]].append(l)
+        in_l[l["to"]].append(l)
+    results = defaultdict(list)
+    for r in by_kind["test_result"]:
+        results[r["test"]].append(r)
+    cov = defaultdict(list)
+    for c in by_kind["coverage_record"]:
+        cov[c["code_unit"]].append(c)
+
+    ratcheted = new_ids is not None
+    failing = [g for g in gaps if g.id in new_ids] if ratcheted else gaps
+    p, b = bundle["project"], bundle["baseline"]
+    h = []
+    h.append(f"<!doctype html><html lang='en'><head><meta charset='utf-8'><meta name='viewport' content='width=device-width,initial-scale=1'>"
+             f"<title>Traceability report</title><style>{CSS}</style></head><body><main>")
+    h.append(f"<h1>{_e(p['name'])}</h1>")
+    h.append(f"<div class='meta'>{_e(p['standard']['id'])} {_e(p['standard']['edition'])} · claim <b>{_e(p['integrity_claim'])}</b>"
+             f" · baseline <b>{_e(b['id'])}</b> · commit <code>{_e(b['commit'][:12])}</code>"
+             f" · generated {_e(bundle['created_at'])} by {_e(bundle['generator']['name'])} {_e(bundle['generator']['version'])}</div>")
+
+    status = "fail" if failing else "pass"
+    summary = f"{len(gaps)} gap(s)"
+    if ratcheted:
+        summary += f" — {len(failing)} new, {len(gaps) - len(failing)} carried from baseline, {len(fixed or [])} fixed"
+    h.append(f"<div class='banner'><span class='badge {status}'>{status.upper()}</span><span>{_e(summary)}</span></div>")
+
+    # Gaps
+    h.append("<h2>Gaps</h2>")
+    if gaps:
+        h.append("<div class='wrap'><table><tr><th>Rule</th><th>Gap</th>" + ("<th></th>" if ratcheted else "") + "</tr>")
+        for g in gaps:
+            tag = ""
+            if ratcheted:
+                tag = "<td class='new'>new</td>" if g.id in new_ids else "<td class='muted'>baseline</td>"
+            h.append(f"<tr><td title='{_e(RULES.get(g.rule, ''))}'>{g.rule}</td><td>{_e(g.message)}</td>{tag}</tr>")
+        h.append("</table></div>")
+    else:
+        h.append("<p class='ok'>No gaps.</p>")
+    if fixed:
+        h.append("<p class='muted'>Fixed since baseline: " + "; ".join(_e(g.message) for g in fixed) + "</p>")
+
+    # Requirements matrix
+    h.append("<h2>Requirements</h2><div class='wrap'><table><tr><th>Key</th><th>Title</th><th>Level · type</th><th>Integrity</th>"
+             "<th>Derives from</th><th>Design · code</th><th>Tests by level</th><th>Status</th></tr>")
+    level_rank = {"system": 0, "software": 1, "derived": 2}
+    for r in sorted(by_kind["requirement"], key=lambda r: (level_rank[r["level"]], r["key"])):
+        parents = [ents[l["to"]]["key"] for l in out_l[r["id"]] if l["type"] == "derives_from"]
+        impl = [l["from"] for l in in_l[r["id"]] if l["type"] == "satisfies"]
+        impl_html = " ".join(f"<span class='chip'>{_e(ents[i].get('key') or _short(i))}</span>" for i in sorted(impl)) or "<span class='muted'>—</span>"
+        tests = [ents[l["from"]] for l in in_l[r["id"]] if l["type"] == "verifies"]
+        cells = []
+        levels = list(dict.fromkeys(r.get("test_levels", []) + [t["level"] for t in tests]))
+        for lvl in levels:
+            at = [t for t in tests if t["level"] == lvl]
+            if not at:
+                cells.append(f"<div><b>{_e(lvl)}</b> <span class='bad'>missing</span></div>")
+                continue
+            items = []
+            for t in at:
+                outs = {x["outcome"] for x in results[t["id"]]}
+                if outs & {"fail", "error"}:
+                    mark = "<span class='bad'>✗ failed</span>"
+                elif "pass" in outs:
+                    envs = sorted(_short(x["environment"]) for x in results[t["id"]] if x["outcome"] == "pass")
+                    mark = f"<span class='ok'>✓</span> <span class='muted'>{_e(', '.join(envs))}</span>"
+                elif outs:
+                    mark = "<span class='warn'>○ skipped</span>"
+                else:
+                    mark = "<span class='warn'>○ not run</span>"
+                items.append(f"<li><code>{_e(t['name'].split('::')[-1])}</code> {mark}</li>")
+            cells.append(f"<div><b>{_e(lvl)}</b><ul class='plain'>{''.join(items)}</ul></div>")
+        tests_html = "".join(cells) or "<span class='muted'>—</span>"
+        h.append(f"<tr><td><b>{_e(r['key'])}</b></td><td>{_e(r['title'])}</td><td>{_e(r['level'])} · {_e(r['type'])}</td>"
+                 f"<td>{_e(r.get('integrity_level') or '—')}</td><td>{_e(', '.join(parents)) or '—'}</td>"
+                 f"<td>{impl_html}</td><td>{tests_html}</td><td>{_e(r['status'])}</td></tr>")
+    h.append("</table></div>")
+
+    # Code units
+    h.append("<h2>Code units</h2><div class='wrap'><table><tr><th>Unit</th><th>Traces to</th><th>Statement</th><th>Branch</th><th>Note</th></tr>")
+    def unit_targets(uid):
+        return sorted({ents[l["to"]].get("key", _short(l["to"])) for l in out_l[uid] if l["type"] in ("satisfies", "implements")})
+
+    file_units = {u["path"]: u for u in by_kind["code_unit"] if u["symbol"] is None}
+    for u in sorted(by_kind["code_unit"], key=lambda u: u["id"]):
+        targets = unit_targets(u["id"])
+        trace = " ".join(f"<span class='chip'>{_e(t)}</span>" for t in targets)
+        note = ""
+        parent = file_units.get(u["path"]) if u["symbol"] is not None else None
+        if u["infrastructure"]:
+            note = f"<span class='muted'>infrastructure: {_e(u['infrastructure']['reason'])}</span>"
+        elif not targets and parent is not None and (parent["infrastructure"] or unit_targets(parent["id"])):
+            trace = "<span class='muted'>via file</span>"
+            note = f"<span class='muted'>covered by the file-level annotation on {_e(u['path'])}</span>"
+        elif not targets:
+            trace = "<span class='bad'>untraced</span>"
+        stmt = br = "—"
+        if cov[u["id"]]:
+            c = cov[u["id"]][0]["metrics"]
+            stmt, br = _pct(c.get("statement")), _pct(c.get("branch"))
+        h.append(f"<tr><td><code>{_e(_short(u['id']))}</code></td><td>{trace or '—'}</td><td>{stmt}</td><td>{br}</td><td>{note}</td></tr>")
+    h.append("</table></div>")
+
+    # Hazards
+    if by_kind["hazard"] or by_kind["cause"]:
+        h.append("<h2>Hazard analysis</h2><div class='wrap'><table><tr><th>Hazard</th><th>Cause</th><th>Mitigated by</th><th>Verified</th></tr>")
+        def req_cell(rid):
+            r = ents[rid]
+            tests = [ents[l["from"]] for l in in_l[rid] if l["type"] == "verifies"]
+            if not tests:
+                return f"<span class='chip'>{_e(r['key'])}</span>", "<span class='bad'>no test</span>"
+            outs = {x["outcome"] for t in tests for x in results[t["id"]]}
+            mark = "<span class='ok'>✓</span>" if "pass" in outs and not outs & {"fail", "error"} else ("<span class='bad'>✗ failing</span>" if outs & {"fail", "error"} else "<span class='warn'>○ not run</span>")
+            return f"<span class='chip'>{_e(r['key'])}</span>", mark
+        for hz in sorted(by_kind["hazard"], key=lambda x: x["key"]):
+            direct = [l["from"] for l in in_l[hz["id"]] if l["type"] == "mitigates"]
+            cs = [ents[l["from"]] for l in in_l[hz["id"]] if l["type"] == "leads_to"]
+            rows_ = []
+            for rid in sorted(direct):
+                chip, mark = req_cell(rid); rows_.append(("<span class='muted'>(direct)</span>", chip, mark))
+            for c in sorted(cs, key=lambda x: x["key"]):
+                mits = sorted(l["from"] for l in in_l[c["id"]] if l["type"] == "mitigates")
+                label = f"<b>{_e(c['key'])}</b> {_e(c['title'])}"
+                if mits:
+                    for rid in mits:
+                        chip, mark = req_cell(rid); rows_.append((label, chip, mark))
+                elif c["accepted"]:
+                    rows_.append((label, f"<span class='muted'>risk accepted: {_e(c['accepted']['justification'])}</span>", "<span class='muted'>—</span>"))
+                else:
+                    rows_.append((label, "<span class='bad'>unmitigated</span>", "<span class='bad'>—</span>"))
+            if not rows_:
+                rows_.append(("<span class='muted'>—</span>", "<span class='bad'>unmitigated</span>", "<span class='bad'>—</span>"))
+            first = True
+            for label, chip, mark in rows_:
+                hcell = f"<td rowspan='{len(rows_)}'><b>{_e(hz['key'])}</b> {_e(hz['title'])}<div class='muted'>{_e(hz.get('severity') or '')}</div></td>" if first else ""
+                h.append(f"<tr>{hcell}<td>{label}</td><td>{chip}</td><td>{mark}</td></tr>"); first = False
+        h.append("</table></div>")
+
+    # Findings
+    h.append("<h2>Static analysis findings</h2>")
+    if by_kind["finding"]:
+        h.append("<div class='wrap'><table><tr><th>Rule</th><th>Location</th><th>Tool</th><th>State</th><th>Deviation</th></tr>")
+        for f in sorted(by_kind["finding"], key=lambda f: f["id"]):
+            devs = [ents[l["from"]] for l in in_l[f["id"]] if l["type"] == "justifies"]
+            dev_html = "<br>".join(f"<b>{_e(d['key'])}</b> {_e(d['justification'])} <span class='muted'>(expires {_e(d['expires_at'] or 'never')})</span>" for d in devs) or "—"
+            state_cls = "bad" if f["state"] == "open" else "muted"
+            loc = f"{f['location']['path']}:{f['location'].get('line', '?')}"
+            h.append(f"<tr><td><code>{_e(f['rule_id'])}</code><div class='muted'>{_e(f.get('message', ''))}</div></td><td><code>{_e(loc)}</code></td>"
+                     f"<td>{_e(ents[f['tool']]['name'])}</td><td class='{state_cls}'>{_e(f['state'])}</td><td>{dev_html}</td></tr>")
+        h.append("</table></div>")
+    else:
+        h.append("<p class='muted'>None ingested.</p>")
+
+    # Tools and pre-existing software
+    h.append("<h2>Tools</h2><div class='wrap'><table><tr><th>Tool</th><th>Version</th><th>Class</th><th>Evidence</th></tr>")
+    for t in sorted(by_kind["tool"], key=lambda t: t["name"].lower()):
+        cls = _e(t["class"]) if t["class"] else "<span class='warn'>unclassified</span>"
+        h.append(f"<tr><td>{_e(t['name'])}</td><td><code>{_e(t['version'])}</code></td><td>{cls}</td><td>{_e(', '.join(t.get('evidence', []))) or '—'}</td></tr>")
+    h.append("</table></div>")
+    if by_kind["preexisting_element"]:
+        h.append("<h2>Pre-existing software</h2><div class='wrap'><table><tr><th>Element</th><th>Version</th><th>Route</th><th>Justification</th></tr>")
+        for x in by_kind["preexisting_element"]:
+            route = _e(x["route"]) if x["route"] else "<span class='warn'>not routed</span>"
+            h.append(f"<tr><td>{_e(x['name'])}</td><td><code>{_e(x['version'])}</code></td><td>{route}</td><td>{_e(', '.join(x.get('justification', []))) or '—'}</td></tr>")
+        h.append("</table></div>")
+
+    # Manifest
+    h.append("<h2>Artifact manifest</h2><div class='wrap'><table><tr><th>Path</th><th>Section</th><th>sha256</th></tr>")
+    for a in bundle["artifacts"]:
+        h.append(f"<tr><td><code>{_e(a['path'])}</code></td><td>{_e(a['section'])}</td><td><code>{_e(a['hash'][7:23])}…</code></td></tr>")
+    h.append("</table></div>")
+    if b.get("previous_bundle_hash"):
+        h.append(f"<p class='meta'>Chained to previous bundle <code>{_e(b['previous_bundle_hash'])}</code></p>")
+
+    if warnings:
+        h.append("<h2>Build warnings</h2><ul>" + "".join(f"<li class='warn'>{_e(w)}</li>" for w in warnings) + "</ul>")
+    h.append("</main></body></html>")
+    return "\n".join(h)