Coverage for src/governed_harness/orchestration/ladder_environment.py: 94%

141 statements  

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

1"""Generic environment preflight (#55, item 10; the ``environment`` section). 

2 

3Before anything changes, DISCOVERY checks what the run will rely on, so that a missing tool or a 

4broken baseline stops the run before an agent is paid to work on it: 

5 

6* ``tools``: each declared tool prints its version and the version matches the pattern; 

7* ``variables``: each declared environment variable is set (its value is never read into the 

8 record); 

9* ``gitHooks.required``: each hook is present and executable in the hooks directory Git uses 

10 (``core.hooksPath`` included). The harness never bypasses hooks; ``install`` is the command the 

11 project declares to install them, named in the reason and run only by ``harness doctor 

12 --install-hooks``; 

13* ``dirtyTree``: uncommitted changes outside ``.harness/`` (``block`` stops the run, ``warn`` 

14 records a LOW finding, ``allow`` records them); 

15* ``baseline``: the mandatory validators run on a scratch copy of the baseline; ``require`` 

16 stops the run when one does not pass, ``report`` records it (and the comparison with the 

17 baseline of ``verification.differential`` reuses the result). 

18 

19The tools the profiles' capabilities need (their detection commands) are reported, not 

20enforced: the validators report a missing tool in VERIFICATION as before.""" 

21 

22from __future__ import annotations 

23 

24import os 

25import re 

26import subprocess # nosec B404 - fixed git argv below, no shell 

27from pathlib import Path 

28from typing import TYPE_CHECKING, Any 

29 

30from governed_harness.capabilities import grants_from_rules 

31from governed_harness.configuration.ladder import EnvironmentConfig 

32from governed_harness.domain.enums import ActorType, FindingSeverity, PhaseId, ResultStatus 

33from governed_harness.domain.models import Actor, ChangeSet, Execution, PhaseExecution 

34from governed_harness.ladder.capabilities import run_detection 

35from governed_harness.orchestration.engine_types import PhaseOutcome 

36from governed_harness.orchestration.workspace_ops import Contents, materialized 

37from governed_harness.runtime import CancellationToken, SafeProcessRunner 

38from governed_harness.validators import ValidationContext 

39 

40if TYPE_CHECKING: 

41 from governed_harness.orchestration.ladder_host import LadderHost 

42 

43ENVIRONMENT_ID = "harness.environment" 

44_TIMEOUT = 15 

45 

46 

47def _git(workspace: Path, *args: str) -> tuple[int, str]: 

48 try: 

49 result = subprocess.run( # nosec B603 B607 - fixed git argv, no shell 

50 ["git", *args], 

51 cwd=workspace, 

52 capture_output=True, 

53 check=False, 

54 timeout=60, 

55 stdin=subprocess.DEVNULL, 

56 env={**os.environ, "GIT_TERMINAL_PROMPT": "0"}, 

57 ) 

58 except (OSError, subprocess.SubprocessError) as error: 

59 return 1, str(error) 

60 return result.returncode, result.stdout.decode("utf-8", "replace") 

61 

62 

63def hooks_directory(workspace: Path) -> Path | None: 

64 code, output = _git(workspace, "rev-parse", "--git-path", "hooks") 

65 if code != 0 or not output.strip(): 65 ↛ 66line 65 didn't jump to line 66 because the condition on line 65 was never true

66 return None 

67 path = Path(output.strip()) 

68 return path if path.is_absolute() else (workspace / path) 

69 

70 

71def dirty_paths(workspace: Path) -> list[str] | None: 

72 """Uncommitted changes outside ``.harness/`` (``None`` outside a Git repository).""" 

73 code, output = _git(workspace, "status", "--porcelain", "--untracked-files=normal") 

74 if code != 0: 74 ↛ 75line 74 didn't jump to line 75 because the condition on line 74 was never true

75 return None 

76 paths = [] 

77 for line in output.splitlines(): 

78 path = line[3:].strip().strip('"') 

79 if path and not path.startswith(".harness"): 

80 paths.append(path) 

81 return sorted(paths) 

82 

83 

84def _tool_checks( 

85 config: EnvironmentConfig, workspace: Path, timeout: int 

86) -> tuple[list[dict[str, Any]], list[str]]: 

87 """Each required tool, its version and why it is not usable.""" 

88 tools: list[dict[str, Any]] = [] 

89 problems: list[str] = [] 

90 for item in config.tools or (): 

91 code, output = run_detection(tuple(item.command), workspace, timeout) 

92 ok = code == 0 and (item.pattern is None or re.search(item.pattern, output) is not None) 

93 version = output.strip().splitlines()[0][:200] if output.strip() else "" 

94 tools.append({"name": item.name, "available": ok, "version": version}) 

