Coverage for src/governed_harness/delivery/publisher.py: 72%
156 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
1"""``harness pr publish``: the decision brief and the SARIF report on a pull request.
3A publisher posts (or updates) one comment per run on the pull request, marked with
4``<!-- governed-harness:<run id> -->`` so that publishing again edits the same comment, and
5uploads the run's findings as SARIF to code scanning. GitHub is the first publisher; it talks
6to the REST API through a transport:
8* ``gh``: the GitHub CLI (``gh api``), with the authentication the CLI already has;
9* ``api``: HTTPS with a token read from an environment variable (``GITHUB_TOKEN`` by default),
10 never from a file or the configuration.
12The comment carries the brief (what was asked, what changed, gate, risks, what was and was not
13verified, decisions) and no output of a validator or the agent. Nothing here decides: a comment
14or a SARIF upload is information for the people who review the pull request."""
16from __future__ import annotations
18import base64
19import gzip
20import json
21import os
22import shutil
23import subprocess # nosec B404 - the forge CLI with a fixed argv, no shell
24import urllib.error
25import urllib.request
26from dataclasses import dataclass
27from typing import Any, Protocol
29from governed_harness.configuration.models import PublisherConfig
30from governed_harness.domain.errors import ConfigurationError, HarnessError
32MAX_COMMENT_CHARS = 60_000
33"""GitHub accepts 65,536 characters in a comment; the brief is cut before that."""
34_TIMEOUT_SECONDS = 30
37class PublishError(HarnessError):
38 """The publisher could not reach the platform or the platform refused a request."""
41class Transport(Protocol):
42 def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
43 """Send a REST request to ``path`` and return the decoded response."""
46@dataclass
47class GhTransport:
48 """``gh api``: the GitHub CLI's own authentication."""
50 executable: str = "gh"
52 def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
53 if shutil.which(self.executable) is None:
54 raise PublishError(f"{self.executable} is not on PATH; use the api transport")
55 args = [self.executable, "api", "--method", method, path]
56 if body is not None:
57 args += ["--input", "-"]
58 try:
59 result = subprocess.run( # nosec B603 - fixed argv of the forge CLI checked on PATH, no shell
60 args,
61 input=json.dumps(body).encode("utf-8") if body is not None else None,
62 capture_output=True,
63 check=False,
64 timeout=_TIMEOUT_SECONDS,
65 )
66 except (OSError, subprocess.SubprocessError) as error:
67 raise PublishError(f"gh api could not run: {error}") from error
68 if result.returncode != 0:
69 message = result.stderr.decode("utf-8", "replace").strip()[:300]
70 raise PublishError(f"gh api {method} {path} failed: {message}")
71 text = result.stdout.decode("utf-8", "replace").strip()
72 return json.loads(text) if text else None
75@dataclass
76class RestTransport:
77 """HTTPS with a bearer token from the environment."""
79 api_url: str
80 token: str
82 def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
83 url = f"{self.api_url}/{path.lstrip('/')}"
84 data = json.dumps(body).encode("utf-8") if body is not None else None
85 request = urllib.request.Request( # noqa: S310 - the URL is https (validated in config)
86 url,
87 data=data,
88 method=method,
89 headers={
90 "Accept": "application/vnd.github+json",
91 "Authorization": f"Bearer {self.token}",
92 "X-GitHub-Api-Version": "2022-11-28",
93 "Content-Type": "application/json",
94 "User-Agent": "governed-harness",
95 },
96 )
97 try:
98 with urllib.request.urlopen(request, timeout=_TIMEOUT_SECONDS) as response: # noqa: S310 # nosec B310
99 text = response.read().decode("utf-8", "replace")
100 except urllib.error.HTTPError as error:
101 raise PublishError(f"{method} {path} returned HTTP {error.code}") from error
102 except OSError as error: # urllib.error.URLError is an OSError
103 raise PublishError(f"{method} {path} failed: {error}") from error
104 return json.loads(text) if text.strip() else None
107def transport_for(config: PublisherConfig) -> Transport:
108 if config.transport == "gh": 108 ↛ 109line 108 didn't jump to line 109 because the condition on line 108 was never true
109 return GhTransport()
110 token = os.environ.get(config.token_env)
111 if not token:
112 raise ConfigurationError(
113 f"the api transport reads the token from {config.token_env}, which is not set"
114 )
115 return RestTransport(config.api_url, token)
118def marker(run_id: str) -> str:
119 return f"<!-- governed-harness:{run_id} -->"
122def _cell(value: Any) -> str:
123 return str(value).replace("|", "\\|").replace("\n", " ").strip()
126def _criteria_lines(asked: dict[str, Any]) -> list[str]:
127 if not asked.get("acceptanceCriteria"): 127 ↛ 128line 127 didn't jump to line 128 because the condition on line 127 was never true
128 return []
129 return [
130 "### Acceptance criteria",
131 "",
132 *(
133 f"- {_cell(item['criterionId'])} [{item.get('priority', 'MUST')}]: {_cell(item['text'])}"
134 for item in asked["acceptanceCriteria"]
135 ),
136 "",
137 ]
140def _changed_lines(changed: dict[str, Any]) -> list[str]:
141 if not changed.get("files"): 141 ↛ 142line 141 didn't jump to line 142 because the condition on line 141 was never true
142 return []
143 return [
144 "### Changed files",
145 "",
146 "| File | Status | + | - |",
147 "|---|---|---:|---:|",
148 *(
149 f"| `{_cell(item['path'])}` | {item['status']} | {item['additions']} | "
150 f"{item['deletions']} |"
151 for item in changed["files"]
152 ),
153 "",
154 ]
157def _finding_lines(risks: list[dict[str, Any]]) -> list[str]:
158 if not risks: 158 ↛ 159line 158 didn't jump to line 159 because the condition on line 158 was never true
159 return []
160 lines = [
161 "### Findings",
162 "",
163 "| Severity | Rule | Location | Message |",
164 "|---|---|---|---|",
165 ]
166 lines += [
167 f"| {item['severity']}{' (blocking)' if item.get('blocking') else ''} | "
168 f"`{_cell(item['ruleId'])}` | {_cell(item.get('location') or '')} | "
169 f"{_cell(item['message'])[:300]} |"
170 for item in risks[:50]
171 ]
172 if len(risks) > 50: 172 ↛ 173line 172 didn't jump to line 173 because the condition on line 172 was never true
173 lines.append(f"| | | | {len(risks) - 50} more finding(s) in the SARIF report |")
174 lines.append("")
175 return lines
178def _verified_lines(brief: dict[str, Any]) -> list[str]:
179 verified = (brief.get("verified") or {}).get("validations") or []
180 if not verified: 180 ↛ 181line 180 didn't jump to line 181 because the condition on line 180 was never true
181 return []
182 return [
183 "### Verified",
184 "",
185 *(
186 f"- `{item['validatorId']}`{'' if item['mandatory'] else ' (optional)'}: "
187 f"{item['status']}"
188 for item in verified
189 ),
190 "",
191 ]
194def _not_verified_lines(brief: dict[str, Any]) -> list[str]:
195 if not brief.get("notVerified"): 195 ↛ 196line 195 didn't jump to line 196 because the condition on line 195 was never true
196 return []
197 return ["### Not verified", "", *(f"- {_cell(item)}" for item in brief["notVerified"]), ""]
200def _provenance_lines(brief: dict[str, Any]) -> list[str]:
201 if not brief.get("provenance"): 201 ↛ 202line 201 didn't jump to line 202 because the condition on line 201 was never true
202 return []
203 provenance = brief["provenance"]
204 return [
205 "### Provenance",
206 "",
207 f"{provenance['agentFiles']} file(s) written by an agent invocation, "
208 f"{provenance['outOfBandFiles']} changed out of band: "
209 + (", ".join(f"`{path}`" for path in provenance["outOfBandPaths"]) or "none"),
210 "",
211 ]
214def _decision_lines(decisions: list[dict[str, Any]]) -> list[str]:
215 if not decisions:
216 return []
217 return [
218 "### Decisions",
219 "",
220 *(
221 f"- {item['decision']} by `{_cell(item['actorId'])}` at {item['decidedAt']} on "
222 f"`{item['changeSetDigest']}`: {_cell(item['rationale'])[:500]}"
223 for item in decisions
224 ),
225 "",
226 ]
229def render_brief_markdown(brief: dict[str, Any]) -> str:
230 """The decision brief (``harness review``) as GitHub Markdown."""
231 run = brief["run"]
232 asked = brief["asked"]
233 changed = brief["changed"]
234 gate = brief.get("gate")
235 lines = [
236 marker(run["executionId"]),
237 f"## Governed Agent Harness: {_cell(asked['title'])}",
238 "",
239 f"Run `{run['executionId']}` (task `{run['taskId']}`): **{run['status']}** in "
240 f"`{run['currentPhase']}`"
241 + (" (waiting for a human decision)" if run.get("awaitingDecision") else ""),
242 "",
243 f"ChangeSet digest: `{run.get('changeSetDigest')}`",
244 "",
245 ]
246 if gate: 246 ↛ 249line 246 didn't jump to line 249 because the condition on line 246 was always true
247 reasons = ", ".join(f"`{item['code']}`" for item in gate.get("reasons", [])) or "none"
248 lines += [f"Gate: **{gate['status']}** ({reasons})", ""]
249 lines += _criteria_lines(asked)
250 lines += _changed_lines(changed)
251 lines += _finding_lines(brief.get("risks") or [])
252 lines += _verified_lines(brief)
253 lines += _not_verified_lines(brief)
254 lines += _provenance_lines(brief)
255 lines += _decision_lines(brief.get("decisions") or [])
256 lines.append(
257 "Verify that the merged tree is the approved ChangeSet: "
258 "`harness verify-approval --base <base> --head <head> --bundle <bundle>`."
259 )
260 text = "\n".join(lines) + "\n"
261 if len(text) > MAX_COMMENT_CHARS: 261 ↛ 262line 261 didn't jump to line 262 because the condition on line 261 was never true
262 text = text[: MAX_COMMENT_CHARS - 80] + "\n\n(cut: the brief is longer than a comment)\n"
263 return text
266@dataclass
267class GitHubPublisher:
268 transport: Transport
269 repository: str
271 def _comment(self, pull_request: int, run_id: str, body: str) -> dict[str, Any]:
272 repo = self.repository
273 existing = None
274 page = 1
275 while existing is None and page <= 10:
276 comments = self.transport.request(
277 "GET", f"repos/{repo}/issues/{pull_request}/comments?per_page=100&page={page}"
278 )
279 if not isinstance(comments, list) or not comments:
280 break
281 existing = next(
282 (
283 item
284 for item in comments
285 if isinstance(item, dict) and marker(run_id) in str(item.get("body", ""))
286 ),
287 None,
288 )
289 page += 1
290 if existing is not None:
291 result = self.transport.request(
292 "PATCH", f"repos/{repo}/issues/comments/{existing['id']}", {"body": body}
293 )
294 action = "updated"
295 else:
296 result = self.transport.request(
297 "POST", f"repos/{repo}/issues/{pull_request}/comments", {"body": body}
298 )
299 action = "created"
300 result = result if isinstance(result, dict) else {}
301 return {"action": action, "id": result.get("id"), "url": result.get("html_url")}
303 def _sarif(self, pull_request: int, sarif: bytes, commit_sha: str | None) -> dict[str, Any]:
304 repo = self.repository
305 if commit_sha is None: 305 ↛ 310line 305 didn't jump to line 310 because the condition on line 305 was always true
306 pull = self.transport.request("GET", f"repos/{repo}/pulls/{pull_request}")
307 commit_sha = (
308 ((pull or {}).get("head") or {}).get("sha") if isinstance(pull, dict) else None
309 )
310 if not commit_sha: 310 ↛ 311line 310 didn't jump to line 311 because the condition on line 310 was never true
311 return {"status": "SKIPPED", "reason": "the head commit of the pull request is unknown"}
312 try:
313 result = self.transport.request(
314 "POST",
315 f"repos/{repo}/code-scanning/sarifs",
316 {
317 "commit_sha": commit_sha,
318 "ref": f"refs/pull/{pull_request}/head",
319 "sarif": base64.b64encode(gzip.compress(sarif, mtime=0)).decode("ascii"),
320 "tool_name": "governed-harness",
321 },
322 )
323 except PublishError as error:
324 # Code scanning may be unavailable for the repository (plan, permissions); the
325 # comment stays published and the report says why the upload failed.
326 return {"status": "FAILED", "reason": str(error), "commitSha": commit_sha}
327 result = result if isinstance(result, dict) else {}
328 return {"status": "UPLOADED", "id": result.get("id"), "commitSha": commit_sha}
330 def publish(
331 self,
332 *,
333 pull_request: int,
334 run_id: str,
335 brief_markdown: str,
336 sarif: bytes | None,
337 commit_sha: str | None = None,
338 ) -> dict[str, Any]:
339 comment = self._comment(pull_request, run_id, brief_markdown)
340 upload = (
341 self._sarif(pull_request, sarif, commit_sha)
342 if sarif is not None
343 else {"status": "SKIPPED", "reason": "SARIF upload disabled"}
344 )
345 return {
346 "publisher": "github",
347 "repository": self.repository,
348 "pullRequest": pull_request,
349 "runId": run_id,
350 "comment": comment,
351 "sarif": upload,
352 }