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
« 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).
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."""
13from __future__ import annotations
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
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
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}$")
82class ReviewAborted(PolicyViolationError):
83 """A review that cannot run as asked (hook mode without its base)."""
85 exit_code = 6
88@dataclass(frozen=True)
89class BaseResolution:
90 ref: str
91 sha: str
92 source: str
93 fetched: bool = False
95 def as_dict(self) -> dict[str, Any]:
96 return {"ref": self.ref, "sha": self.sha, "source": self.source, "fetched": self.fetched}
99# ----- base resolution --------------------------------------------------------------------------
100def _ref_exists(git: Git, ref: str) -> bool:
101 return git.resolve(ref) is not None
104def _has_remote(git: Git, remote: str = "origin") -> bool:
105 return git.run("remote", "get-url", remote, check=False).returncode == 0
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
122def _convention(branch: str, configured: dict[str, str] | None, git: Git) -> str | None:
123 import fnmatch
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
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 )
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
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
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)
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 )
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 )
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
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
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
280 from governed_harness.capabilities import grants_from_rules
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 )
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 )
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")
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
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
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}
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
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"
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
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))
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}
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 }
563# ----- the commands -------------------------------------------------------------------------------
564class ReviewCodeCommands:
565 """The ``harness review-code`` and ``harness review ...`` commands of the application."""
567 def _resolved_repository(self, path: Path) -> tuple[ResolvedConfiguration, Git]:
568 from governed_harness.configuration.resolver import ConfigurationResolver
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
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
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
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
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 }
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
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 }
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)
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)
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
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 }
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]