Coverage for src/governed_harness/application/review_code.py: 83%

357 statements  

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

1"""``harness review-code`` and the ``harness review`` subcommands outside governed runs (#57). 

2 

3* ``review_code``: resolve the base (explicit, then the pull or merge request base the CI 

4 exposes, then the branch convention, then the merge base with the default branch; in hook mode 

5 the base is fetched first and a failed fetch aborts), take the diff (``manual`` and ``hook``: 

6 base..head; ``staged``: the index against ``HEAD``), run the panel and, when it passes, record 

7 the evidence as a Git ref and, when asked, one pull or merge request comment per result; 

8* ``verify_review``: check the evidence ref of a commit without calling any model (CI); 

9* ``install_hook``: a ``pre-push`` hook that runs ``harness review-code --mode hook``; 

10* ``rules_report`` and ``sync_rules``: the catalog and the generated blocks of the reviewers; 

11* ``review_variance``: the same review N times without cache, to measure its variance.""" 

12 

13from __future__ import annotations 

14 

15import json 

16import os 

17import re 

18import shlex 

19import shutil 

20import stat 

21from collections import Counter 

22from dataclasses import dataclass 

23from itertools import combinations 

24from pathlib import Path 

25from typing import Any 

26 

27from governed_harness import __version__ 

28from governed_harness.configuration.models import ResolvedConfiguration 

29from governed_harness.delivery.vcs import Git 

30from governed_harness.domain.enums import ActorType, PhaseId 

31from governed_harness.domain.errors import ConfigurationError, PolicyViolationError 

32from governed_harness.domain.models import Actor, Provenance 

33from governed_harness.evidence.hashing import sha256_bytes 

34from governed_harness.review.cache import CACHE_DIRECTORY, ReviewCache 

35from governed_harness.review.diff import diff_hash 

36from governed_harness.review.invoke import ProviderInvoker 

37from governed_harness.review.panel import PanelInputs, PanelReport, run_panel 

38from governed_harness.review.project import ( 

39 ReviewSetup, 

40 consistency_runner, 

41 linter_runner, 

42 panel_context, 

43 review_setup, 

44 reviewer_route, 

45) 

46from governed_harness.review.providers import build_reviewer_provider, mcp_digest, mcp_servers 

47from governed_harness.review.reviewers import sync_blocks 

48from governed_harness.runtime.process_runner import SafeProcessRunner 

49 

50MODES = ("hook", "manual", "staged") 

51REF_PREFIX = "refs/harness/review" 

52REF_KINDS = {"PASS": "pass", "PASS_WARN": "pass-warn"} # nosec B105 - git ref names, not passwords 

53EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904" 

54HOOK_MARKER = "# governed-harness review hook (harness review hook install)" 

55PULL_REQUEST_BASE_ENV = ( 

56 "GITHUB_BASE_REF", 

57 "CI_MERGE_REQUEST_TARGET_BRANCH_NAME", 

58 "BITBUCKET_PR_DESTINATION_BRANCH", 

59 "SYSTEM_PULLREQUEST_TARGETBRANCH", 

60) 

61"""Variables in which GitHub (and Gitea) Actions, GitLab CI, Bitbucket Pipelines and Azure 

62Pipelines expose the base branch of the pull or merge request being built.""" 

63PULL_REQUEST_NUMBER_ENV = ( 

64 "CI_MERGE_REQUEST_IID", 

65 "BITBUCKET_PR_ID", 

66 "SYSTEM_PULLREQUEST_PULLREQUESTNUMBER", 

67 "SYSTEM_PULLREQUEST_PULLREQUESTID", 

68) 

69_DEFAULT_TARGET = "@default" 

70"""The target of a branch convention that stands for the default branch of the repository.""" 

71BUILTIN_CONVENTIONS: tuple[tuple[str, str], ...] = ( 

72 ("release/*", _DEFAULT_TARGET), 

73 ("hotfix/*", _DEFAULT_TARGET), 

74 ("*", "develop"), 

75) 

76"""Branch conventions applied after ``review.panel.baseBranches``: release and hotfix branches 

77against the default branch, every other branch against ``develop`` when it exists.""" 

78REVIEW_EXECUTION_PREFIX = "review" 

79_COMMIT = re.compile(r"^[0-9a-f]{7,64}$") 

80 

81 

82class ReviewAborted(PolicyViolationError): 

83 """A review that cannot run as asked (hook mode without its base).""" 

84 

85 exit_code = 6 

86 

87 

88@dataclass(frozen=True) 

