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

1"""``harness pr publish``: the decision brief and the SARIF report on a pull request. 

2 

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: 

7 

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. 

11 

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.""" 

15 

16from __future__ import annotations 

17 

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 

28 

29from governed_harness.configuration.models import PublisherConfig 

30from governed_harness.domain.errors import ConfigurationError, HarnessError 

31 

32MAX_COMMENT_CHARS = 60_000 

33"""GitHub accepts 65,536 characters in a comment; the brief is cut before that.""" 

34_TIMEOUT_SECONDS = 30 

35 

36 

37class PublishError(HarnessError): 

38 """The publisher could not reach the platform or the platform refused a request.""" 

39 

40 

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.""" 

44 

45 

46@dataclass 

47class GhTransport: 

48 """``gh api``: the GitHub CLI's own authentication.""" 

49 

50 executable: str = "gh" 

51 

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 

73 

74 

75@dataclass 

76class RestTransport: 

77 """HTTPS with a bearer token from the environment.""" 

78 

79 api_url: str 

80 token: str 

81 

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 

105 

106 

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) 

116 

117 

118def marker(run_id: str) -> str: 

119 return f"<!-- governed-harness:{run_id} -->" 

120 

121 

122def _cell(value: Any) -> str: 

123 return str(value).replace("|", "\\|").replace("\n", " ").strip() 

124 

125 

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 ] 

138 

139 

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 ] 

155 

156 

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 

176 

177 

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 ] 

192 

193 

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"]), ""] 

198 

199 

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 ] 

212 

213 

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 ] 

227 

228 

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 

264 

265 

266@dataclass 

267class GitHubPublisher: 

268 transport: Transport 

269 repository: str 

270 

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")} 

302 

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} 

329 

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 }