Coverage for src/governed_harness/configuration/review.py: 92%
121 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"""Configuration of the review panel (``review.panel``, since #57).
3Every key is optional and left out of the serialized configuration when unset, so a
4``project.yaml`` without ``review.panel`` keeps the earlier behaviour and its configuration
5digest: the single second reviewer of #38 under ``review.agentReview``. ``harness init`` writes
6the section."""
8from __future__ import annotations
10import re
11from typing import Any, Literal
13from pydantic import Field, field_validator
15from governed_harness.configuration.agent_results import _Section, off_from_yaml
17PanelPolicy = Literal["enforce", "warn", "off"]
18AutoFixMode = Literal["scoped", "off"]
19SecondOpinionMode = Literal["blocking", "off"]
21DEFAULT_MAX_FINDINGS = 20
22DEFAULT_PARALLEL = 4
23DEFAULT_BASE_TOKENS = 6_000
24DEFAULT_TOKENS_PER_LINE = 30
25DEFAULT_MAX_TOKENS = 60_000
26DEFAULT_CACHE_TTL_DAYS = 14
27DEFAULT_CACHE_ENTRIES = 500
28DEFAULT_AUTOFIX_ATTEMPTS = 2
30_ID = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
33class PanelBudget(_Section):
34 """The token budget of one reviewer call, proportional to the size of its diff slice:
35 ``baseTokens + tokensPerLine * changed lines``, at most ``maxTokens`` (or the reviewer's own
36 ``maxBudget``)."""
38 base_tokens: int | None = Field(default=None, alias="baseTokens", ge=0)
39 tokens_per_line: int | None = Field(default=None, alias="tokensPerLine", ge=0)
40 max_tokens: int | None = Field(default=None, alias="maxTokens", ge=1)
42 def for_lines(self, lines: int, cap: int | None = None) -> int:
43 base = self.base_tokens if self.base_tokens is not None else DEFAULT_BASE_TOKENS
44 per_line = (
45 self.tokens_per_line if self.tokens_per_line is not None else DEFAULT_TOKENS_PER_LINE
46 )
47 ceiling = self.max_tokens if self.max_tokens is not None else DEFAULT_MAX_TOKENS
48 if cap is not None:
49 ceiling = min(ceiling, cap)
50 return max(1, min(ceiling, base + per_line * max(lines, 0)))
53class PanelCache(_Section):
54 """The review cache under ``.harness/review/cache``: a time to live and an entry limit."""
56 enabled: bool | None = None
57 ttl_days: int | None = Field(default=None, alias="ttlDays", ge=1, le=365)
58 max_entries: int | None = Field(default=None, alias="maxEntries", ge=1, le=100_000)
60 @property
61 def on(self) -> bool:
62 return self.enabled is not False
64 @property
65 def ttl_seconds(self) -> int:
66 return (self.ttl_days or DEFAULT_CACHE_TTL_DAYS) * 86_400
68 @property
69 def limit(self) -> int:
70 return self.max_entries or DEFAULT_CACHE_ENTRIES
73class ConsistencyCheck(_Section):
74 """A deterministic check of the project that runs before any reviewer; when it fails no
75 model is called (#57 item 12)."""
77 check_id: str = Field(alias="id", min_length=1, max_length=64)
78 command: tuple[str, ...] = Field(min_length=1)
79 timeout_seconds: int | None = Field(default=None, alias="timeoutSeconds", ge=1, le=3600)
82class AutoFixConfig(_Section):
83 """Scoped auto-fix: only errors on lines the agent wrote in the run (provenance) go back to
84 IMPLEMENTATION, at most ``maxAttempts`` times; suggestions never do."""
86 mode: AutoFixMode | None = None
87 max_attempts: int | None = Field(default=None, alias="maxAttempts", ge=0, le=10)
89 @field_validator("mode", mode="before")
90 @classmethod
91 def _bare_off(cls, value: Any) -> Any:
92 return off_from_yaml(value)
94 @property
95 def attempts(self) -> int:
96 return self.max_attempts if self.max_attempts is not None else DEFAULT_AUTOFIX_ATTEMPTS
99class SecondOpinionConfig(_Section):
100 """An optional second opinion on the blocking findings only (``mode: blocking``), from
101 ``provider`` (default: the fallback provider, else the panel's provider)."""
103 mode: SecondOpinionMode | None = None
104 provider: str | None = None
106 @field_validator("mode", mode="before")
107 @classmethod
108 def _bare_off(cls, value: Any) -> Any:
109 return off_from_yaml(value)
112class ReviewPanelConfig(_Section):
113 """The review panel (#57): reviewers by domain over diff slices, a layered rule catalog
114 (built-in, language packs, project), a fixed output contract and a verdict the harness
115 recomputes. Replaces the single reviewer of ``review.agentReview`` in INDEPENDENT_REVIEW and
116 runs outside governed runs with ``harness review-code``."""
118 mode: PanelPolicy | None = None
119 reviewers: tuple[str, ...] | None = None
120 """The reviewers that may run (built-in and project ids); absent: all of them."""
121 max_findings: int | None = Field(default=None, alias="maxFindings", ge=1, le=200)
122 parallel: int | None = Field(default=None, ge=1, le=16)
123 budget: PanelBudget | None = None
124 cache: PanelCache | None = None
125 provider: str | None = None
126 """The provider of the reviewers (an ``agentProviders`` id); absent: the review call's."""
127 fallback_provider: str | None = Field(default=None, alias="fallbackProvider")
128 """The alternate provider of the one retry after an invalid answer (UNKNOWN)."""
129 consistency_checks: tuple[ConsistencyCheck, ...] | None = Field(
130 default=None, alias="consistencyChecks"
131 )
132 run_tools: bool | None = Field(default=None, alias="runTools")
133 """Outside a governed run, run the pack tools the repository configures for the rules they
134 verify (``verified_by: tool:...``); inside a run the validators already ran them."""
135 auto_fix: AutoFixConfig | None = Field(default=None, alias="autoFix")
136 second_opinion: SecondOpinionConfig | None = Field(default=None, alias="secondOpinion")
137 evidence_refs: bool | None = Field(default=None, alias="evidenceRefs")
138 """Record a passing review as ``refs/harness/review/pass/SHA`` (or ``pass-warn``)."""
139 comment: bool | None = None
140 """Post one pull or merge request comment per passing result through the forge layer."""
141 base_branches: dict[str, str] | None = Field(default=None, alias="baseBranches")
142 """Branch-name globs and the base branch each one is reviewed against (``feat/*: develop``)."""
143 mcp_servers: tuple[str, ...] | None = Field(default=None, alias="mcpServers")
144 """The MCP servers (names of the repository's ``.mcp.json``) a reviewer may use; absent or
145 empty: none."""
147 @field_validator("mode", mode="before")
148 @classmethod
149 def _bare_off(cls, value: Any) -> Any:
150 return off_from_yaml(value)
152 @field_validator("reviewers")
153 @classmethod
154 def _ids(cls, value: tuple[str, ...] | None) -> tuple[str, ...] | None:
155 for item in value or ():
156 if not _ID.match(item):
157 raise ValueError(f"reviewer id must be lower case with dashes: {item!r}")
158 return value
160 @field_validator("consistency_checks")
161 @classmethod
162 def _unique_checks(
163 cls, value: tuple[ConsistencyCheck, ...] | None
164 ) -> tuple[ConsistencyCheck, ...] | None:
165 ids = [item.check_id for item in value or ()]
166 if len(set(ids)) != len(ids): 166 ↛ 167line 166 didn't jump to line 167 because the condition on line 166 was never true
167 raise ValueError("consistency check ids must be unique")
168 return value
170 @property
171 def enabled(self) -> bool:
172 return self.mode in {"enforce", "warn"}
174 @property
175 def finding_limit(self) -> int:
176 return self.max_findings or DEFAULT_MAX_FINDINGS
178 @property
179 def workers(self) -> int:
180 return self.parallel or DEFAULT_PARALLEL
182 @property
183 def effective_budget(self) -> PanelBudget:
184 return self.budget or PanelBudget()
186 @property
187 def effective_cache(self) -> PanelCache:
188 return self.cache or PanelCache()
191__all__ = [
192 "DEFAULT_AUTOFIX_ATTEMPTS",
193 "DEFAULT_BASE_TOKENS",
194 "DEFAULT_CACHE_ENTRIES",
195 "DEFAULT_CACHE_TTL_DAYS",
196 "DEFAULT_MAX_FINDINGS",
197 "DEFAULT_MAX_TOKENS",
198 "DEFAULT_PARALLEL",
199 "DEFAULT_TOKENS_PER_LINE",
200 "AutoFixConfig",
201 "ConsistencyCheck",
202 "PanelBudget",
203 "PanelCache",
204 "ReviewPanelConfig",
205 "SecondOpinionConfig",
206]