89class BaseResolution: 

90 ref: str 

91 sha: str 

92 source: str 

93 fetched: bool = False 

94 

95 def as_dict(self) -> dict[str, Any]: 

96 return {"ref": self.ref, "sha": self.sha, "source": self.source, "fetched": self.fetched} 

97 

98 

99# ----- base resolution -------------------------------------------------------------------------- 

100def _ref_exists(git: Git, ref: str) -> bool: 

101 return git.resolve(ref) is not None 

102 

103 

104def _has_remote(git: Git, remote: str = "origin") -> bool: 

105 return git.run("remote", "get-url", remote, check=False).returncode == 0 

106 

107 

108def default_branch(git: Git) -> str | None: 

109 head = git.run("symbolic-ref", "--quiet", "refs/remotes/origin/HEAD", check=False) 

110 if head.returncode == 0: 110 ↛ 111line 110 didn't jump to line 111 because the condition on line 110 was never true

111 name = head.stdout.decode().strip().removeprefix("refs/remotes/origin/") 

112 if name: 

113 return name 

114 for candidate in ("main", "master", "trunk", "develop"): 114 ↛ 119line 114 didn't jump to line 119 because the loop on line 114 didn't complete

115 if _ref_exists(git, f"refs/remotes/origin/{candidate}") or _ref_exists( 

116 git, f"refs/heads/{candidate}" 

117 ): 

118 return candidate 

119 return None 

120 

121 

122def _convention(branch: str, configured: dict[str, str] | None, git: Git) -> str | None: 

123 import fnmatch 

124 

125 for pattern, target in (*(configured or {}).items(), *BUILTIN_CONVENTIONS): 

126 if not fnmatch.fnmatchcase(branch, pattern): 

127 continue 

128 name = default_branch(git) if target == _DEFAULT_TARGET else target 

129 if ( 129 ↛ 137line 129 didn't jump to line 137 because the condition on line 129 was never true

130 name 

131 and name != branch 

132 and ( 

133 _ref_exists(git, f"refs/heads/{name}") 

134 or _ref_exists(git, f"refs/remotes/origin/{name}") 

135 ) 

136 ): 

137 return name 

138 return None 

139 

140 

141def _fetch(git: Git, branch: str) -> None: 

142 result = git.run( 

143 "fetch", 

144 "--quiet", 

145 "--no-tags", 

146 "origin", 

147 f"+refs/heads/{branch}:refs/remotes/origin/{branch}", 

148 check=False, 

149 ) 

150 if result.returncode != 0: 

151 message = result.stderr.decode("utf-8", "replace").strip() or "no message" 

152 raise ReviewAborted( 

153 f"hook mode: the base branch {branch} could not be fetched from origin ({message}); " 

154 "the review is aborted" 

155 ) 

156 

157 

158def _pull_request_base() -> tuple[str, str] | None: 

159 """The base branch the CI exposes for the pull or merge request being built, if any.""" 

160 for name in PULL_REQUEST_BASE_ENV: 

161 value = os.environ.get(name, "").strip().removeprefix("refs/heads/") 

162 if value: 162 ↛ 163line 162 didn't jump to line 163 because the condition on line 162 was never true

163 return value, f"pull-request:{name}" 

164 return None 

165 

166 

167def _base_candidates( 

168 git: Git, explicit: str | None, configured: dict[str, str] | None 

169) -> list[tuple[str, str]]: 

170 """``(name, source)`` of every base to try, in order; all of them are gathered before the 

171 first one is tried.""" 

172 candidates: list[tuple[str, str]] = [] 

173 if explicit: 

174 candidates.append((explicit, "explicit")) 

175 pull_request = _pull_request_base() 

176 if pull_request is not None: 176 ↛ 177line 176 didn't jump to line 177 because the condition on line 176 was never true

177 candidates.append(pull_request) 

178 branch = git.run("rev-parse", "--abbrev-ref", "HEAD", check=False).stdout.decode().strip() 

179 if branch and branch != "HEAD": 179 ↛ 183line 179 didn't jump to line 183 because the condition on line 179 was always true

180 convention = _convention(branch, configured, git) 

181 if convention: 181 ↛ 182line 181 didn't jump to line 182 because the condition on line 181 was never true

182 candidates.append((convention, "branch-convention")) 

183 fallback = default_branch(git) 

184 if fallback and fallback != branch: 184 ↛ 186line 184 didn't jump to line 186 because the condition on line 184 was always true

185 candidates.append((fallback, "merge-base")) 

