feat(three-stage-scan): report map and honor fail-on worth-fixing

src/openultrasast/cli.py

@@ -28,6 +28,7 @@ from .calibration import (
     write_ranking_calibrations,
 )
 from .complexity import map as complexity_map
+from .complexity.ledger import persist_verdicts
 from .config import load_config
 from .findings import StaticFinding, quick_scan_findings, write_findings
 from .fusion import FusionDecision, fuse_findings_dispatch
@@ -42,7 +43,7 @@ from .mapping import analyze_entry_points, attach_reachability_hints, ingest_sar
 from .policy import assert_rules_resolve, load_policy
 from .preprocess import preprocess_repository, write_preprocess_artifact
 from .rank import rank_targets, write_rankings
-from .regress import run_regression, write_verdicts
+from .regress import CandidateVerdict, run_regression, write_verdicts
 from .reports import scan_exit_code, write_manifest, write_markdown_report, write_sarif_report
 from .ruleset import DEFAULT_RULESET_DIR, load_ruleset
 from .run import ScanRun, create_scan_run
@@ -341,6 +342,7 @@ def _run_scan(path: Path, config_path: Path, mode: str, fail_on: str) -> ScanOut
         }
     verdicts_path = run.root / "verdicts.json"
     wrote_verdicts = False
+    verdict_records: tuple[CandidateVerdict, ...] = ()
     if Stage.REGRESS in plan.requested:
         probe = resolve_sandbox_probe()
         if not probe.available():
@@ -368,10 +370,21 @@ def _run_scan(path: Path, config_path: Path, mode: str, fail_on: str) -> ScanOut
                 ),
             )
             write_verdicts(records, verdicts_path)
+            persist_verdicts(run.target / CALIBRATION_DIR / "complexity_ledger.json", records)
+            verdict_records = records
             wrote_verdicts = True
             plan = record_completed(plan, Stage.REGRESS)
+    worth_fixing_payload = _worth_fixing_payload(verdict_records) if wrote_verdicts else None
     runtime.run_stage(
-        "report", lambda: write_markdown_report(findings, markdown_path, verifications, redact=config.hardening.redact_secrets)
+        "report",
+        lambda: write_markdown_report(
+            findings,
+            markdown_path,
+            verifications,
+            redact=config.hardening.redact_secrets,
+            complexity_map=built_map,
+            verdicts=verdict_records if wrote_verdicts else None,
+        ),
     )
     runtime.run_stage("sarif", lambda: write_sarif_report(findings, verifications, sarif_path))
     runtime.run_stage(
@@ -397,6 +410,7 @@ def _run_scan(path: Path, config_path: Path, mode: str, fail_on: str) -> ScanOut
             fusion=[_fusion_summary(decision) for decision in fusion_decisions] or None,
             stages=stages_payload(plan),
             complexity=complexity_payload,
+            worth_fixing=worth_fixing_payload,
         ),
     )
     runtime.finish(status="succeeded")
@@ -407,7 +421,7 @@ def _run_scan(path: Path, config_path: Path, mode: str, fail_on: str) -> ScanOut
         ranked_target_count=len(rankings),
         finding_count=len(findings),
         calibrations_applied=len(applied_calibrations),
-        exit_code=scan_exit_code(findings, verifications, fail_on),
+        exit_code=scan_exit_code(findings, verifications, fail_on, worth_fixing_verdicts=verdict_records),
     )
 
 
@@ -493,6 +507,23 @@ def _load_static_hints(sarif_paths: tuple[str, ...]) -> list[object]:
     return hints
 
 
+def _worth_fixing_payload(verdicts: tuple[CandidateVerdict, ...]) -> dict[str, object]:
+    worth = [record for record in verdicts if record.worth_fixing]
+    return {
+        "count": len(worth),
+        "verdicts": [
+            {
+                "path": record.path,
+                "function_name": record.function_name,
+                "verdict": record.verdict,
+                "reason": record.reason,
+                "worth_fixing": True,
+            }
+            for record in worth
+        ],
+    }
+
+
 def _artifact_paths(**paths: Path | None) -> dict[str, Path]:
     return {name: path for name, path in paths.items() if path is not None}
 

