Coverage for src/ai_jury/incremental.py: 100%
38 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
1"""Incremental review mode for updated PRs (issue #9).
3Re-reviewing a large PR's full diff on every push is slow and costly. Incremental
4mode reviews only what changed since the jury last ran: it records the
5reviewed head SHA in a hidden marker on its summary comment, and on the next run
6compares that SHA to the current head to fetch just the new range.
8This module holds the PURE, network-free core — embedding/parsing the marker and
9deciding the review scope — so it is fully unit-testable. The thin GitHub calls
10(fetch head SHA, fetch comment bodies, fetch the range diff) live in
11``github.py`` and the CLI; this module never touches the network.
12"""
14from __future__ import annotations
16import re
18# Hidden marker embedded in the jury summary comment recording the SHA that
19# was reviewed, so a later run can compute the incremental range.
20_MARKER_RE = re.compile(r"<!--\s*arc-reviewed-sha:([0-9a-fA-F]{7,40})\s*-->")
22# Page size requested from the compare API; a list this long may be capped.
23_COMMIT_PAGE = 100
25MODE_FULL = "full"
26MODE_INCREMENTAL = "incremental"
29def reviewed_sha_marker(sha: str) -> str:
30 """Return the hidden HTML-comment marker recording the reviewed head SHA."""
31 return f"<!-- arc-reviewed-sha:{sha} -->"
34def parse_reviewed_sha(comment_bodies) -> str | None:
35 """Return the most recent reviewed SHA across jury comment bodies, or None.
37 Scans every body for the marker and returns the LAST match found (later
38 comments override earlier ones), so a fresh re-review marker wins.
39 """
40 last: str | None = None
41 for body in comment_bodies or []:
42 for m in _MARKER_RE.finditer(body or ""):
43 last = m.group(1)
44 return last
47def decide_review(prev_sha: str | None, head_sha: str | None) -> tuple[str, str]:
48 """Decide review scope from the previous reviewed SHA and the current head.
50 Returns ``(mode, reason)`` where ``mode`` is ``"full"`` or ``"incremental"``.
51 Falls back to a full review whenever incremental is not safely possible: no
52 prior marker, unknown head, or an unchanged head (nothing new to review).
53 """
54 if not prev_sha:
55 return MODE_FULL, "no prior jury marker found — full review"
56 if not head_sha:
57 return MODE_FULL, "current head SHA unavailable — full review"
58 if prev_sha == head_sha:
59 return MODE_FULL, "head unchanged since last review — full review"
60 return (
61 MODE_INCREMENTAL,
62 f"incremental: reviewing {prev_sha[:7]}..{head_sha[:7]}",
63 )
66def range_full_reason(meta: dict | None) -> str | None:
67 """Return why ``marker...head`` is NOT the PR's own delta, or None when it is (#974).
69 ``meta`` is the compare summary from ``github.compare_meta``: ``status``,
70 ``total_commits`` and ``parents`` (the parent count of each listed commit).
71 The three-dot range is only the PR's own change when every commit in it is
72 the PR author's work on top of the marker. Three things break that, and each
73 pulls the base branch's changes (other PRs' work) into the diff, so each
74 falls back to a FULL review (``base...head``, which is always the PR's own
75 change):
77 * a merge commit in the range (typically ``git merge main`` into the PR);
78 * a history that is not a plain fast-forward from the marker (status other
79 than ``ahead``: a rebase onto a newer base, or a force-push);
80 * a commit list the API may have truncated (the compare endpoint caps the
81 list, and ``total_commits`` can equal the returned length at the cap), so
82 the merge check cannot be trusted to have seen every commit.
84 A full review is the chosen conservative behaviour in each case.
86 Limit: a squash-merge of the base (``git merge --squash``) is a single-parent
87 commit, so it cannot be told apart from ordinary work and is NOT detected.
88 """
89 if not meta:
90 return "commit range unavailable"
91 if meta.get("status") != "ahead":
92 return f"history is not a fast-forward from the last review ({meta.get('status')})"
93 parents = meta.get("parents") or []
94 if len(parents) >= _COMMIT_PAGE or int(meta.get("total_commits") or 0) > len(parents):
95 return "commit range too long to inspect for a base-branch merge"
96 if any(int(n) > 1 for n in parents):
97 return "the branch merged another branch since the last review"
98 return None
101def compare_range(prev_sha: str, head_sha: str) -> str:
102 """Return the ``base...head`` range spec for the GitHub compare API."""
103 return f"{prev_sha}...{head_sha}"
106def scope_note(mode: str, reason: str) -> str:
107 """Render the user-facing review-scope line for the report (issue #9)."""
108 label = "Incremental" if mode == MODE_INCREMENTAL else "Full"
109 return f"**Review scope:** {label} — {reason}"