186 return candidates 

187 

188 

189def _resolve_candidate(git: Git, mode: str, name: str, source: str) -> BaseResolution | None: 

190 """One candidate base: fetched first in hook mode, then its merge base with ``HEAD``; 

191 ``None`` to try the next one. An explicit base that does not resolve is an error.""" 

192 fetched = False 

193 is_branch = source != "explicit" or not _COMMIT.match(name) 

194 if mode == "hook" and is_branch: 

195 if not _has_remote(git): 195 ↛ 196line 195 didn't jump to line 196 because the condition on line 195 was never true

196 raise ReviewAborted( 

197 "hook mode: there is no origin remote to fetch the base from; the review is aborted" 

198 ) 

199 _fetch(git, name) 

200 fetched = True 

201 ref = name 

202 if is_branch and _ref_exists(git, f"refs/remotes/origin/{name}"): 

203 ref = f"origin/{name}" 

204 if not _ref_exists(git, ref): 204 ↛ 205line 204 didn't jump to line 205 because the condition on line 204 was never true

205 if source == "explicit": 

206 raise ConfigurationError(f"base {name!r} does not resolve to a commit") 

207 return None 

208 merge = git.run("merge-base", "HEAD", ref, check=False) 

209 sha = merge.stdout.decode().strip() 

210 if merge.returncode != 0 or not sha: 210 ↛ 211line 210 didn't jump to line 211 because the condition on line 210 was never true

211 return None 

212 return BaseResolution(ref, sha, source, fetched) 

213 

214 

215def resolve_base( 

216 git: Git, mode: str, explicit: str | None, configured: dict[str, str] | None 

217) -> BaseResolution: 

218 """explicit, then the pull or merge request base, then the branch convention, then the 

219 merge base with the default branch.""" 

220 if mode == "staged": 

221 head = git.resolve("HEAD") 

222 return BaseResolution("HEAD", head or EMPTY_TREE, "staged") 

223 for name, source in _base_candidates(git, explicit, configured): 223 ↛ 227line 223 didn't jump to line 227 because the loop on line 223 didn't complete

224 resolution = _resolve_candidate(git, mode, name, source) 

225 if resolution is not None: 225 ↛ 223line 225 didn't jump to line 223 because the condition on line 225 was always true

226 return resolution 

227 raise ConfigurationError( 

228 "no base to review against: pass --base, or create the default branch (main) or the " 

229 "convention's base branch" 

230 ) 

231 

232 

233def _diff_args() -> tuple[str, ...]: 

234 return ( 

235 "diff", 

236 "--no-color", 

237 "--no-ext-diff", 

238 "--no-renames", 

239 "--src-prefix=a/", 

240 "--dst-prefix=b/", 

241 "-U3", 

242 ) 

243 

244 

245def collect_diff(git: Git, mode: str, base: BaseResolution, head_ref: str) -> tuple[str, str]: 

246 """The diff to review and the head it is bound to (a commit, or ``tree:SHA`` of the 

247 index).""" 

248 if mode == "staged": 

249 tree = git.text("write-tree") 

250 diff = git.run(*_diff_args(), "--cached", base.sha).stdout.decode("utf-8", "replace") 

251 return diff, f"tree:{tree}" 

252 head = git.resolve(head_ref) 

253 if head is None: 253 ↛ 254line 253 didn't jump to line 254 because the condition on line 253 was never true

254 raise ConfigurationError(f"head {head_ref!r} does not resolve to a commit") 

255 diff = git.run(*_diff_args(), base.sha, head).stdout.decode("utf-8", "replace") 

256 return diff, head 

257 

258 

259# ----- running the panel ------------------------------------------------------------------------ 

260def _invoker( 

261 resolved: ResolvedConfiguration, 

262 services: Any, 

263 setup: ReviewSetup, 

264 execution_id: str, 

265) -> ProviderInvoker: 

266 workspace = resolved.workspace_root 

267 servers = mcp_servers(workspace, setup.settings.mcp_servers) 

268 runtime = resolved.project.runtime 

269 

270 def build(provider_id: str) -> Any: 

271 built = build_reviewer_provider( 

272 resolved, 

273 provider_id, 

274 workspace=workspace, 

275 protected=(), 

276 allow_network=True, 

277 ) 

278 return built if isinstance(built, str) else built.built 

279 

280 from governed_harness.capabilities import grants_from_rules 

281 

