Coverage for src/ai_jury/consensus.py: 98%
119 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
1"""Deterministic consensus grouping of findings across reviewers.
3Groups findings that refer to the same underlying issue so the report can
4distinguish issues raised by every reviewer (consensus) from those raised by a
5single reviewer (single_reviewer). Grouping is fully deterministic: identical
6input always produces identical output.
7"""
9from __future__ import annotations
11import re
12from dataclasses import dataclass, field
14from .config import normalise_vendor
15from .findings import SEVERITY_ORDER, Finding
17# Buckets describing how broadly a finding was raised.
18BUCKET_CONSENSUS = "consensus"
19BUCKET_MAJORITY = "majority"
20BUCKET_SINGLE = "single_reviewer"
21# Verification-derived buckets (issue #3).
22BUCKET_REJECTED = "rejected"
23BUCKET_DISPUTED = "disputed"
25# Line proximity threshold: findings within this many lines are treated as the
26# same location (when both have a line).
27LINE_PROXIMITY = 3
28# Token-set Jaccard threshold for treating two claims as the same.
29JACCARD_THRESHOLD = 0.6
32@dataclass
33class FindingGroup:
34 representative: Finding
35 reviewers: list[str] = field(default_factory=list)
36 severity: str = "info"
37 members: list[Finding] = field(default_factory=list)
38 bucket: str = BUCKET_SINGLE
39 # Verification status (issue #3); empty until a verdict is attached.
40 status: str = ""
41 status_reasoning: str = ""
42 origin: str = ""
44 def __post_init__(self) -> None:
45 if self.members:
46 self.origin = _resolve_group_origin(self.members)
47 elif not self.origin: 47 ↛ exitline 47 didn't return from function '__post_init__' because the condition on line 47 was always true
48 self.origin = getattr(self.representative, "origin", "") or "unclear"
51def _normalize_path(path, *, fold_case: bool = True) -> str:
52 """Normalize a path for comparison.
54 Strips only a real leading ``./`` prefix — NOT ``str.lstrip("./")``, which
55 removes a whole leading run of ``.``/``/`` and collides distinct paths
56 (e.g. ``.github/x.yml`` vs ``github/x.yml``, ``../auth.py`` vs ``./auth.py``;
57 audit 2026-06-13 r5/M).
59 ``fold_case`` lower-cases the result, which is fine for *grouping/dedup*
60 (a finding's display location) but DANGEROUS for the CI gate: on a
61 case-sensitive filesystem ``Config.py`` and ``config.py`` are different
62 files, so a case-folded match would let a verifier ``unsupported`` verdict on
63 a benign sibling swallow a real critical and pass the gate (audit
64 2026-06-13 r6/M). ``orchestrator._verdict_matches_group`` therefore calls
65 this with ``fold_case=False`` (case-exact, fail-closed).
66 """
67 if not path:
68 return ""
69 p = str(path).strip().replace("\\", "/")
70 while p.startswith("./"):
71 p = p[2:]
72 return p.lower() if fold_case else p
75def _normalize_claim(claim) -> str:
76 text = (claim or "").lower()
77 text = re.sub(r"[^a-z0-9\s]+", " ", text)
78 return re.sub(r"\s+", " ", text).strip()
81def _tokens(claim_norm: str) -> set[str]:
82 return set(claim_norm.split())
85def _jaccard(a: set[str], b: set[str]) -> float:
86 if not a and not b:
87 return 1.0
88 if not a or not b:
89 return 0.0
90 inter = len(a & b)
91 # Bolt ⚡: calculate union size without allocating a new set
92 union = len(a) + len(b) - inter
93 return inter / union if union else 0.0
96def _same_location(a: Finding, b: Finding) -> bool:
97 if _normalize_path(a.file) != _normalize_path(b.file):
98 return False
99 if a.line is None and b.line is None:
100 return True
101 if a.line is None or b.line is None:
102 return False
103 return abs(a.line - b.line) <= LINE_PROXIMITY
106def _same_claim(a_norm: str, b_norm: str) -> bool:
107 if a_norm == b_norm:
108 return True
109 return _jaccard(_tokens(a_norm), _tokens(b_norm)) >= JACCARD_THRESHOLD
112def _sort_key(f: Finding):
113 return (
114 _normalize_path(f.file),
115 f.line if f.line is not None else -1,
116 _normalize_claim(f.claim),
117 )
120def _max_severity(findings) -> str:
121 # Lower SEVERITY_ORDER index == more severe.
122 best = None
123 best_rank = None
124 for f in findings:
125 rank = SEVERITY_ORDER.get(f.severity, len(SEVERITY_ORDER))
126 if best_rank is None or rank < best_rank:
127 best_rank = rank
128 best = f.severity
129 return best or "info"
132def _classify(reviewer_count: int, distinct_reviewers: int) -> str:
133 if reviewer_count > 0 and distinct_reviewers >= reviewer_count:
134 return BUCKET_CONSENSUS
135 if distinct_reviewers > 1:
136 return BUCKET_MAJORITY
137 return BUCKET_SINGLE
140# Severity a demoted group is capped at — below the default CI ``fail_on``
141# threshold (critical/major) so it stops blocking by default but still shows.
142_DEMOTED_SEVERITY = "minor"
145def demote_local_only_groups(
146 groups: list[FindingGroup], vendor_by_reviewer: dict[str, str]
147) -> None:
148 """Cap severity for a finding raised only by local/free-model reviewers (issue #442).
150 A numeric per-reviewer trust weight was rejected in favor of this categorical
151 rule: it is auditable in one line ("local-only finding, demoted unless a cloud
152 reviewer concurs"), where a coefficient invites silent drift. A group is
153 demoted only when EVERY contributing reviewer resolves to vendor ``"local"``;
154 a group with at least one cloud-vendor reviewer, or with no reviewers at all
155 (e.g. an injected finding), is left untouched. Mutates ``groups`` in place and
156 is idempotent — safe to call more than once on the same groups.
157 """
158 for group in groups:
159 if not group.reviewers:
160 continue
161 # Normalised, not compared raw: the mapping is built from configured
162 # vendors, and "which vendor is this" is one question with one answer
163 # everywhere (issue #701, round 3).
164 if not all(
165 normalise_vendor(vendor_by_reviewer.get(r, "")) == "local" for r in group.reviewers
166 ):
167 continue
168 if (
169 SEVERITY_ORDER.get(group.severity, len(SEVERITY_ORDER))
170 < SEVERITY_ORDER[_DEMOTED_SEVERITY]
171 ):
172 group.severity = _DEMOTED_SEVERITY
175def _resolve_group_origin(members: list[Finding]) -> str:
176 """Resolve origin across group members (issue #976).
178 A group is pre_existing only if every member says so; introduced if any says
179 introduced; otherwise unclear.
180 """
181 if not members: 181 ↛ 182line 181 didn't jump to line 182 because the condition on line 181 was never true
182 return "unclear"
183 if any(m.origin == "introduced" for m in members):
184 return "introduced"
185 if all(m.origin == "pre_existing" for m in members):
186 return "pre_existing"
187 return "unclear"
190def group_findings(findings, reviewer_count: int) -> list[FindingGroup]:
191 """Group findings that describe the same issue.
193 Findings match when they share a normalized file path, are within
194 ``LINE_PROXIMITY`` lines (or both have no line), and have an equal or
195 sufficiently similar (token-set Jaccard) normalized claim.
197 Deterministic: findings are sorted before greedy grouping, and the resulting
198 groups are returned in a stable order.
199 """
200 ordered = sorted(findings, key=_sort_key)
201 groups: list[FindingGroup] = []
202 group_claim_norms: list[str] = []
204 for finding in ordered:
205 f_claim = _normalize_claim(finding.claim)
206 placed = False
207 for idx, group in enumerate(groups):
208 rep = group.representative
209 if _same_location(finding, rep) and _same_claim(f_claim, group_claim_norms[idx]):
210 group.members.append(finding)
211 placed = True
212 break
213 if not placed:
214 groups.append(
215 FindingGroup(
216 representative=finding,
217 members=[finding],
218 )
219 )
220 group_claim_norms.append(f_claim)
222 for group in groups:
223 reviewers = sorted({m.reviewer for m in group.members if m.reviewer})
224 group.reviewers = reviewers
225 group.severity = _max_severity(group.members)
226 group.origin = _resolve_group_origin(group.members)
227 # Pick the most severe member as representative for display stability.
228 group.representative = min(
229 group.members,
230 key=lambda m: (
231 SEVERITY_ORDER.get(m.severity, len(SEVERITY_ORDER)),
232 _sort_key(m),
233 ),
234 )
235 group.bucket = _classify(reviewer_count, len(reviewers))
237 # Stable, deterministic output order: severity, then location, then claim.
238 groups.sort(
239 key=lambda g: (
240 SEVERITY_ORDER.get(g.severity, len(SEVERITY_ORDER)),
241 _normalize_path(g.representative.file),
242 g.representative.line if g.representative.line is not None else -1,
243 _normalize_claim(g.representative.claim),
244 )
245 )
246 return groups