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
« 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``."""
4from __future__ import annotations
6from collections.abc import Callable
7from dataclasses import dataclass, replace
8from pathlib import Path
9from typing import Any
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
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
50@dataclass(frozen=True)
51class ReviewSetup:
52 settings: ReviewPanelConfig
53 catalog: Catalog
54 reviewers: list[Reviewer]
55 standards: ProjectStandards | None
56 tools: frozenset[str]
58 @property
59 def packs(self) -> tuple[str, ...]:
60 return tuple(item.pack_id for item in self.standards.packs) if self.standards else ()
63def panel_settings(resolved: ResolvedConfiguration) -> ReviewPanelConfig:
64 review = resolved.project.review
65 return (review.panel if review is not None else None) or ReviewPanelConfig()
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)
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))
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)))
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)))
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 )
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
154RouteObserver = Callable[[Reviewer, str, RoutingDecision], None]
155"""Hears the routing decision of a reviewer on a provider (#85: recorded per call)."""
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
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
196 return route
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
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
244 return run
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
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
291 return run
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
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
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
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]