282 return ProviderInvoker( 

283 workspace=workspace, 

284 artifacts=services.artifacts, 

285 runner=SafeProcessRunner(workspace), 

286 provenance=Provenance( 

287 actor=Actor(actor_type=ActorType.HARNESS, actor_id="harness.review", version="1"), 

288 core_version=__version__, 

289 ), 

290 build=build, 

291 grants_for=lambda actor: grants_from_rules( 

292 execution_id, actor, resolved.effective_capabilities 

293 ), 

294 execution_id=execution_id, 

295 phase_id=PhaseId.INDEPENDENT_REVIEW, 

296 default_timeout=min(runtime.command_timeout_seconds, 3600), 

297 max_output_bytes=runtime.max_output_bytes, 

298 mcp_servers=servers, 

299 ) 

300 

301 

302def panel_inputs( 

303 resolved: ResolvedConfiguration, 

304 services: Any, 

305 *, 

306 mode: str, 

307 diff_text: str, 

308 base: str | None, 

309 head: str | None, 

310 provider: str | None, 

311 fallback: str | None, 

312 model: str | None, 

313 skip: tuple[str, ...], 

314 use_cache: bool, 

315 setup: ReviewSetup | None = None, 

316) -> PanelInputs: 

317 setup = setup or review_setup(resolved) 

318 settings = setup.settings 

319 workspace = resolved.workspace_root 

320 project = resolved.project 

321 review = project.review 

322 reviewer_config = review.reviewer if review is not None else None 

323 provider_id = ( 

324 provider 

325 or settings.provider 

326 or (reviewer_config.provider if reviewer_config else None) 

327 or project.agent_provider 

328 ) 

329 if provider_id == "session": 329 ↛ 330line 329 didn't jump to line 330 because the condition on line 329 was never true

330 provider_id = "simulated" 

331 execution_id = f"{REVIEW_EXECUTION_PREFIX}-{sha256_bytes(diff_text.encode())[7:19]}" 

332 cache_settings = settings.effective_cache 

333 cache = ( 

334 ReviewCache( 

335 workspace / CACHE_DIRECTORY, 

336 ttl_seconds=cache_settings.ttl_seconds, 

337 max_entries=cache_settings.limit, 

338 ) 

339 if use_cache and cache_settings.on 

340 else None 

341 ) 

342 runner = SafeProcessRunner(workspace) 

343 servers = mcp_servers(workspace, settings.mcp_servers) 

344 untrusted, notice = panel_context(resolved, workspace) 

345 return PanelInputs( 

346 workspace=workspace, 

347 diff_text=diff_text, 

348 mode=mode, 

349 catalog=setup.catalog, 

350 reviewers=setup.reviewers, 

351 settings=settings, 

352 provider=provider_id, 

353 invoker=_invoker(resolved, services, setup, execution_id), 

354 route=reviewer_route(resolved), 

355 runner_version=__version__, 

356 base=base, 

357 head=head, 

358 fallback=fallback or settings.fallback_provider, 

359 forced_model=model, 

360 skip=skip, 

361 packs=setup.packs or None, 

362 cache=cache, 

363 consistency=consistency_runner(resolved, workspace, runner, execution_id=execution_id), 

364 linters=linter_runner(resolved, setup, workspace, runner, execution_id=execution_id), 

365 mcp={"mcpServers": servers, "digest": mcp_digest(servers)}, 

366 extra=untrusted, 

367 untrusted_notice=notice, 

368 ) 

369 

370 

371# ----- evidence refs ---------------------------------------------------------------------------- 

372def report_json(report: dict[str, Any]) -> bytes: 

373 return json.dumps(report, sort_keys=True, indent=2, ensure_ascii=False).encode("utf-8") 

374 

375 

376def write_evidence_ref(git: Git, report: PanelReport) -> str | None: 

377 kind = REF_KINDS.get(report.verdict) 

378 head = report.head 

379 if kind is None or not head or head.startswith("tree:"): 

380 return None 

381 blob = git.text("hash-object", "-w", "--stdin", stdin=report_json(report.as_dict())) 

382 ref = f"{REF_PREFIX}/{kind}/{head}" 

383 git.run("update-ref", ref, blob) 

384 for other in REF_KINDS.values(): 

385 if other != kind: 

386 git.run("update-ref", "-d", f"{REF_PREFIX}/{other}/{head}", check=False) 

387 return ref 

388 

389 

390def _evidence_ref(git: Git, commit: str) -> tuple[str, str] | None: 

391 """``(verdict, ref)`` of the first evidence ref the commit has, in ``REF_KINDS`` order.""" 