95 if not ok: 

96 want = f" matching {item.pattern!r}" if item.pattern else "" 

97 problems.append(f"tool {item.name}{want} is not available ({version or output[:200]})") 

98 return tools, problems 

99 

100 

101def _hook_state(path: Path | None) -> tuple[bool, bool]: 

102 """Whether a hook file is present and executable (any file is on Windows).""" 

103 present = bool(path and path.is_file()) 

104 executable = bool(path and present and (os.name == "nt" or os.access(path, os.X_OK))) 

105 return present, executable 

106 

107 

108def _hook_checks( 

109 config: EnvironmentConfig, workspace: Path 

110) -> tuple[list[dict[str, Any]], list[str]]: 

111 """Each required Git hook, whether it is present and executable, and how to install it.""" 

112 hooks: list[dict[str, Any]] = [] 

113 problems: list[str] = [] 

114 git_hooks = config.git_hooks 

115 if not git_hooks or not git_hooks.required: 

116 return hooks, problems 

117 directory = hooks_directory(workspace) 

118 install = f"; install it with: {' '.join(git_hooks.install)}" if git_hooks.install else "" 

119 for name in git_hooks.required: 

120 present, executable = _hook_state(directory / name if directory else None) 

121 hooks.append({"name": name, "present": present, "executable": executable}) 

122 if not executable: 

123 state = "not executable" if present else "missing" 

124 problems.append(f"Git hook {name} is {state}{install}") 

125 return hooks, problems 

126 

127 

128def environment_checks( 

129 config: EnvironmentConfig, workspace: Path, *, timeout: int = _TIMEOUT 

130) -> dict[str, Any]: 

131 """Tools, variables, hooks and the dirty tree (no validator runs): the checks DISCOVERY 

132 and ``harness doctor`` share. ``problems`` are the ones that stop a run.""" 

133 tools, problems = _tool_checks(config, workspace, timeout) 

134 variables = [ 

135 {"name": name, "set": bool(os.environ.get(name))} for name in config.variables or () 

136 ] 

137 problems.extend( 

138 f"environment variable {item['name']} is not set" for item in variables if not item["set"] 

139 ) 

140 hooks, hook_problems = _hook_checks(config, workspace) 

141 problems.extend(hook_problems) 

142 dirty = dirty_paths(workspace) 

143 policy = config.dirty_tree or "allow" 

144 if dirty and policy == "block": 

145 problems.append( 

146 f"the working tree has {len(dirty)} uncommitted change(s): {', '.join(dirty[:10])}" 

147 ) 

148 return { 

149 "tools": tools, 

150 "variables": variables, 

151 "gitHooks": hooks, 

152 "dirtyTree": {"policy": policy, "paths": dirty}, 

153 "problems": problems, 

154 } 

155 

156 

157class EnvironmentPreflight: 

158 def __init__(self, ladder: LadderHost) -> None: 

159 self.ladder = ladder 

160 

161 @property 

162 def config(self) -> EnvironmentConfig | None: 

163 return self.ladder.project.environment 

164 

165 def run( 

166 self, execution: Execution, phase: PhaseExecution, baseline_digest: str 

167 ) -> PhaseOutcome | None: 

168 config = self.config 

169 if config is None: 

170 return None 

171 hub = self.ladder 

172 results = hub.engine.results 

173 workspace = hub.s.paths.workspace 

174 report = environment_checks(config, workspace) 

175 report["profileTools"] = [ 

176 item.as_dict() 

177 for item in hub.capabilities(execution) 

178 if item.level in {"L0", "L1"} and item.detections 

179 ] 

180 problems: list[str] = list(report["problems"]) 

181 dirty = report["dirtyTree"]["paths"] or [] 

182 if dirty and config.dirty_tree == "warn": 182 ↛ 183line 182 didn't jump to line 183 because the condition on line 182 was never true

183 results.record_finding( 

184 execution, 

185 validator_id=ENVIRONMENT_ID, 

186 rule_id="environment.dirty-tree", 

187 category="environment", 

188 severity=FindingSeverity.LOW, 

189 message=( 

190 f"The run starts on {len(dirty)} uncommitted change(s): " 

191 + ", ".join(dirty[:10]) 

192 ), 

193 recommendation="Commit or stash unrelated changes before a governed run.", 

194 ) 

195 if config.baseline in {"require", "report"}: 

196 baseline = self._baseline(execution, baseline_digest) 

197 report["baseline"] = baseline 

198 failing = [item for item in baseline["validators"] if item["status"] != "PASSED"] 

199 if failing and config.baseline == "require": 

200 problems.append( 

201 "the baseline does not pass: " 

202 + ", ".join(f"{item['validatorId']} {item['status']}" for item in failing) 

203 ) 

