Coverage for src/governed_harness/configuration/resolver.py: 91%
175 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
1from __future__ import annotations
3import shutil
4from pathlib import Path
6from governed_harness.configuration.engineering import StandardsConfig
7from governed_harness.configuration.loader import (
8 BUILTIN_PROFILE_IDS,
9 EXTENDED_PROFILES,
10 find_project_config,
11 load_builtin_profile,
12 load_builtin_workflow,
13 load_extended_profiles,
14 load_project_config,
15 load_yaml,
16)
17from governed_harness.configuration.models import (
18 CapabilityRule,
19 ProjectConfiguration,
20 ResolvedConfiguration,
21 TechnologyProfileDefinition,
22 ToolchainConfig,
23 ValidatorDefinition,
24 WorkflowDefinition,
25)
26from governed_harness.configuration.policies import validate_profile_policies
27from governed_harness.configuration.workflow_rules import validate_enforced_workflow
28from governed_harness.domain.errors import ConfigurationError
29from governed_harness.profiles.detectors import detect_profiles
30from governed_harness.profiles.interpreter import discover_python, with_interpreter
32PROTECTED_WRITE_ROOTS = (".harness", ".git")
33"""Directories whose write scopes are dropped under ``governance.protectExcludedPaths``."""
36def _protected_scope(scope: str) -> bool:
37 return any(scope == root or scope.startswith(f"{root}/") for root in PROTECTED_WRITE_ROOTS)
40CORE_POLICIES = {
41 "requireHumanDecision": True,
42 "approvalDigestBinding": True,
43 "mandatoryNonSuccessBlocks": True,
44 "retrospectiveAutoApply": False,
45 "repositoryContentTrusted": False,
46 "destructiveActionsDefault": "deny",
47 "findingBlockSeverities": ["HIGH", "CRITICAL"],
48}
51class ConfigurationResolver:
52 def resolve(self, start: Path) -> ResolvedConfiguration:
53 config_path = find_project_config(start)
54 project = load_project_config(config_path)
55 workspace_root = (config_path.parent / project.workspace.root).resolve(strict=True)
56 toolchain = project.toolchain_settings
57 project_profiles, profile_files = load_project_profiles(
58 workspace_root,
59 toolchain.profile_paths or (),
60 reserved=frozenset(EXTENDED_PROFILES) if toolchain.extended_profiles else frozenset(),
61 )
62 # Since #55: the built-in Go, Rust, JVM, Swift and Android profiles are detected under
63 # toolchain.extendedProfiles; without it detection is the 1.0.0 one.
64 extended = load_extended_profiles() if toolchain.extended_profiles else {}
65 requested = self._requested_profiles(
66 project, workspace_root, [*project_profiles.values(), *extended.values()]
67 )
68 profiles = tuple(
69 project_profiles[profile_id]
70 if profile_id in project_profiles
71 else load_builtin_profile(profile_id)
72 for profile_id in dict.fromkeys(requested)
73 )
74 workflow = load_builtin_workflow(project.workflow)
75 if project.governance_settings.enforce_workflow:
76 # Since #3: every gate and condition the engine will evaluate must be known.
77 validate_enforced_workflow(workflow)
78 validators, grants = self._validators_and_grants(project, workspace_root, profiles)
79 if project.governance_settings.phase_capabilities:
80 # #4: the project narrows the profiles; the scopes derived from the validators the
81 # project selects are added after it, and each phase allows what it declares.
82 derived = grants[len(project.capabilities.grants) :]
83 capabilities = self._narrowed_capabilities(
84 project.capabilities.grants, derived, profiles
85 )
86 workflow = self._phase_workflow(workflow)
87 else:
88 capabilities = self._resolve_capabilities(grants, profiles)
89 if project.governance_settings.protect_excluded_paths:
90 capabilities = self._without_protected_writes(capabilities)
91 policies = self._resolve_policies(project.policies, profiles)
92 if project.governance_settings.apply_profile_policies:
93 validate_profile_policies(policies)
94 return ResolvedConfiguration(
95 project=project,
96 workspace_root=workspace_root,
97 profiles=profiles,
98 workflow=workflow,
99 effective_capabilities=capabilities,
100 effective_validators=validators,
101 effective_policies=policies,
102 source_files=(
103 str(config_path),
104 "builtin:workflow/default",
105 *(
106 f"builtin:profile/{p.profile_id}"
107 for p in profiles
108 if p.profile_id not in project_profiles
109 ),
110 *profile_files,
111 ),
112 )
114 @staticmethod
115 def _requested_profiles(
116 project: ProjectConfiguration,
117 workspace_root: Path,
118 candidates: list[TechnologyProfileDefinition],
119 ) -> list[str]:
120 """The profiles the project names; ``auto`` detects them among the project's own, the
121 extended and the built-in profiles (the best one, or all under ``profileDetection``)."""
122 requested = list(project.profiles)
123 if requested != ["auto"] and "auto" not in requested: 123 ↛ 124line 123 didn't jump to line 124 because the condition on line 123 was never true
124 return requested
125 detections = [
126 result
127 for result in detect_profiles(workspace_root, candidates)
128 if result.confidence > 0
129 ]
130 if not detections:
131 raise ConfigurationError("no supported technology profile detected")
132 if project.toolchain_settings.profile_detection == "all":
133 return [item.profile_id for item in detections]
134 return [detections[0].profile_id]
136 def _validators_and_grants(
137 self,
138 project: ProjectConfiguration,
139 workspace_root: Path,
140 profiles: tuple[TechnologyProfileDefinition, ...],
141 ) -> tuple[tuple[ValidatorDefinition, ...], tuple[CapabilityRule, ...]]:
142 """The validators of the profiles and the project, with the project toolchain and the
143 standards tools, and the grants with the process scopes those add."""
144 toolchain = project.toolchain_settings
145 validators = self._resolve_validators(project.validators, profiles)
146 grants = (*project.capabilities.grants, *(project.capabilities.extend or ()))
147 scopes: list[str] = []
148 if toolchain.validators or toolchain.interpreter == "auto":
149 validators, extra_scopes = self._project_toolchain(
150 validators, toolchain, workspace_root
151 )
152 scopes.extend(extra_scopes)
153 standards = project.standards
154 if standards is not None and standards.tools_enabled:
155 validators, tool_scopes = self._standards_tools(
156 validators, standards, workspace_root, profiles
157 )
158 scopes.extend(tool_scopes)
159 grants = (
160 *grants,
161 *(CapabilityRule(capability="process.execute", scope=(scope,)) for scope in scopes),
162 )
163 return validators, grants
165 @classmethod
166 def _narrowed_capabilities(
167 cls,
168 explicit: tuple[CapabilityRule, ...],
169 derived: tuple[CapabilityRule, ...],
170 profiles: tuple[TechnologyProfileDefinition, ...],
171 ) -> tuple[CapabilityRule, ...]:
172 from governed_harness.capabilities.phase import intersect_capabilities
174 profile_rules = cls._resolve_capabilities((), profiles)
175 narrowed = intersect_capabilities(profile_rules, explicit)
176 return cls._resolve_capabilities((*narrowed, *derived), ())
178 @staticmethod
179 def _phase_workflow(workflow: WorkflowDefinition) -> WorkflowDefinition:
180 """The workflow whose phases also allow what the harness itself runs in them
181 (``HARNESS_PHASE_CAPABILITIES``), recorded in the resolved configuration."""
182 from governed_harness.capabilities.phase import HARNESS_PHASE_CAPABILITIES
184 phases = tuple(
185 phase.model_copy(
186 update={
187 "allowed_capabilities": tuple(
188 dict.fromkeys(
189 (
190 *phase.allowed_capabilities,
191 *HARNESS_PHASE_CAPABILITIES.get(phase.phase_id.value, ()),
192 )
193 )
194 )
195 }
196 )
197 for phase in workflow.phases
198 )
199 return workflow.model_copy(update={"phases": phases})
201 @staticmethod
202 def _resolve_capabilities(
203 explicit: tuple[CapabilityRule, ...], profiles: tuple[TechnologyProfileDefinition, ...]
204 ) -> tuple[CapabilityRule, ...]:
205 merged: dict[tuple[str, bool], set[str]] = {}
206 for profile in profiles:
207 for capability, scopes in profile.capabilities.items():
208 merged.setdefault((capability, False), set()).update(scopes)
209 for rule in explicit:
210 merged.setdefault((rule.capability, rule.approval_required), set()).update(rule.scope)
211 return tuple(
212 CapabilityRule(
213 capability=capability, scope=tuple(sorted(scopes)), approvalRequired=approval
214 )
215 for (capability, approval), scopes in sorted(merged.items())
216 )
218 @staticmethod
219 def _without_protected_writes(
220 capabilities: tuple[CapabilityRule, ...],
221 ) -> tuple[CapabilityRule, ...]:
222 """Drop write grants on the harness state and on Git (``governance.protectExcludedPaths``):
223 the built-in profiles grant ``filesystem.write`` on ``.harness/**``."""
224 kept: list[CapabilityRule] = []
225 for rule in capabilities:
226 if rule.capability == "filesystem.write":
227 scope = tuple(item for item in rule.scope if not _protected_scope(item))
228 if not scope: 228 ↛ 229line 228 didn't jump to line 229 because the condition on line 228 was never true
229 continue
230 rule = rule.model_copy(update={"scope": scope})
231 kept.append(rule)
232 return tuple(kept)
234 @staticmethod
235 def _resolve_validators(
236 requested: tuple[str, ...], profiles: tuple[TechnologyProfileDefinition, ...]
237 ) -> tuple[ValidatorDefinition, ...]:
238 available: dict[str, ValidatorDefinition] = {}
239 defaults: list[str] = []
240 for profile in profiles:
241 defaults.extend(profile.default_validators)
242 available.update(
243 {validator.validator_id: validator for validator in profile.validators}
244 )
245 selected = list(requested) if requested else defaults
246 missing = [validator_id for validator_id in selected if validator_id not in available]
247 if missing: 247 ↛ 248line 247 didn't jump to line 248 because the condition on line 247 was never true
248 raise ConfigurationError(f"validators not defined by selected profiles: {missing}")
249 return tuple(available[validator_id] for validator_id in dict.fromkeys(selected))
251 @staticmethod
252 def _project_toolchain(
253 validators: tuple[ValidatorDefinition, ...],
254 toolchain: ToolchainConfig,
255 workspace_root: Path,
256 ) -> tuple[tuple[ValidatorDefinition, ...], tuple[str, ...]]:
257 """Apply ``toolchain.validators`` (replace a selected validator with the same id, add
258 the others) and ``toolchain.interpreter``. Returns the validators and the
259 ``process.execute`` scopes their commands need: the exact command of each project
260 validator and the discovered interpreter prefix."""
261 by_id = {item.validator_id: item for item in validators}
262 scopes: list[str] = []
263 for item in toolchain.validators or ():
264 by_id[item.validator_id] = item
265 scopes.append(" ".join(item.command or ()))
266 interpreter = discover_python(workspace_root) if toolchain.interpreter == "auto" else None
267 resolved = tuple(
268 item.model_copy(update={"command": with_interpreter(item.command, interpreter)})
269 for item in by_id.values()
270 )
271 if interpreter is not None and any(
272 item.command and item.command[: len(interpreter.argv)] == interpreter.argv
273 for item in resolved
274 ):
275 scopes.append(interpreter.grant_scope)
276 return resolved, tuple(dict.fromkeys(scope for scope in scopes if scope))
278 @staticmethod
279 def _standards_tools(
280 validators: tuple[ValidatorDefinition, ...],
281 standards: StandardsConfig,
282 workspace_root: Path,
283 profiles: tuple[TechnologyProfileDefinition, ...],
284 ) -> tuple[tuple[ValidatorDefinition, ...], tuple[str, ...]]:
285 """``standards.tools: detect`` (#56): an optional validator for every pack tool the
286 repository configures and no selected validator runs already, with a
287 ``process.execute`` grant for its exact command."""
288 from governed_harness.standards import project_standards, tool_validators
290 packs = project_standards(
291 workspace_root,
292 packs=standards.packs,
293 overrides=standards.overrides_path,
294 disabled=standards.disabled or (),
295 technologies=tuple(item.technology for item in profiles),
296 )
297 added = tool_validators(packs, workspace_root, [item.validator_id for item in validators])
298 return (
299 (*validators, *(definition for _pack, _tool, definition in added)),
300 tuple(" ".join(definition.command or ()) for _pack, _tool, definition in added),
301 )
303 @staticmethod
304 def _resolve_policies(
305 project_policies: dict[str, object], profiles: tuple[TechnologyProfileDefinition, ...]
306 ) -> dict[str, object]:
307 resolved: dict[str, object] = dict(CORE_POLICIES)
308 for profile in profiles:
309 resolved.update(profile.policies)
310 # Locked core policies may only remain true/deny. Other values are project-configurable.
311 for key, value in project_policies.items():
312 if (
313 key
314 in {"requireHumanDecision", "approvalDigestBinding", "mandatoryNonSuccessBlocks"}
315 and value is not True
316 ):
317 raise ConfigurationError(
318 f"project configuration may not weaken locked policy {key}"
319 )
320 if key == "retrospectiveAutoApply" and value is not False:
321 raise ConfigurationError("retrospectiveAutoApply is a locked false policy")
322 resolved[key] = value
323 return resolved
326def _profile_files(workspace_root: Path, paths: tuple[str, ...]) -> list[Path]:
327 """The profile files ``paths`` name: a directory gives its ``*.yaml`` files, sorted."""
328 files: list[Path] = []
329 for item in paths:
330 target = (workspace_root / item).resolve()
331 try:
332 target.relative_to(workspace_root)
333 except ValueError as error:
334 raise ConfigurationError(f"profile path leaves the workspace: {item}") from error
335 if target.is_dir():
336 files.extend(sorted(target.glob("*.yaml")))
337 elif target.is_file(): 337 ↛ 340line 337 didn't jump to line 340 because the condition on line 337 was always true
338 files.append(target)
339 else:
340 raise ConfigurationError(f"profile path not found: {item}")
341 return files
344def _load_profile(path: Path) -> TechnologyProfileDefinition:
345 """One project profile; any error but a ``ConfigurationError`` is wrapped in one."""
346 try:
347 return TechnologyProfileDefinition.model_validate(load_yaml(path))
348 except ConfigurationError:
349 raise
350 except Exception as error:
351 raise ConfigurationError(f"invalid project profile {path}: {error}") from error
354def load_project_profiles(
355 workspace_root: Path, paths: tuple[str, ...], reserved: frozenset[str] = frozenset()
356) -> tuple[dict[str, TechnologyProfileDefinition], tuple[str, ...]]:
357 """The profiles of ``toolchain.profilePaths`` by id, and the files they came from."""
358 files = _profile_files(workspace_root, paths)
359 profiles: dict[str, TechnologyProfileDefinition] = {}
360 for path in files:
361 profile = _load_profile(path)
362 if profile.profile_id in BUILTIN_PROFILE_IDS | reserved:
363 raise ConfigurationError(
364 f"project profile {path} uses the built-in profile id {profile.profile_id!r}"
365 )
366 if profile.profile_id in profiles: 366 ↛ 367line 366 didn't jump to line 367 because the condition on line 366 was never true
367 raise ConfigurationError(f"profile id {profile.profile_id!r} is declared twice")
368 profiles[profile.profile_id] = profile
369 return profiles, tuple(str(path) for path in files)
372def executable_available(argv0: str) -> bool:
373 if "/" in argv0 or "\\" in argv0:
374 return Path(argv0).exists()
375 return shutil.which(argv0) is not None