392 for verdict, kind in REF_KINDS.items(): 392 ↛ 399line 392 didn't jump to line 399 because the loop on line 392 didn't complete

393 ref = f"{REF_PREFIX}/{kind}/{commit}" 

394 if ( 394 ↛ 392line 394 didn't jump to line 392 because the condition on line 394 was always true

395 git.resolve(ref) is not None 

396 or git.run("rev-parse", "--verify", "--quiet", ref, check=False).returncode == 0 

397 ): 

398 return verdict, ref 

399 return None 

400 

401 

402def verify_evidence(git: Git, sha: str) -> dict[str, Any]: 

403 """Check the review evidence of a commit without calling any model: the ref exists, its 

404 report is bound to the commit, its digest is intact, its verdict matches the ref and its 

405 diff is the diff between its base and the commit.""" 

406 commit = git.resolve(sha) 

407 problems: list[str] = [] 

408 result: dict[str, Any] = {"sha": sha, "commit": commit} 

409 if commit is None: 409 ↛ 410line 409 didn't jump to line 410 because the condition on line 409 was never true

410 return {**result, "valid": False, "problems": [f"{sha} is not a commit"]} 

411 found = _evidence_ref(git, commit) 

412 if found is None: 412 ↛ 413line 412 didn't jump to line 413 because the condition on line 412 was never true

413 return {**result, "valid": False, "problems": ["no review evidence ref for the commit"]} 

414 verdict, ref = found 

415 result["ref"] = ref 

416 try: 

417 report = json.loads(git.run("cat-file", "blob", ref).stdout.decode("utf-8")) 

418 except ValueError as error: 

419 return {**result, "valid": False, "problems": [f"the report is not JSON: {error}"]} 

420 result["verdict"] = report.get("verdict") 

421 if report.get("head") != commit: 421 ↛ 422line 421 didn't jump to line 422 because the condition on line 421 was never true

422 problems.append("the report is bound to another commit") 

423 if report.get("verdict") != verdict: 423 ↛ 424line 423 didn't jump to line 424 because the condition on line 423 was never true

424 problems.append(f"the ref says {verdict} but the report says {report.get('verdict')}") 

425 try: 

426 recomputed = PanelReport.from_dict(report).digest 

427 except (KeyError, TypeError, ValueError) as error: 

428 recomputed = f"unreadable: {error}" 

429 if recomputed != report.get("digest"): 

430 problems.append("the report digest does not match its content") 

431 base = report.get("base") 

432 if not isinstance(base, str) or git.resolve(base) is None: 432 ↛ 433line 432 didn't jump to line 433 because the condition on line 432 was never true

433 problems.append("the base of the report is not a commit of this repository") 

434 else: 

435 diff = git.run(*_diff_args(), base, commit).stdout.decode("utf-8", "replace") 

436 if diff_hash(diff) != report.get("diffHash"): 436 ↛ 437line 436 didn't jump to line 437 because the condition on line 436 was never true

437 problems.append("the diff between the base and the commit is not the one reviewed") 

438 return {**result, "valid": not problems, "problems": problems, "base": base} 

439 

440 

441# ----- comment ------------------------------------------------------------------------------------ 

442def pull_request_number(explicit: int | None) -> int | None: 

443 if explicit: 

444 return explicit 

445 github = os.environ.get("GITHUB_REF", "") 

446 if github.startswith("refs/pull/"): 446 ↛ 447line 446 didn't jump to line 447 because the condition on line 446 was never true

447 part = github.split("/")[2] 

448 if part.isdigit(): 

449 return int(part) 

450 for name in PULL_REQUEST_NUMBER_ENV: 

451 value = os.environ.get(name, "").strip() 

452 if value.isdigit(): 452 ↛ 453line 452 didn't jump to line 453 because the condition on line 452 was never true

453 return int(value) 

454 return None 

455 

456 

457def render_comment(report: dict[str, Any]) -> str: 

458 counts = report.get("counts") or {} 

459 lines = [ 

460 f"### Review panel: {report['verdict']}", 

461 "", 

462 f"Head `{report.get('head')}`, base `{report.get('base')}`, report digest " 

463 f"`{report.get('digest')}`.", 

464 "", 

465 f"{counts.get('errors', 0)} error(s), {counts.get('suggestions', 0)} suggestion(s); " 

466 f"{counts.get('droppedOutside', 0)} finding(s) outside the changed lines dropped.", 

467 "", 

468 ] 

469 findings = report.get("findings") or [] 

