Coverage for src/governed_harness/configuration/declared.py: 83%
69 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"""Settings that are declared but not applied, reported by ``harness config validate`` (#51).
3Each one is marked ``x-declarative`` in the generated JSON Schema (or listed here when it is a
4policy or a setting whose effect depends on a ``governance`` key). ``config validate`` lists
5them all under ``declarative`` and adds a warning for each one the project actually relies on.
6"""
8from __future__ import annotations
10from typing import Any
12from governed_harness.configuration.models import ResolvedConfiguration
14DECLARATIVE_SETTINGS: dict[str, str] = {
15 "workspace.units": "Declared units are not used by the engine.",
16 "policies.ambiguousPackageManager": "No component reads it; the Node.js profile always uses "
17 "npm.",
18 "workflow.phases[].validators": "The validators come from the profiles and the project.",
19 "workflow.invariants": "Names of invariants the engine enforces in code.",
20}
22_PROJECT_KEYS = {
23 "workspace.units": ("workspace", "units"),
24}
25_POLICY_KEYS = ("ambiguousPackageManager",)
28def _present(raw: dict[str, Any], path: tuple[str, ...]) -> bool:
29 value: Any = raw
30 for part in path:
31 if not isinstance(value, dict) or part not in value: 31 ↛ 32line 31 didn't jump to line 32 because the condition on line 31 was never true
32 return False
33 value = value[part]
34 return value not in (None, [], {})
37def declared_settings_report(
38 resolved: ResolvedConfiguration, raw: dict[str, Any]
39) -> tuple[list[dict[str, str]], list[str]]:
40 """``(declarative, warnings)``: every declarative setting with its reason, and a warning for
41 each one this project sets (or receives from a profile) and for each declared setting that a
42 ``governance`` key would apply but that key is off."""
43 declarative = [{"key": key, "reason": reason} for key, reason in DECLARATIVE_SETTINGS.items()]
44 warnings = _declarative_key_warnings(resolved, raw)
45 warnings += _governance_warnings(resolved, raw)
46 warnings += _profile_policy_warnings(resolved)
47 if resolved.project.retention: 47 ↛ 49line 47 didn't jump to line 49 because the condition on line 47 was always true
48 warnings.append("retention is applied only when harness gc --apply runs")
49 warnings.extend(ungranted_provider_warnings(resolved))
50 return declarative, warnings
53def _declarative_key_warnings(resolved: ResolvedConfiguration, raw: dict[str, Any]) -> list[str]:
54 """A warning for each declarative key the project sets or receives from a profile."""
55 warnings: list[str] = []
56 for key, path in _PROJECT_KEYS.items():
57 if _present(raw, path): 57 ↛ 58line 57 didn't jump to line 58 because the condition on line 57 was never true
58 warnings.append(f"{key} is declarative: {DECLARATIVE_SETTINGS[key]}")
59 for key in _POLICY_KEYS:
60 if key in resolved.effective_policies and key in _project_or_profile_policies(resolved): 60 ↛ 61line 60 didn't jump to line 61 because the condition on line 60 was never true
61 warnings.append(
62 f"policies.{key} is declarative: {DECLARATIVE_SETTINGS[f'policies.{key}']}"
63 )
64 return warnings
67def _governance_warnings(resolved: ResolvedConfiguration, raw: dict[str, Any]) -> list[str]:
68 """A warning for each declared setting whose ``governance`` key is off."""
69 warnings: list[str] = []
70 governance = resolved.project.governance_settings
71 if not governance.phase_capabilities:
72 warnings.append(
73 "workflow allowedCapabilities are declared but not applied (grants are per run); "
74 "set governance.phaseCapabilities: true"
75 )
76 if not governance.apply_repository_policies:
77 warnings.append(
78 "policies repositoryContentTrusted and destructiveActionsDefault are declared but not "
79 "applied; set governance.applyRepositoryPolicies: true"
80 )
81 if not governance.apply_workflow_settings:
82 warnings.append(
83 "workflow maxAttempts, timeoutSeconds and exitGate are declared but not applied; "
84 "set governance.applyWorkflowSettings: true"
85 )
86 if not governance.enforce_workflow:
87 # Since #3 these take effect under governance.enforceWorkflow.
88 warnings.append(
89 "workflow exitGate, dependsOn and parallelizable are declared but not enforced; "
90 "set governance.enforceWorkflow: true"
91 )
92 if _present(raw, ("runtime", "maxParallel")): 92 ↛ 97line 92 didn't jump to line 97 because the condition on line 92 was always true
93 warnings.append(
94 "runtime.maxParallel is declarative without governance.enforceWorkflow: phases "
95 "and validators run one at a time"
96 )
97 if not governance.apply_network_policy and not resolved.project.runtime.allow_network: 97 ↛ 98line 97 didn't jump to line 98 because the condition on line 97 was never true
98 warnings.append(
99 "runtime.allowNetwork: false is not enforced; set governance.applyNetworkPolicy: "
100 "true (it applies to the agent sandbox under runtime.agentSandbox: enforce)"
101 )
102 if (
103 governance.apply_network_policy
104 and resolved.project.runtime.effective_agent_sandbox == "off"
105 ):
106 warnings.append(
107 "governance.applyNetworkPolicy has no effect while runtime.agentSandbox is off"
108 )
109 return warnings
112def _profile_policy_warnings(resolved: ResolvedConfiguration) -> list[str]:
113 """Profile policies that ``governance.applyProfilePolicies`` would apply, or cannot."""
114 warnings: list[str] = []
115 governance = resolved.project.governance_settings
116 profile_policies = {
117 key
118 for key in ("missingTestCommand", "missingTestScript", "coverage")
119 if key in resolved.effective_policies
120 }
121 if profile_policies and not governance.apply_profile_policies:
122 warnings.append(
123 f"policies {', '.join(sorted(profile_policies))} are declared but not applied; set "
124 "governance.applyProfilePolicies: true"
125 )
126 coverage = resolved.effective_policies.get("coverage")
127 if ( 127 ↛ 132line 127 didn't jump to line 132 because the condition on line 127 was never true
128 governance.apply_profile_policies
129 and isinstance(coverage, dict)
130 and not any(profile.technology == "python" for profile in resolved.profiles)
131 ):
132 warnings.append("policies.coverage.minimumPercent is applied to Python projects only")
133 return warnings
136def ungranted_provider_warnings(resolved: ResolvedConfiguration) -> list[str]:
137 """Under ``governance.phaseCapabilities`` (#87) a provider command that no ``process.execute``
138 grant allows is refused when the run starts it: one warning per such provider."""
139 from governed_harness.capabilities.phase import launch_granted
141 if not resolved.project.governance_settings.phase_capabilities:
142 return []
143 return [
144 f"agentProviders.{provider_id}.command {' '.join(config.effective_command)!r} is not "
145 "allowed by any process.execute grant: a run refuses to start it; add it to "
146 "capabilities.extend"
147 for provider_id, config in sorted(resolved.project.agent_providers.items())
148 if config.effective_command
149 and not launch_granted(config.effective_command, resolved.effective_capabilities)
150 ]
153def _project_or_profile_policies(resolved: ResolvedConfiguration) -> set[str]:
154 keys = set(resolved.project.policies)
155 for profile in resolved.profiles:
156 keys |= set(profile.policies)
157 return keys