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

1"""Settings that are declared but not applied, reported by ``harness config validate`` (#51). 

2 

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

7 

8from __future__ import annotations 

9 

10from typing import Any 

11 

12from governed_harness.configuration.models import ResolvedConfiguration 

13 

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} 

21 

22_PROJECT_KEYS = { 

23 "workspace.units": ("workspace", "units"), 

24} 

25_POLICY_KEYS = ("ambiguousPackageManager",) 

26 

27 

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, [], {}) 

35 

36 

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 

51 

52 

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 

65 

66 

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 

110 

111 

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 

134 

135 

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 

140 

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 ] 

151 

152 

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