470 if findings: 470 ↛ 471line 470 didn't jump to line 471 because the condition on line 470 was never true

471 lines.extend( 

472 [ 

473 "| Severity | Rule | Location | Issue |", 

474 "| --- | --- | --- | --- |", 

475 ] 

476 ) 

477 for item in findings: 

478 issue = str(item["issue"]).replace("|", "\\|") 

479 lines.append( 

480 f"| {item['severity']} | `{item['rule']}` | `{item['file']}:{item['line']}` " 

481 f"({item['side']}) | {issue} |" 

482 ) 

483 ran = [item["id"] for item in report.get("reviewers") or [] if item["status"] != "SKIPPED"] 

484 lines.extend(["", f"Reviewers: {', '.join(ran) or 'none (deterministic rules only)'}."]) 

485 return "\n".join(lines) + "\n" 

486 

487 

488def comment_on_forge( 

489 services: Any, 

490 report: dict[str, Any], 

491 number: int, 

492 transport_override: Any = None, 

493) -> dict[str, Any]: 

494 from governed_harness.application.forges import forge_settings 

495 from governed_harness.forges import open_forge, resolve_forge 

496 

497 resolved = resolve_forge(services.paths.workspace, forge_settings(services)) 

498 forge = open_forge(resolved, transport_override) 

499 return forge.upsert_comment(number, f"review-{report['head']}", render_comment(report)) 

500 

501 

502# ----- hook --------------------------------------------------------------------------------------- 

503def install_hook( 

504 workspace: Path, *, force: bool = False, executable: str | None = None 

505) -> dict[str, Any]: 

506 git = Git(workspace) 

507 if not git.is_repository(): 507 ↛ 508line 507 didn't jump to line 508 because the condition on line 507 was never true

508 raise ConfigurationError(f"{workspace} is not a Git repository") 

509 hooks = Path(git.text("rev-parse", "--git-path", "hooks")) 

510 if not hooks.is_absolute(): 510 ↛ 512line 510 didn't jump to line 512 because the condition on line 510 was always true

511 hooks = workspace / hooks 

512 target = hooks / "pre-push" 

513 existing = target.read_text(encoding="utf-8", errors="replace") if target.exists() else None 

514 if existing is not None and HOOK_MARKER not in existing and not force: 

515 raise ConfigurationError( 

516 f"{target} exists and was not written by the harness; pass --force to replace it" 

517 ) 

518 command = executable or shutil.which("harness") or "harness" 

519 script = ( 

520 "#!/bin/sh\n" 

521 f"{HOOK_MARKER}\n" 

522 "# Reviews the commits being pushed against their base; a FAIL or UNKNOWN verdict, or a\n" 

523 "# base that cannot be fetched, stops the push (exit code 6).\n" 

524 'root="$(git rev-parse --show-toplevel)" || exit 1\n' 

525 f'exec {shlex.quote(command)} --json review-code --mode hook --path "$root"\n' 

526 ) 

527 hooks.mkdir(parents=True, exist_ok=True) 

528 target.write_text(script, encoding="utf-8") 

529 target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH) 

530 return {"status": "PASSED", "hook": str(target), "command": command} 

531 

532 

533# ----- variance ------------------------------------------------------------------------------------- 

534def variance_summary(reports: list[dict[str, Any]]) -> dict[str, Any]: 

535 """Verdict stability, finding frequency and pairwise agreement of identical reviews.""" 

536 keys = [ 

537 { 

538 f"{item['file']}:{item['side']}:{item['line']}:{item['rule']}" 

539 for item in report.get("findings") or [] 

540 } 

541 for report in reports 

542 ] 

543 verdicts = Counter(str(report.get("verdict")) for report in reports) 

544 frequency = Counter(key for run in keys for key in run) 

545 pairs = list(combinations(keys, 2)) 

546 jaccard = [ 

547 (len(left & right) / len(left | right)) if (left | right) else 1.0 for left, right in pairs 

548 ] 

549 runs = len(reports) 

550 return { 

551 "runs": runs, 

552 "verdicts": dict(sorted(verdicts.items())), 

553 "verdictStability": round(max(verdicts.values()) / runs, 4) if runs else None, 

554 "findings": [ 

555 {"finding": key, "runs": count, "share": round(count / runs, 4)} 

556 for key, count in sorted(frequency.items(), key=lambda item: (-item[1], item[0])) 

557 ], 

558 "meanJaccard": round(sum(jaccard) / len(jaccard), 4) if jaccard else 1.0, 

559 "tokensPerRun": [int((report.get("tokens") or {}).get("total") or 0) for report in reports], 

560 } 