204 elif failing: 

205 results.record_finding( 

206 execution, 

207 validator_id=ENVIRONMENT_ID, 

208 rule_id="environment.baseline-failing", 

209 category="environment", 

210 severity=FindingSeverity.LOW, 

211 message=( 

212 "The baseline already fails before the change: " 

213 + ", ".join(f"{item['validatorId']} {item['status']}" for item in failing) 

214 ), 

215 recommendation=( 

216 "Failures the baseline already has are not the change's; " 

217 "verification.differential tells them apart." 

218 ), 

219 ) 

220 report["problems"] = problems 

221 ref = results.record_json( 

222 execution, 

223 PhaseId.DISCOVERY, 

224 report, 

225 kind="environment-preflight", 

226 summary=( 

227 f"Environment preflight: {len(problems)} problem(s)" 

228 if problems 

229 else "Environment preflight passed" 

230 ), 

231 ) 

232 hub.s.events.append( 

233 execution.execution_id, 

234 "environment.preflight.completed", 

235 {"problems": problems, "evidenceRef": ref}, 

236 phase_execution_id=phase.phase_execution_id, 

237 ) 

238 if problems: 

239 return PhaseOutcome( 

240 ResultStatus.BLOCKED, 

241 "Environment preflight: " + "; ".join(problems[:5]), 

242 (ref,), 

243 ) 

244 return None 

245 

246 def _baseline(self, execution: Execution, baseline_digest: str) -> dict[str, Any]: 

247 """Run the mandatory validators on a scratch copy of the workspace as DISCOVERY found 

248 it, and keep each result where the baseline comparison looks for it.""" 

249 from governed_harness.orchestration.differential import Differential 

250 

251 hub = self.ladder 

252 engine = hub.engine 

253 results = engine.results 

254 workspace = hub.s.paths.workspace 

255 scratch = hub.s.paths.harness_dir / "tmp" 

256 placeholder = ChangeSet( 

257 change_set_id="baseline", 

258 execution_id=execution.execution_id, 

259 files=(), 

260 diff_ref="baseline", 

261 digest=baseline_digest, 

262 ) 

263 entries: list[dict[str, Any]] = [] 

264 unchanged = Contents(lambda _path: True, lambda _path: None) 

265 with materialized(workspace, scratch, unchanged, []) as copy: 

266 if copy is None: 266 ↛ 267line 266 didn't jump to line 267 because the condition on line 266 was never true

267 return {"validators": [], "problem": "the baseline could not be copied"} 

268 for definition in hub.s.resolved.effective_validators: 

269 if not definition.mandatory: 

270 continue 

271 actor = Actor( 

272 actor_type=ActorType.TOOL, 

273 actor_id=f"validator.{definition.validator_id}", 

274 version="1", 

275 ) 

276 output = engine.validators.create(definition.validator_id).execute( 

277 ValidationContext( 

278 execution_id=execution.execution_id, 

279 workspace=copy, 

280 task=engine.run_task(execution), 

281 change_set=placeholder, 

282 definition=engine._bounded_definition(definition), 

283 grants=grants_from_rules( 

284 execution.execution_id, actor, hub.s.resolved.effective_capabilities 

285 ), 

286 artifact_store=hub.s.artifacts, 

287 process_runner=SafeProcessRunner(copy), 

288 provenance=engine._provenance(execution).model_copy( 

289 update={"actor": actor} 

290 ), 

291 cancellation=CancellationToken( 

292 lambda: engine.is_cancelled(execution.execution_id) 

293 ), 

294 max_output_bytes=hub.project.runtime.max_output_bytes, 

295 ) 

296 ) 

297 status = output.result.status 

298 differential = Differential(results) 

299 keys = differential._candidate_keys(output.result, copy) 

300 record = { 

301 "validatorId": definition.validator_id, 

302 "baselineDigest": baseline_digest, 

303 "status": status.value, 

304 "keys": list(keys), 

305 "evidenceRefs": list(output.result.evidence_refs), 

306 } 

307 if status in {ResultStatus.PASSED, ResultStatus.FAILED}: 307 ↛ 311line 307 didn't jump to line 311 because the condition on line 307 was always true

308 results.set_flag_json( 

309 differential._cache_key(baseline_digest, definition), record 

310 ) 

311 entries.append( 

312 { 

313 "validatorId": definition.validator_id, 

314 "status": status.value, 

315 "summary": output.result.summary, 

316 "evidenceRefs": list(output.result.evidence_refs), 

317 } 

318 ) 

319 return {"validators": entries} 

320 

321 

322__all__ = [ 

323 "ENVIRONMENT_ID", 

324 "EnvironmentPreflight", 

325 "dirty_paths", 

326 "environment_checks", 

327 "hooks_directory", 

328]