src/openultrasast/complexity/__init__.py

@@ -7,6 +7,7 @@ from .ledger import (
     hotspot_key,
     load_ledger,
     must_keep_as_candidate,
+    persist_verdicts,
     record_verdict,
     select_forced_candidates,
     write_ledger,
@@ -27,6 +28,7 @@ __all__ = [
     "hotspot_key",
     "load_ledger",
     "must_keep_as_candidate",
+    "persist_verdicts",
     "record_verdict",
     "select_forced_candidates",
     "write_complexity_map",

src/openultrasast/complexity/hints.py

@@ -35,6 +35,7 @@ class TestHint:
     gap: str  # no_adjacent_test | no_function_reference | no_fuzz_entry | covered
     test_kind: str | None
     reason: str
+    __test__ = False
 
     def __post_init__(self) -> None:
         if self.gap not in GAPS:

src/openultrasast/complexity/ledger.py

@@ -57,6 +57,27 @@ def write_ledger(path: Path, ledger: Mapping[str, LedgerEntry | Mapping[str, obj
     path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
 
 
+def persist_verdicts(path: Path, verdicts: Sequence[object]) -> dict[str, LedgerEntry]:
+    """Record triggerable / not_triggerable outcomes into the loop-owned complexity ledger."""
+    ledger = load_ledger(path)
+    changed = False
+    for item in verdicts:
+        verdict = str(getattr(item, "verdict", ""))
+        if verdict not in VERDICT_DELTAS:
+            continue
+        raw_function = getattr(item, "function_name", None)
+        ledger = record_verdict(
+            ledger,
+            path=str(getattr(item, "path", "")),
+            function_name=raw_function if isinstance(raw_function, str) else None,
+            verdict=verdict,
+        )
+        changed = True
+    if changed:
+        write_ledger(path, ledger)
+    return ledger
+
+
 def record_verdict(
     ledger: Mapping[str, LedgerEntry | Mapping[str, object]],
     *,

src/openultrasast/regress/candidate.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 from collections.abc import Mapping, Sequence
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, replace
 from pathlib import Path
 
 from ..complexity.ledger import hotspot_key, select_forced_candidates
@@ -200,6 +200,7 @@ def run_regression(
         image = images.get(language) or DEFAULT_IMAGES.get(language, "ousast-missing-image")
         mapped = runner.run_recipe(language, snippet, image, sandbox_limits, repo_root=repo_root)
         reachability = _reachability_for(hotspot, findings_by_id)
+        mapped = replace(mapped, worth_fixing=is_worth_fixing(mapped.verdict, reachability))
         records.append(
             CandidateVerdict(
                 path=hotspot.path,
@@ -208,7 +209,7 @@ def run_regression(
                 verdict=mapped.verdict,
                 reason=mapped.reason,
                 inventory_finding_ids=hotspot.inventory_finding_ids,
-                worth_fixing=is_worth_fixing(mapped.verdict, reachability),
+                worth_fixing=mapped.worth_fixing,
             )
         )
     return tuple(records)

src/openultrasast/regress/verdict.py

@@ -50,6 +50,7 @@ _CRASH_MARKERS = (
 class RegressionVerdict:
     verdict: str
     reason: str = ""
+    worth_fixing: bool = False
 
 
 def is_worth_fixing(verdict: str, reachability: str) -> bool:

src/openultrasast/reports.py

@@ -11,13 +11,20 @@ from .verification import VerificationResult
 
 
 def write_markdown_report(
-    findings: list[StaticFinding], path: Path, verifications: list[VerificationResult] | None = None, *, redact: bool = True
+    findings: list[StaticFinding],
+    path: Path,
+    verifications: list[VerificationResult] | None = None,
+    *,
+    redact: bool = True,
+    complexity_map: object | None = None,
+    verdicts: Sequence[object] | None = None,
 ) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     verification_by_id = _verification_by_id(verifications or [])
     lines = ["# OpenUltraSAST Report", "", f"Findings: {len(findings)}", "", "## Inventory", ""]
     if not findings:
         lines.append("No quick-mode findings were emitted.")
+        lines.append("")
     for finding in findings:
         verification = verification_by_id.get(finding.finding_id)
         lines.extend(
@@ -41,6 +48,10 @@ def write_markdown_report(
                 "",
             ]
         )
+    if complexity_map is not None:
+        _append_complexity_map(lines, complexity_map)
+    if verdicts is not None:
+        _append_worth_fixing(lines, verdicts)
     report = "\n".join(lines).rstrip() + "\n"
     if redact:
         from .redaction import redact_secrets
@@ -49,6 +60,68 @@ def write_markdown_report(
     path.write_text(report)
 
 
+def _append_complexity_map(lines: list[str], complexity_map: object) -> None:
+    hotspots = tuple(getattr(complexity_map, "hotspots", ()) or ())
+    heuristic_only = getattr(complexity_map, "heuristic_only", None)
+    summary = f"Hotspots: {len(hotspots)}"
+    if heuristic_only is not None:
+        summary += f" (heuristic_only={str(bool(heuristic_only)).lower()})"
+    lines.extend(["## Complexity map", "", summary, ""])
+    if not hotspots:
+        lines.extend(["No complexity hotspots were emitted.", ""])
+        return
+    for hotspot in hotspots:
+        identity = _report_identity(getattr(hotspot, "path", ""), getattr(hotspot, "function_name", None))
+        lines.extend(
+            [
+                f"### `{identity}`",
+                "",
+                f"- Score: `{getattr(hotspot, 'score', '')}`",
+                f"- Band: `{getattr(hotspot, 'band', '')}`",
+            ]
+        )
+        hint = getattr(hotspot, "test_hint", None)
+        if hint is not None:
+            lines.append(f"- Gap: `{getattr(hint, 'gap', '')}`")
+            kind = getattr(hint, "test_kind", None)
+            if kind:
+                lines.append(f"- Recommended test: `{kind}`")
+            reason = getattr(hint, "reason", "")
+            if reason:
+                lines.append(f"- Hint: {reason}")
+        inventory_ids = tuple(getattr(hotspot, "inventory_finding_ids", ()) or ())
+        if inventory_ids:
+            lines.append(f"- Inventory: `{', '.join(str(item) for item in inventory_ids)}`")
+        rationale = str(getattr(hotspot, "rationale", "") or "")
+        lines.extend(["", rationale, ""] if rationale else [""])
+
+
+def _append_worth_fixing(lines: list[str], verdicts: Sequence[object]) -> None:
+    worth = [item for item in verdicts if getattr(item, "worth_fixing", False)]
+    lines.extend(["## Worth fixing", "", f"Count: {len(worth)}", ""])
+    if not worth:
+        lines.extend(["No worth-fixing verdicts were produced.", ""])
+        return
+    for item in worth:
+        identity = _report_identity(getattr(item, "path", ""), getattr(item, "function_name", None))
+        lines.extend(
+            [
+                f"### `{identity}`",
+                "",
+                f"- Verdict: `{getattr(item, 'verdict', '')}`",
+                f"- Reason: `{getattr(item, 'reason', '')}`",
+                "",
+            ]
+        )
+
+
+def _report_identity(path: object, function_name: object) -> str:
+    path_text = str(path or "")
+    if function_name:
+        return f"{path_text}::{function_name}"
+    return path_text
+
+
 def write_sarif_report(findings: list[StaticFinding], verifications: list[VerificationResult], path: Path) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     verification_by_id = _verification_by_id(verifications)
@@ -84,6 +157,7 @@ def write_manifest(
     fusion: list[dict[str, object]] | None = None,
     stages: dict[str, object] | None = None,
     complexity: dict[str, object] | None = None,
+    worth_fixing: dict[str, object] | None = None,
 ) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     verification_by_id = _verification_by_id(verifications)
@@ -116,6 +190,8 @@ def write_manifest(
         payload["stages"] = stages
     if complexity is not None:
         payload["complexity"] = complexity
+    if worth_fixing is not None:
+        payload["worth_fixing"] = worth_fixing
     path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")