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
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3import json
4from typing import Any
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
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
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 ]
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 ]
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 ]
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 }
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")
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")
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")