561 

562 

563# ----- the commands ------------------------------------------------------------------------------- 

564class ReviewCodeCommands: 

565 """The ``harness review-code`` and ``harness review ...`` commands of the application.""" 

566 

567 def _resolved_repository(self, path: Path) -> tuple[ResolvedConfiguration, Git]: 

568 from governed_harness.configuration.resolver import ConfigurationResolver 

569 

570 resolved = ConfigurationResolver().resolve(path) 

571 git = Git(resolved.workspace_root) 

572 if not git.is_repository(): 572 ↛ 573line 572 didn't jump to line 573 because the condition on line 572 was never true

573 raise ConfigurationError(f"{resolved.workspace_root} is not a Git repository") 

574 return resolved, git 

575 

576 def review_code( 

577 self, 

578 path: Path, 

579 *, 

580 mode: str = "manual", 

581 base: str | None = None, 

582 head: str = "HEAD", 

583 provider: str | None = None, 

584 fallback: str | None = None, 

585 model: str | None = None, 

586 skip: tuple[str, ...] = (), 

587 pull_request: int | None = None, 

588 comment: bool | None = None, 

589 cache: bool = True, 

590 transport_override: Any = None, 

591 ) -> dict[str, Any]: 

592 """Review the change of a branch (``manual``), of a push (``hook``) or of the index 

593 (``staged``) with the review panel, outside a governed run.""" 

594 from governed_harness.delivery.publisher import PublishError 

595 from governed_harness.orchestration.engine import EngineServices 

596 

597 if mode not in MODES: 597 ↛ 598line 597 didn't jump to line 598 because the condition on line 597 was never true

598 raise ConfigurationError(f"mode must be one of {', '.join(MODES)}, got {mode!r}") 

599 resolved, git = self._resolved_repository(path) 

600 setup = review_setup(resolved) 

601 if setup.settings.mode == "off": 601 ↛ 602line 601 didn't jump to line 602 because the condition on line 601 was never true

602 raise ConfigurationError("review.panel.mode is off in project.yaml") 

603 resolution = resolve_base(git, mode, base, setup.settings.base_branches) 

604 diff_text, head_sha = collect_diff(git, mode, resolution, head) 

605 services = EngineServices.open(resolved) 

606 try: 

607 inputs = panel_inputs( 

608 resolved, 

609 services, 

610 mode=mode, 

611 diff_text=diff_text, 

612 base=resolution.sha, 

613 head=head_sha, 

614 provider=provider, 

615 fallback=fallback, 

616 model=model, 

617 skip=skip, 

618 use_cache=cache, 

619 setup=setup, 

620 ) 

621 report = run_panel(inputs) 

622 result = report.as_dict() 

623 result["baseResolution"] = resolution.as_dict() 

624 evidence: str | None = None 

625 if setup.settings.evidence_refs is not False and mode != "staged": 

626 evidence = write_evidence_ref(git, report) 

627 result["evidenceRef"] = evidence 

628 wanted = comment if comment is not None else bool(setup.settings.comment) 

629 number = pull_request_number(pull_request) 

630 if not wanted or number is None: 

631 result["comment"] = {"status": "SKIPPED", "reason": "no comment requested"} 

632 elif report.verdict not in REF_KINDS: 

633 result["comment"] = { 

634 "status": "SKIPPED", 

635 "reason": f"no comment on a {report.verdict} review", 

636 } 

637 elif report.cache == "hit": 

638 result["comment"] = { 

639 "status": "SKIPPED", 

640 "reason": "cache hit: this result was already commented", 

641 } 

642 else: 

643 try: 

644 posted = comment_on_forge(services, result, number, transport_override) 

645 result["comment"] = {"status": "PASSED", "pullRequest": number, **posted} 

646 except (PublishError, ConfigurationError) as error: 

647 result["comment"] = {"status": "ERROR", "error": str(error)} 

648 finally: 

649 services.close() 

650 return result 

651 

652 def review_rules(self, path: Path) -> dict[str, Any]: 

653 """The effective catalog: the rules by layer, the inactive ones and why, the reviewers 

654 and their drift.""" 

655 from governed_harness.configuration.resolver import ConfigurationResolver 

656 from governed_harness.review.reviewers import drift 

657 

658 resolved = ConfigurationResolver().resolve(path) 

659 setup = review_setup(resolved) 

