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
« 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).
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:
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).
19The tools the profiles' capabilities need (their detection commands) are reported, not
20enforced: the validators report a missing tool in VERIFICATION as before."""
22from __future__ import annotations
24import os
25import re
26import subprocess # nosec B404 - fixed git argv below, no shell
27from pathlib import Path
28from typing import TYPE_CHECKING, Any
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
40if TYPE_CHECKING:
41 from governed_harness.orchestration.ladder_host import LadderHost
43ENVIRONMENT_ID = "harness.environment"
44_TIMEOUT = 15
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")
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)
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)
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
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
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
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 }
157class EnvironmentPreflight:
158 def __init__(self, ladder: LadderHost) -> None:
159 self.ladder = ladder
161 @property
162 def config(self) -> EnvironmentConfig | None:
163 return self.ladder.project.environment
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
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
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}
322__all__ = [
323 "ENVIRONMENT_ID",
324 "EnvironmentPreflight",
325 "dirty_paths",
326 "environment_checks",
327 "hooks_directory",
328]