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

1"""Configuration of the review panel (``review.panel``, since #57). 

2 

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

7 

8from __future__ import annotations 

9 

10import re 

11from typing import Any, Literal 

12 

13from pydantic import Field, field_validator 

14 

15from governed_harness.configuration.agent_results import _Section, off_from_yaml 

16 

17PanelPolicy = Literal["enforce", "warn", "off"] 

18AutoFixMode = Literal["scoped", "off"] 

19SecondOpinionMode = Literal["blocking", "off"] 

20 

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 

29 

30_ID = re.compile(r"^[a-z][a-z0-9-]{0,63}$") 

31 

32 

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

37 

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) 

41 

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

51 

52 

53class PanelCache(_Section): 

54 """The review cache under ``.harness/review/cache``: a time to live and an entry limit.""" 

55 

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) 

59 

60 @property 

61 def on(self) -> bool: 

62 return self.enabled is not False 

63 

64 @property 

65 def ttl_seconds(self) -> int: 

66 return (self.ttl_days or DEFAULT_CACHE_TTL_DAYS) * 86_400 

67 

68 @property 

69 def limit(self) -> int: 

70 return self.max_entries or DEFAULT_CACHE_ENTRIES 

71 

72 

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

76 

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) 

80 

81 

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

85 

86 mode: AutoFixMode | None = None 

87 max_attempts: int | None = Field(default=None, alias="maxAttempts", ge=0, le=10) 

88 

89 @field_validator("mode", mode="before") 

90 @classmethod 

91 def _bare_off(cls, value: Any) -> Any: 

92 return off_from_yaml(value) 

93 

94 @property 

95 def attempts(self) -> int: 

96 return self.max_attempts if self.max_attempts is not None else DEFAULT_AUTOFIX_ATTEMPTS 

97 

98 

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

102 

103 mode: SecondOpinionMode | None = None 

104 provider: str | None = None 

105 

106 @field_validator("mode", mode="before") 

107 @classmethod 

108 def _bare_off(cls, value: Any) -> Any: 

109 return off_from_yaml(value) 

110 

111 

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

117 

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

146 

147 @field_validator("mode", mode="before") 

148 @classmethod 

149 def _bare_off(cls, value: Any) -> Any: 

150 return off_from_yaml(value) 

151 

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 

159 

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 

169 

170 @property 

171 def enabled(self) -> bool: 

172 return self.mode in {"enforce", "warn"} 

173 

174 @property 

175 def finding_limit(self) -> int: 

176 return self.max_findings or DEFAULT_MAX_FINDINGS 

177 

178 @property 

179 def workers(self) -> int: 

180 return self.parallel or DEFAULT_PARALLEL 

181 

182 @property 

183 def effective_budget(self) -> PanelBudget: 

184 return self.budget or PanelBudget() 

185 

186 @property 

187 def effective_cache(self) -> PanelCache: 

188 return self.cache or PanelCache() 

189 

190 

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]