660 return { 

661 "catalog": setup.catalog.summary(), 

662 "rules": [ 

663 { 

664 "id": rule.rule_id, 

665 "domain": rule.domain, 

666 "layer": rule.layer, 

667 "source": rule.source, 

668 "severity": rule.severity, 

669 "priority": rule.priority, 

670 "verifiedBy": list(rule.verified_by), 

671 } 

672 for rule in setup.catalog.rules 

673 ], 

674 "reviewers": [ 

675 { 

676 "id": item.reviewer_id, 

677 "domain": item.domain, 

678 "source": item.source, 

679 "diffSlice": item.spec.diff_slice 

680 if isinstance(item.spec.diff_slice, str) 

681 else list(item.spec.diff_slice), 

682 "activation": item.spec.activation, 

683 "modes": list(item.spec.modes), 

684 "rules": len(setup.catalog.for_domain(item.domain, ai_only=True)), 

685 } 

686 for item in setup.reviewers 

687 ], 

688 "drift": drift(setup.reviewers, setup.catalog), 

689 "packs": list(setup.packs), 

690 "tools": sorted(setup.tools), 

691 } 

692 

693 def review_rules_sync(self, path: Path, *, check: bool = False) -> dict[str, Any]: 

694 """Write (or, with ``check``, compare) the rules block of every project reviewer.""" 

695 from governed_harness.configuration.resolver import ConfigurationResolver 

696 

697 resolved = ConfigurationResolver().resolve(path) 

698 setup = review_setup(resolved) 

699 results = sync_blocks(resolved.workspace_root, setup.catalog, check=check) 

700 drifted = [item.as_dict() for item in results if item.status == "drift"] 

701 return { 

702 "status": "FAILED" if drifted else "PASSED", 

703 "check": check, 

704 "catalog": setup.catalog.digest, 

705 "reviewers": [item.as_dict() for item in results], 

706 "drift": drifted, 

707 } 

708 

709 def review_verify(self, path: Path, sha: str) -> dict[str, Any]: 

710 _resolved, git = self._resolved_repository(path) 

711 return verify_evidence(git, sha) 

712 

713 def review_hook_install(self, path: Path, *, force: bool = False) -> dict[str, Any]: 

714 resolved, _git = self._resolved_repository(path) 

715 return install_hook(resolved.workspace_root, force=force) 

716 

717 def review_variance( 

718 self, 

719 path: Path, 

720 *, 

721 runs: int = 3, 

722 mode: str = "manual", 

723 base: str | None = None, 

724 provider: str | None = None, 

725 model: str | None = None, 

726 ) -> dict[str, Any]: 

727 """The same review ``runs`` times without cache: verdict stability and agreement.""" 

728 from governed_harness.orchestration.engine import EngineServices 

729 

730 if not 2 <= runs <= 10: 730 ↛ 731line 730 didn't jump to line 731 because the condition on line 730 was never true

731 raise ConfigurationError("runs must be between 2 and 10") 

732 resolved, git = self._resolved_repository(path) 

733 setup = review_setup(resolved) 

734 resolution = resolve_base(git, mode, base, setup.settings.base_branches) 

735 diff_text, head_sha = collect_diff(git, mode, resolution, "HEAD") 

736 services = EngineServices.open(resolved) 

737 reports: list[dict[str, Any]] = [] 

738 try: 

739 for _ in range(runs): 

740 inputs = panel_inputs( 

741 resolved, 

742 services, 

743 mode=mode, 

744 diff_text=diff_text, 

745 base=resolution.sha, 

746 head=head_sha, 

747 provider=provider, 

748 fallback=None, 

749 model=model, 

750 skip=(), 

751 use_cache=False, 

752 setup=setup, 

753 ) 

754 reports.append(run_panel(inputs).as_dict()) 

755 finally: 

756 services.close() 

757 return { 

758 "baseResolution": resolution.as_dict(), 

759 "head": head_sha, 

760 **variance_summary(reports), 

761 } 

762 

763 

764__all__ = [ 

765 "MODES", 

766 "REF_KINDS", 

767 "ReviewCodeCommands", 

768 "REF_PREFIX", 

769 "BaseResolution", 

770 "ReviewAborted", 

771 "collect_diff", 

772 "comment_on_forge", 

773 "install_hook", 

774 "panel_inputs", 

775 "pull_request_number", 

776 "render_comment", 

777 "resolve_base", 

778 "sync_blocks", 

779 "variance_summary", 

780 "verify_evidence", 

781 "write_evidence_ref", 

782]