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

1from __future__ import annotations 

2 

3import shutil 

4from pathlib import Path 

5 

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 

31 

32PROTECTED_WRITE_ROOTS = (".harness", ".git") 

33"""Directories whose write scopes are dropped under ``governance.protectExcludedPaths``.""" 

34 

35 

36def _protected_scope(scope: str) -> bool: 

37 return any(scope == root or scope.startswith(f"{root}/") for root in PROTECTED_WRITE_ROOTS) 

38 

39 

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} 

49 

50 

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 ) 

113 

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] 

135 

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 

164 

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 

173 

174 profile_rules = cls._resolve_capabilities((), profiles) 

175 narrowed = intersect_capabilities(profile_rules, explicit) 

176 return cls._resolve_capabilities((*narrowed, *derived), ()) 

177 

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 

183 

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

200 

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 ) 

217 

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) 

233 

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

250 

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

277 

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 

289 

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 ) 

302 

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 

324 

325 

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 

342 

343 

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 

352 

353 

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) 

370 

371 

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