Coverage for src/governed_harness/orchestration/feedback.py: 98%

68 statements  

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

1"""Feedback for a correction attempt and the transient-failure test for command providers. 

2 

3Both work on what the harness already recorded (validation results, findings and their redacted 

4artifacts); neither runs a check of its own.""" 

5 

6from __future__ import annotations 

7 

8import json 

9import re 

10from collections.abc import Iterable, Sequence 

11 

12from governed_harness.domain.enums import FindingSeverity, ResultStatus 

13from governed_harness.domain.models import ( 

14 FEEDBACK_MAX_FINDINGS, 

15 FEEDBACK_STREAM_CHARS, 

16 FEEDBACK_TEXT_CHARS, 

17 FEEDBACK_TOTAL_CHARS, 

18 FeedbackDecision, 

19 FeedbackFinding, 

20 FeedbackGate, 

21 FeedbackTrigger, 

22 FeedbackValidator, 

23 Finding, 

24 ProviderFeedback, 

25 ValidationResult, 

26) 

27from governed_harness.evidence import LocalArtifactStore 

28 

29_SEVERITY_ORDER = { 

30 FindingSeverity.CRITICAL: 0, 

31 FindingSeverity.HIGH: 1, 

32 FindingSeverity.MEDIUM: 2, 

33 FindingSeverity.LOW: 3, 

34 FindingSeverity.INFO: 4, 

35} 

36 

37TRANSIENT_SCAN_BYTES = 65536 

38"""Bytes read from the end of each provider stream when looking for a transient cause.""" 

39 

40 

41def tail(text: str, limit: int) -> tuple[str, bool]: 

42 """The last ``limit`` characters of ``text`` and whether anything was cut.""" 

43 if limit <= 0: 

44 return "", bool(text) 

45 if len(text) <= limit: 

46 return text, False 

47 return text[-limit:], True 

48 

49 

50def head(text: str, limit: int = FEEDBACK_TEXT_CHARS) -> str: 

51 """``text`` cut to ``limit`` characters, marking the cut with an ellipsis.""" 

52 return text if len(text) <= limit else text[: limit - 1] + "…" 

53 

54 

55def failing_validations(validations: Iterable[ValidationResult]) -> list[ValidationResult]: 

56 """Mandatory validation results that did not pass, in their recorded order.""" 

57 return [ 

58 item for item in validations if item.mandatory and item.status is not ResultStatus.PASSED 

59 ] 

60 

61 

62def verification_reason_codes(failing: Sequence[ValidationResult]) -> tuple[str, ...]: 

63 """Reason codes in the form the gate engine uses: ``<validatorId>_<STATUS>``.""" 

64 return tuple(f"{item.validator_id}_{item.status}" for item in failing) 

65 

66 

67class FeedbackBuilder: 

68 def __init__(self, artifacts: LocalArtifactStore) -> None: 

69 self.artifacts = artifacts 

70 

71 def build( 

72 self, 

73 *, 

74 trigger: FeedbackTrigger, 

75 attempt: int, 

76 change_set_digest: str, 

77 gate: FeedbackGate, 

78 validations: Sequence[ValidationResult], 

79 findings: Sequence[Finding], 

80 decision: FeedbackDecision | None = None, 

81 ) -> ProviderFeedback: 

82 ordered = sorted(findings, key=lambda item: _SEVERITY_ORDER.get(item.severity, 5)) 

83 kept = ordered[:FEEDBACK_MAX_FINDINGS] 

84 return ProviderFeedback( 

85 attempt=attempt, 

86 trigger=trigger, 

87 change_set_digest=change_set_digest, 

88 gate=gate, 

89 findings=tuple( 

90 FeedbackFinding( 

91 rule_id=item.rule_id, 

92 severity=item.severity, 

93 validator_id=item.validator_id, 

94 location=item.location, 

95 message=head(item.message), 

96 ) 

97 for item in kept 

98 ), 

99 omitted_findings=len(ordered) - len(kept), 

100 validators=self._validators(failing_validations(validations)), 

101 decision=decision, 

102 ) 

103 

104 def _validators(self, failing: Sequence[ValidationResult]) -> tuple[FeedbackValidator, ...]: 

105 budget = FEEDBACK_TOTAL_CHARS 

106 items: list[FeedbackValidator] = [] 

107 for result in failing: 

108 report = self._report(result) 

109 streams: dict[str, tuple[str, bool]] = {} 

110 for name in ("stdout", "stderr"): 

111 text = self._text(report.get(f"{name}Ref")) 

112 excerpt, cut = tail(text, min(FEEDBACK_STREAM_CHARS, budget)) 

113 budget -= len(excerpt) 

114 streams[name] = (excerpt, cut or bool(report.get(f"{name}Truncated"))) 

115 exit_code = report.get("exitCode") 

116 items.append( 

117 FeedbackValidator( 

118 validator_id=result.validator_id, 

119 status=result.status, 

120 summary=head(result.summary), 

121 exit_code=exit_code if isinstance(exit_code, int) else None, 

122 stdout=streams["stdout"][0], 

123 stderr=streams["stderr"][0], 

124 stdout_truncated=streams["stdout"][1], 

125 stderr_truncated=streams["stderr"][1], 

126 ) 

127 ) 

128 return tuple(items) 

129 

130 def _report(self, result: ValidationResult) -> dict[str, object]: 

131 """The validation report of a command validator (its first evidence reference).""" 

132 try: 

133 value = json.loads(self.artifacts.get(result.evidence_refs[0])) 

134 except (OSError, ValueError, KeyError, IndexError): 

135 return {} 

136 return value if isinstance(value, dict) else {} 

137 

138 def _text(self, uri: object) -> str: 

139 if not isinstance(uri, str): 

140 return "" 

141 try: 

142 return self.artifacts.get(uri).decode("utf-8", "replace") 

143 except (OSError, ValueError, KeyError): 

144 return "" 

145 

146 

147def _pattern_regex(pattern: str) -> re.Pattern[str]: 

148 # A numeric code such as 429 must not match inside a longer number (a line 4290 of a log). 

149 body = re.escape(pattern.strip()) 

150 prefix = r"(?<![0-9])" if pattern.strip()[:1].isdigit() else "" 

151 suffix = r"(?![0-9])" if pattern.strip()[-1:].isdigit() else "" 

152 return re.compile(prefix + body + suffix, re.IGNORECASE) 

153 

154 

155def transient_cause(texts: Iterable[str], patterns: Sequence[str]) -> str | None: 

156 """The first configured pattern found in the provider's streams, or ``None``.""" 

157 compiled = [(pattern, _pattern_regex(pattern)) for pattern in patterns] 

158 for text in texts: 

159 for pattern, regex in compiled: 

160 if regex.search(text): 

161 return pattern 

162 return None