Coverage for src/governed_harness/reporting/trace.py: 92%

74 statements  

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

1from __future__ import annotations 

2 

3import json 

4from typing import Any 

5 

6from governed_harness.domain.models import ( 

7 Execution, 

8 Finding, 

9 GateEvaluation, 

10 HumanDecision, 

11 PhaseExecution, 

12 Retrospective, 

13 Task, 

14 ValidationResult, 

15) 

16from governed_harness.events import StoredEvent 

17from governed_harness.reporting.fingerprint import FINGERPRINT_VERSION, finding_fingerprint 

18from governed_harness.telemetry import MetricValue 

19 

20 

21def _finding_lines(findings: list[dict[str, Any]]) -> list[str]: 

22 if not findings: 22 ↛ 23line 22 didn't jump to line 23 because the condition on line 22 was never true

23 return ["No findings were recorded."] 

24 lines = [] 

25 for finding in findings: 

26 location = finding.get("location") or {} 

27 where = location.get("path") or "execution" 

28 if location.get("startLine"): 

29 where += f":{location['startLine']}" 

30 lines.append( 

31 f"- **{finding['severity']}** `{finding['ruleId']}` at `{where}`: {finding['message']}" 

32 ) 

33 return lines 

34 

35 

36def _gate_lines(gate: dict[str, Any] | None) -> list[str]: 

37 if not gate: 37 ↛ 38line 37 didn't jump to line 38 because the condition on line 37 was never true

38 return ["No gate evaluation has been recorded."] 

39 return [ 

40 f"Automatic gate `{gate['gateEvaluationId']}`: **{gate['status']}**.", 

41 "Reasons: " + ", ".join(f"`{item}`" for item in gate["reasonCodes"]), 

42 ] 

43 

44 

45def _decision_lines(decision: dict[str, Any] | None) -> list[str]: 

46 if not decision: 46 ↛ 47line 46 didn't jump to line 47 because the condition on line 46 was never true

47 return ["No human decision has been recorded."] 

48 return [ 

49 f"Human decision: **{decision['decision']}** by `{decision['actor']['actorId']}` for `{decision['changeSetDigest']}`." 

50 ] 

51 

52 

53def _retrospective_lines(retrospective: dict[str, Any] | None) -> list[str]: 

54 if not retrospective: 54 ↛ 55line 54 didn't jump to line 55 because the condition on line 54 was never true

55 return ["No retrospective has been generated yet."] 

56 return [ 

57 *( 

58 f"- **{recommendation['category']}** ({recommendation['confidence']:.2f}): {recommendation['statement']}" 

59 for recommendation in retrospective["recommendations"] 

60 ), 

61 "", 

62 "Recommendations require human review and were not applied automatically.", 

63 ] 

64 

65 

66class TraceReporter: 

67 def as_dict( 

68 self, 

69 *, 

70 execution: Execution, 

71 task: Task, 

72 phases: list[PhaseExecution], 

73 validations: list[ValidationResult], 

74 findings: list[Finding], 

75 gate: GateEvaluation | None, 

76 decision: HumanDecision | None, 

77 events: list[StoredEvent], 

78 metrics: dict[str, MetricValue], 

79 retrospective: Retrospective | None, 

80 ) -> dict[str, Any]: 

81 return { 

82 "schemaVersion": "1.0", 

83 "execution": execution.model_dump(mode="json", by_alias=True), 

84 "task": task.model_dump(mode="json", by_alias=True), 

85 "phases": [item.model_dump(mode="json", by_alias=True) for item in phases], 

86 "validations": [item.model_dump(mode="json", by_alias=True) for item in validations], 

87 "findings": [item.model_dump(mode="json", by_alias=True) for item in findings], 

88 "gate": gate.model_dump(mode="json", by_alias=True) if gate else None, 

89 "humanDecision": decision.model_dump(mode="json", by_alias=True) if decision else None, 

90 "events": [event.as_dict() for event in events], 

91 "metrics": {key: value.as_dict() for key, value in metrics.items()}, 

92 "retrospective": retrospective.model_dump(mode="json", by_alias=True) 

93 if retrospective 

94 else None, 

95 } 

96 

97 def render_json(self, **kwargs: Any) -> bytes: 

98 return json.dumps( 

99 self.as_dict(**kwargs), indent=2, ensure_ascii=False, sort_keys=True 

100 ).encode("utf-8") 

101 

102 def render_markdown(self, **kwargs: Any) -> bytes: 

103 data = self.as_dict(**kwargs) 

104 execution = data["execution"] 

105 task = data["task"] 

