Coverage for src/governed_harness/gates/engine.py: 89%

73 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1from __future__ import annotations 

2 

3from collections.abc import Iterable 

4from dataclasses import dataclass 

5 

6from governed_harness.domain.enums import FindingSeverity, ResultStatus 

7from governed_harness.domain.ids import new_id 

8from governed_harness.domain.models import Finding, GateEvaluation, Provenance, ValidationResult 

9 

10 

11@dataclass(frozen=True) 

12class GateInput: 

13 check_id: str 

14 status: ResultStatus 

15 mandatory: bool = True 

16 

17 

18@dataclass(frozen=True) 

19class LegacyGateDecision: 

20 status: ResultStatus 

21 reason_codes: tuple[str, ...] 

22 

23 

24@dataclass(frozen=True) 

25class GatePolicy: 

26 require_human_decision: bool = True 

27 blocking_severities: tuple[FindingSeverity, ...] = ( 

28 FindingSeverity.HIGH, 

29 FindingSeverity.CRITICAL, 

30 ) 

31 

32 

33class GateEngine: 

34 """Fail-closed consolidation. It evaluates evidence; it never executes checks.""" 

35 

36 def evaluate( 

37 self, 

38 inputs: list[GateInput] | None = None, 

39 *, 

40 execution_id: str | None = None, 

41 gate_id: str | None = None, 

42 change_set_digest: str | None = None, 

43 policy_digest: str | None = None, 

44 validations: Iterable[ValidationResult] = (), 

45 findings: Iterable[Finding] = (), 

46 policy: GatePolicy | None = None, 

47 provenance: Provenance | None = None, 

48 ) -> GateEvaluation | LegacyGateDecision: 

49 if inputs is not None: 

50 return self._legacy(inputs) 

51 if ( 51 ↛ 59line 51 didn't jump to line 59 because the condition on line 51 was never true

52 execution_id is None 

53 or gate_id is None 

54 or change_set_digest is None 

55 or policy_digest is None 

56 or policy is None 

57 or provenance is None 

58 ): 

59 raise TypeError( 

60 "structured gate evaluation requires execution, gate, digests, policy and provenance" 

61 ) 

62 validation_list = list(validations) 

63 finding_list = list(findings) 

64 mandatory = [item for item in validation_list if item.mandatory] 

65 input_refs = tuple( 

66 [f"record://validation/{item.validation_result_id}" for item in validation_list] 

67 + [f"record://finding/{item.finding_id}" for item in finding_list] 

68 ) 

69 reasons: list[str] = [] 

70 if not mandatory: 

71 status = ResultStatus.INCONCLUSIVE 

72 reasons.append("NO_MANDATORY_VALIDATIONS") 

73 else: 

74 status = self._status(mandatory, reasons) 

75 blocking_findings = [ 

76 finding for finding in finding_list if finding.severity in policy.blocking_severities 

77 ] 

78 if blocking_findings and status is ResultStatus.PASSED: 

79 status = ResultStatus.FAILED 

80 for finding in blocking_findings: 

81 reasons.append(f"BLOCKING_FINDING_{finding.finding_id}") 

82 if not reasons and status is ResultStatus.PASSED: 

83 reasons.append("ALL_MANDATORY_VALIDATIONS_PASSED") 

84 return GateEvaluation( 

85 gate_evaluation_id=new_id("gateeval"), 

86 execution_id=execution_id, 

87 gate_id=gate_id, 

88 status=status, 

89 change_set_digest=change_set_digest, 

90 policy_digest=policy_digest, 

91 input_refs=input_refs, 

92 reason_codes=tuple(reasons), 

93 requires_human_decision=policy.require_human_decision, 

94 provenance=provenance, 

95 ) 

96 

97 @staticmethod 

98 def _legacy(inputs: list[GateInput]) -> LegacyGateDecision: 

99 """The decision over plain check inputs: only mandatory inputs count.""" 

100 mandatory_inputs = [item for item in inputs if item.mandatory] 

101 if not mandatory_inputs: 

102 return LegacyGateDecision(ResultStatus.INCONCLUSIVE, ("NO_MANDATORY_INPUTS",)) 

103 non_passed = [item for item in mandatory_inputs if item.status is not ResultStatus.PASSED] 

104 if not non_passed: 

105 return LegacyGateDecision(ResultStatus.PASSED, ("ALL_MANDATORY_PASSED",)) 

106 return LegacyGateDecision( 

107 GateEngine._legacy_status(non_passed), 

108 tuple(f"{item.check_id}_{item.status}" for item in non_passed), 

109 ) 

110 

111 @staticmethod 

112 def _legacy_status(non_passed: list[GateInput]) -> ResultStatus: 

113 if any(item.status is ResultStatus.ERROR for item in non_passed): 113 ↛ 114line 113 didn't jump to line 114 because the condition on line 113 was never true

114 return ResultStatus.ERROR 

115 if any( 115 ↛ 119line 115 didn't jump to line 119 because the condition on line 115 was never true

116 item.status in {ResultStatus.BLOCKED, ResultStatus.TIMED_OUT, ResultStatus.CANCELLED} 

117 for item in non_passed 

118 ): 

119 return ResultStatus.BLOCKED 

120 if any(item.status is ResultStatus.INCONCLUSIVE for item in non_passed): 120 ↛ 121line 120 didn't jump to line 121 because the condition on line 120 was never true

121 return ResultStatus.INCONCLUSIVE 

122 return ResultStatus.FAILED 

123 

124 @staticmethod 

125 def _status(mandatory: list[ValidationResult], reasons: list[str]) -> ResultStatus: 

126 non_passed = [item for item in mandatory if item.status is not ResultStatus.PASSED] 

127 if not non_passed: 

128 return ResultStatus.PASSED 

129 precedence = ( 

130 (ResultStatus.ERROR, ResultStatus.ERROR), 

131 (ResultStatus.TIMED_OUT, ResultStatus.BLOCKED), 

132 (ResultStatus.BLOCKED, ResultStatus.BLOCKED), 

133 (ResultStatus.CANCELLED, ResultStatus.BLOCKED), 

134 (ResultStatus.INCONCLUSIVE, ResultStatus.INCONCLUSIVE), 

135 (ResultStatus.SKIPPED, ResultStatus.INCONCLUSIVE), 

136 (ResultStatus.NOT_APPLICABLE, ResultStatus.INCONCLUSIVE), 

137 (ResultStatus.FAILED, ResultStatus.FAILED), 

138 ) 

139 for source, gate_status in precedence: 139 ↛ 144line 139 didn't jump to line 144 because the loop on line 139 didn't complete

140 matching = [item for item in non_passed if item.status is source] 

141 if matching: 

142 reasons.extend(f"{item.validator_id}_{source}" for item in matching) 

143 return gate_status 

144 reasons.append("UNKNOWN_MANDATORY_STATUS") 

145 return ResultStatus.ERROR