Coverage for src/governed_harness/review/project.py: 92%

160 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""The review panel of one project: its settings, catalog, reviewers, routing, consistency checks 

2and linters (#57). Shared by INDEPENDENT_REVIEW and ``harness review-code``.""" 

3 

4from __future__ import annotations 

5 

6from collections.abc import Callable 

7from dataclasses import dataclass, replace 

8from pathlib import Path 

9from typing import Any 

10 

11from governed_harness.agents.routing import ( 

12 RoutingDecision, 

13 flags_for, 

14 invoking_model, 

15 provider_family, 

16 select_reviewer, 

17) 

18from governed_harness.capabilities import grants_from_rules 

19from governed_harness.configuration.models import ResolvedConfiguration 

20from governed_harness.configuration.review import ReviewPanelConfig 

21from governed_harness.domain.enums import ActorType, ResultStatus 

22from governed_harness.domain.models import Actor 

23from governed_harness.review.checks import CHECKS 

24from governed_harness.review.contract import ReviewFinding 

25from governed_harness.review.diff import Locations 

26from governed_harness.review.panel import Route 

27from governed_harness.review.reviewers import Reviewer, load_reviewers, reviewer_domains 

28from governed_harness.review.rules import ( 

29 HARNESS_TOOL, 

30 Catalog, 

31 InactiveRule, 

32 Rule, 

33 builtin_rules, 

34 configured_tools, 

35 merge, 

36 pack_rules, 

37 project_rules, 

38) 

39from governed_harness.runtime import CancellationToken 

40from governed_harness.runtime.process_runner import CommandSpec, ProcessResult, SafeProcessRunner 

41from governed_harness.standards import PackTool, ProjectStandards, project_standards 

42 

43CONSISTENCY_ACTOR = Actor( 

44 actor_type=ActorType.TOOL, actor_id="validator.review.consistency", version="1" 

45) 

46TOOLS_ACTOR = Actor(actor_type=ActorType.TOOL, actor_id="validator.review.tools", version="1") 

47_OUTPUT_TAIL = 2000 

48 

49 

50@dataclass(frozen=True) 

51class ReviewSetup: 

52 settings: ReviewPanelConfig 

53 catalog: Catalog 

54 reviewers: list[Reviewer] 

55 standards: ProjectStandards | None 

56 tools: frozenset[str] 

57 

58 @property 

59 def packs(self) -> tuple[str, ...]: 

60 return tuple(item.pack_id for item in self.standards.packs) if self.standards else () 

61 

62 

63def panel_settings(resolved: ResolvedConfiguration) -> ReviewPanelConfig: 

64 review = resolved.project.review 

65 return (review.panel if review is not None else None) or ReviewPanelConfig() 

66 

67 

68def _standards(resolved: ResolvedConfiguration, workspace: Path) -> ProjectStandards | None: 

69 config = resolved.project.standards 

70 technologies = tuple(item.technology for item in resolved.profiles) 

71 if config is not None: 

72 return project_standards( 

73 workspace, 

74 packs=config.packs, 

75 overrides=config.overrides_path, 

76 disabled=config.disabled or (), 

77 technologies=technologies, 

78 ) 

79 return project_standards(workspace, packs=None, overrides=None, technologies=technologies) 

80 

81 

82def review_setup(resolved: ResolvedConfiguration, workspace: Path | None = None) -> ReviewSetup: 

83 workspace = workspace or resolved.workspace_root 

84 settings = panel_settings(resolved) 

85 standards = _standards(resolved, workspace) 

86 tools = configured_tools( 

87 standards, workspace, [item.validator_id for item in resolved.effective_validators] 

88 ) 

89 layers: list[Rule] = [*builtin_rules()] 

90 if standards is not None: 90 ↛ 92line 90 didn't jump to line 92 because the condition on line 90 was always true

91 layers.extend(pack_rules(standards.packs)) 

92 layers.extend(project_rules(workspace)) 

93 catalog = merge( 

94 layers, 

95 available_tools=tools, 

96 reviewer_domains=reviewer_domains(workspace, settings.reviewers), 

97 workspace=workspace, 

98 ) 

99 catalog = _known_checks(catalog) 

100 if resolved.effective_policies.get("repositoryContentTrusted") is True: 

101 catalog = _trusted_content(catalog) 

102 reviewers = load_reviewers(workspace, catalog, enabled=settings.reviewers) 

103 return ReviewSetup(settings, catalog, reviewers, standards, frozenset(tools)) 

104 

105 

106def _known_checks(catalog: Catalog) -> Catalog: 

107 """A rule naming a harness check that does not exist is inactive, never silently passed.""" 

108 active: list[Rule] = [] 

109 inactive = list(catalog.inactive) 

110 for rule in catalog.rules: 

111 unknown = [name for tool, name in rule.tools if tool == HARNESS_TOOL and name not in CHECKS] 

112 if unknown: 112 ↛ 113line 112 didn't jump to line 113 because the condition on line 112 was never true

113 inactive.append(InactiveRule(rule, f"unknown harness check {unknown[0]}")) 

114 else: 

115 active.append(rule) 

116 return Catalog(tuple(active), tuple(sorted(inactive, key=lambda item: item.rule.rule_id))) 

117 

118 

119def _trusted_content(catalog: Catalog) -> Catalog: 

120 """Under ``policies.repositoryContentTrusted: true`` (#5) instructions in changed content 

121 are not flagged.""" 

122 active: list[Rule] = [] 

123 inactive = list(catalog.inactive) 

124 for rule in catalog.rules: 

125 if (HARNESS_TOOL, "embedded-instructions") in rule.tools: 

126 inactive.append( 

127 InactiveRule( 

128 rule, "repository content is trusted (policies.repositoryContentTrusted)" 

129 ) 

130 ) 

131 else: 

132 active.append(rule) 

133 return Catalog(tuple(active), tuple(sorted(inactive, key=lambda item: item.rule.rule_id))) 

134 

135 

136def panel_context( 

137 resolved: ResolvedConfiguration, workspace: Path 

138) -> tuple[dict[str, Any], str | None]: 

139 """What ``governance.applyRepositoryPolicies`` adds to every reviewer request (#5): the 

140 names of the instruction files as untrusted context and the prompt-injection notice.""" 

141 from governed_harness.capabilities.repository import ( 

142 UNTRUSTED_NOTICE, 

143 repository_policies, 

144 untrusted_context, 

145 ) 

146 

147 policies = repository_policies(resolved) 

148 if not policies.untrusted: 

149 return {}, None 

150 context = untrusted_context(workspace, policies.instruction_files, include_content=False) 

151 return {"untrustedContent": context}, UNTRUSTED_NOTICE 

152 

153 

154RouteObserver = Callable[[Reviewer, str, RoutingDecision], None] 

155"""Hears the routing decision of a reviewer on a provider (#85: recorded per call).""" 

156 

157 

158def reviewer_route(resolved: ResolvedConfiguration, observer: RouteObserver | None = None) -> Route: 

159 """The model and effort of a reviewer on a provider: the reviewer's own ``models`` entry 

160 (provider id or family) and ``effort``, else the routing table (``reviewers``, ``review``) 

161 under ``agentRouting: tiered`` (capped at the invoking model under ``anchored``, #85), else 

162 the provider's default. ``observer`` hears every decision.""" 

163 project = resolved.project 

164 policy = project.agent_routing 

165 

166 def route(reviewer: Reviewer, provider_id: str) -> tuple[str | None, str | None]: 

167 configured = project.agent_providers.get(provider_id) 

168 command = (*(configured.command or ()), configured.kind) if configured else () 

169 family = provider_family(provider_id, command, policy.families if policy else None) 

170 decision = select_reviewer( 

171 reviewer.reviewer_id, 

172 policy, 

173 family=family, 

174 anchor=invoking_model(project, provider_id), 

175 ) 

176 model = reviewer.model_for(provider_id, family) 

177 effort = reviewer.spec.effort 

178 if model is not None: 178 ↛ 180line 178 didn't jump to line 180 because the condition on line 178 was never true

179 # The reviewer's own model wins over the tables, as a call's own setting does. 

180 decision = replace( 

181 decision, 

182 rule=f"reviewer:{reviewer.reviewer_id}", 

183 model=model, 

184 effort=effort, 

185 rung=None, 

186 flags=flags_for(family, model, effort), 

187 ) 

188 elif effort is not None: 188 ↛ 192line 188 didn't jump to line 192 because the condition on line 188 was always true

189 decision = replace( 

190 decision, effort=effort, flags=flags_for(family, decision.model, effort) 

191 ) 

192 if observer is not None: 

193 observer(reviewer, provider_id, decision) 

194 return decision.model, decision.effort 

195 

196 return route 

197 

198 

199def consistency_runner( 

200 resolved: ResolvedConfiguration, 

201 workspace: Path, 

202 runner: SafeProcessRunner, 

203 *, 

204 execution_id: str, 

205 cancelled: Callable[[], bool] = lambda: False, 

206) -> Callable[[], list[dict[str, Any]]] | None: 

207 """The project's consistency checks (``review.panel.consistencyChecks``), run before any 

208 reviewer with the project's capability grants; ``None`` without any.""" 

209 checks = panel_settings(resolved).consistency_checks or () 

210 if not checks: 

211 return None 

212 

213 def run() -> list[dict[str, Any]]: 

214 grants = grants_from_rules(execution_id, CONSISTENCY_ACTOR, resolved.effective_capabilities) 

215 results: list[dict[str, Any]] = [] 

216 for check in checks: 

217 try: 

218 outcome = runner.run( 

219 CommandSpec( 

220 argv=check.command, 

221 cwd=workspace, 

222 timeout_seconds=float(check.timeout_seconds or 300), 

223 max_output_bytes=resolved.project.runtime.max_output_bytes, 

224 ), 

225 actor=CONSISTENCY_ACTOR, 

226 grants=grants, 

227 cancellation=CancellationToken(cancelled), 

228 ) 

229 except (OSError, ValueError) as error: 

230 results.append({"id": check.check_id, "status": "BLOCKED", "summary": f"{error}"}) 

231 continue 

232 tail = (outcome.stdout + outcome.stderr).decode("utf-8", "replace")[-_OUTPUT_TAIL:] 

233 results.append( 

234 { 

235 "id": check.check_id, 

236 "status": "PASSED" if outcome.status is ResultStatus.PASSED else "FAILED", 

237 "exitCode": outcome.exit_code, 

238 "command": list(check.command), 

239 "summary": " ".join(tail.split())[-500:], 

240 } 

241 ) 

242 return results 

243 

244 return run 

245 

246 

247def linter_runner( 

248 resolved: ResolvedConfiguration, 

249 setup: ReviewSetup, 

250 workspace: Path, 

251 runner: SafeProcessRunner, 

252 *, 

253 execution_id: str, 

254) -> Callable[[list[Rule], Locations], list[ReviewFinding]] | None: 

255 """Outside a governed run (``review.panel.runTools``): run each pack tool the repository 

256 configures that verifies an active rule, once, and keep the diagnostics of those rules on 

257 reportable lines.""" 

258 standards = setup.standards 

259 if not setup.settings.run_tools or standards is None: 

260 return None 

261 

262 def run(rules: list[Rule], locations: Locations) -> list[ReviewFinding]: 

263 wanted = _wanted_rules(rules, setup.tools) 

264 if not wanted or not locations.lines: 264 ↛ 265line 264 didn't jump to line 265 because the condition on line 264 was never true

265 return [] 

266 grants = grants_from_rules(execution_id, TOOLS_ACTOR, resolved.effective_capabilities) 

267 limit = resolved.project.runtime.max_output_bytes 

268 findings: list[ReviewFinding] = [] 

269 for pack_tool in (tool for pack in standards.packs for tool in pack.tools): 

270 if pack_tool.tool_id not in wanted or not pack_tool.command: 

271 continue 

272 try: 

273 outcome = runner.run( 

274 CommandSpec( 

275 argv=pack_tool.command, 

276 cwd=workspace, 

277 timeout_seconds=600.0, 

278 max_output_bytes=limit, 

279 ), 

280 actor=TOOLS_ACTOR, 

281 grants=grants, 

282 ) 

283 except (OSError, ValueError): 

284 continue 

285 findings.extend( 

286 _tool_findings(pack_tool, wanted[pack_tool.tool_id], outcome, workspace, locations) 

287 ) 

288 del wanted[pack_tool.tool_id] 

289 return findings 

290 

291 return run 

292 

293 

294def _wanted_rules(rules: list[Rule], tools: frozenset[str]) -> dict[str, dict[str, Rule]]: 

295 """``tool -> tool rule name -> rule`` for the active rules a configured tool verifies.""" 

296 wanted: dict[str, dict[str, Rule]] = {} 

297 for rule in rules: 

298 for tool, name in rule.tools: 

299 if tool in tools and name: 299 ↛ 298line 299 didn't jump to line 298 because the condition on line 299 was always true

300 wanted.setdefault(tool, {})[name] = rule 

301 return wanted 

302 

303 

304def _tool_findings( 

305 pack_tool: PackTool, 

306 rules: dict[str, Rule], 

307 outcome: ProcessResult, 

308 workspace: Path, 

309 locations: Locations, 

310) -> list[ReviewFinding]: 

311 """The diagnostics of one tool run that belong to a wanted rule, on a reportable line.""" 

312 from governed_harness.validators.parsers import parse_output 

313 

314 issues = parse_output( 

315 outcome.stdout.decode("utf-8", "replace"), 

316 outcome.stderr.decode("utf-8", "replace"), 

317 workspace, 

318 parser=pack_tool.parser or "auto", 

319 ) 

320 findings: list[ReviewFinding] = [] 

321 for issue in issues: 

322 matched = rules.get(issue.rule) 

323 if matched is None or not issue.path or not issue.line: 

324 continue 

325 if not locations.allows(issue.path, "new", issue.line): 325 ↛ 326line 325 didn't jump to line 326 because the condition on line 325 was never true

326 continue 

327 findings.append( 

328 ReviewFinding( 

329 reviewer=pack_tool.tool_id, 

330 file=issue.path, 

331 side="new", 

332 line=issue.line, 

333 rule=matched.rule_id, 

334 severity="error" if matched.blocking else "suggestion", 

335 issue=issue.message, 

336 priority=matched.priority, 

337 source=f"tool:{pack_tool.tool_id}", 

338 ) 

339 ) 

340 return findings 

341 

342 

343__all__ = [ 

344 "ReviewSetup", 

345 "RouteObserver", 

346 "consistency_runner", 

347 "linter_runner", 

348 "panel_context", 

349 "panel_settings", 

350 "review_setup", 

351 "reviewer_route", 

352]