106 lines = [ 

107 f"# Execution trace `{execution['executionId']}`", 

108 "", 

109 f"- **Task:** {task['title']} (`{task['taskId']}`)", 

110 f"- **Status:** `{execution['status']}`", 

111 f"- **Current phase:** `{execution['currentPhase']}`", 

112 f"- **ChangeSet digest:** `{execution.get('changeSetDigest') or 'not available'}`", 

113 f"- **Configuration digest:** `{execution['configurationDigest']}`", 

114 f"- **Workflow digest:** `{execution['workflowDigest']}`", 

115 f"- **Policy digest:** `{execution['policyDigest']}`", 

116 "", 

117 "## Normative phases", 

118 "", 

119 "| Phase | Attempt | Status | Summary |", 

120 "|---|---:|---|---|", 

121 ] 

122 for phase in data["phases"]: 

123 summary = str(phase.get("summary", "")).replace("|", "\\|") 

124 lines.append( 

125 f"| `{phase['phaseId']}` | {phase['attempt']} | `{phase['status']}` | {summary} |" 

126 ) 

127 lines.extend( 

128 [ 

129 "", 

130 "## Validation results", 

131 "", 

132 "| Validator | Mandatory | Status | Kind | Summary |", 

133 "|---|:---:|---|---|---|", 

134 ] 

135 ) 

136 for result in data["validations"]: 

137 summary = str(result["summary"]).replace("|", "\\|") 

138 lines.append( 

139 f"| `{result['validatorId']}` | {result['mandatory']} | `{result['status']}` | `{result['kind']}` | {summary} |" 

140 ) 

141 lines.extend(["", "## Findings", ""]) 

142 lines.extend(_finding_lines(data["findings"])) 

143 lines.extend(["", "## Gate and human decision", ""]) 

144 lines.extend(_gate_lines(data["gate"])) 

145 lines.extend(_decision_lines(data["humanDecision"])) 

146 lines.extend( 

147 [ 

148 "", 

149 "## Operational metrics", 

150 "", 

151 "| Metric | Value | Unit | Quality |", 

152 "|---|---:|---|---|", 

153 ] 

154 ) 

155 for key, metric in sorted(data["metrics"].items()): 

156 value = "N/A" if metric["value"] is None else metric["value"] 

157 lines.append(f"| `{key}` | {value} | {metric['unit']} | `{metric['quality']}` |") 

158 lines.extend(["", "## Retrospective", ""]) 

159 lines.extend(_retrospective_lines(data["retrospective"])) 

160 lines.extend(["", "## Event chain", ""]) 

161 for event in data["events"]: 

162 lines.append(f"{event['sequence']}. `{event['eventType']}` — `{event['eventDigest']}`") 

163 return ("\n".join(lines) + "\n").encode("utf-8") 

164 

165 def render_sarif(self, findings: list[Finding]) -> bytes: 

166 rules: dict[str, dict[str, Any]] = {} 

167 results = [] 

168 level_map = { 

169 "INFO": "note", 

170 "LOW": "note", 

171 "MEDIUM": "warning", 

172 "HIGH": "error", 

173 "CRITICAL": "error", 

174 } 

175 for finding in findings: 

176 rules.setdefault( 

177 finding.rule_id, 

178 { 

179 "id": finding.rule_id, 

180 "name": finding.rule_id, 

181 "shortDescription": {"text": finding.category}, 

182 "help": {"text": finding.recommendation or finding.message}, 

183 }, 

184 ) 

185 result: dict[str, Any] = { 

186 "ruleId": finding.rule_id, 

187 "level": level_map[finding.severity], 

188 "message": {"text": finding.message}, 

189 # Stable across attempts and runs (rule, validator, path and message without 

190 # positions), so code-scanning tools can track one problem over time. 

191 "partialFingerprints": {FINGERPRINT_VERSION: finding_fingerprint(finding)}, 

192 "properties": { 

193 "findingId": finding.finding_id, 

194 "executionId": finding.execution_id, 

195 "validatorId": finding.validator_id, 

196 "severity": finding.severity.value, 

197 "category": finding.category, 

198 }, 

199 } 

200 if finding.location and finding.location.path: 

201 result["locations"] = [ 

202 { 

203 "physicalLocation": { 

204 "artifactLocation": {"uri": finding.location.path}, 

205 "region": { 

206 "startLine": finding.location.start_line or 1, 

207 "endLine": finding.location.end_line 

208 or finding.location.start_line 

209 or 1, 

210 }, 

211 } 

212 } 

213 ] 

214 results.append(result) 

215 sarif = { 

216 "$schema": "https://json.schemastore.org/sarif-2.1.0.json", 

217 "version": "2.1.0", 

218 "runs": [ 

219 { 

220 "tool": { 

221 "driver": {"name": "Governed Agent Harness", "rules": list(rules.values())} 

222 }, 

223 "results": results, 

224 } 

225 ], 

226 } 

227 return json.dumps(sarif, indent=2, sort_keys=True).encode("utf-8")