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

1"""Deterministic consensus grouping of findings across reviewers. 

2 

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""" 

8 

9from __future__ import annotations 

10 

11import re 

12from dataclasses import dataclass, field 

13 

14from .config import normalise_vendor 

15from .findings import SEVERITY_ORDER, Finding 

16 

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" 

24 

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 

30 

31 

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 = "" 

43 

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" 

49 

50 

51def _normalize_path(path, *, fold_case: bool = True) -> str: 

52 """Normalize a path for comparison. 

53 

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). 

58 

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 

73 

74 

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() 

79 

80 

81def _tokens(claim_norm: str) -> set[str]: 

82 return set(claim_norm.split()) 

83 

84 

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 

94 

95 

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 

104 

105 

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 

110 

111 

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 ) 

118 

119 

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" 

130 

131 

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 

138 

139 

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" 

143 

144 

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). 

149 

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 

173 

174 

175def _resolve_group_origin(members: list[Finding]) -> str: 

176 """Resolve origin across group members (issue #976). 

177 

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" 

188 

189 

190def group_findings(findings, reviewer_count: int) -> list[FindingGroup]: 

191 """Group findings that describe the same issue. 

192 

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. 

196 

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] = [] 

203 

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) 

221 

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)) 

236 

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