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
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3from collections.abc import Iterable
4from dataclasses import dataclass
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
11@dataclass(frozen=True)
12class GateInput:
13 check_id: str
14 status: ResultStatus
15 mandatory: bool = True
18@dataclass(frozen=True)
19class LegacyGateDecision:
20 status: ResultStatus
21 reason_codes: tuple[str, ...]
24@dataclass(frozen=True)
25class GatePolicy:
26 require_human_decision: bool = True
27 blocking_severities: tuple[FindingSeverity, ...] = (
28 FindingSeverity.HIGH,
29 FindingSeverity.CRITICAL,
30 )
33class GateEngine:
34 """Fail-closed consolidation. It evaluates evidence; it never executes checks."""
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 )
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 )
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
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