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

1"""Incremental review mode for updated PRs (issue #9). 

2 

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. 

7 

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

13 

14from __future__ import annotations 

15 

16import re 

17 

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

21 

22# Page size requested from the compare API; a list this long may be capped. 

23_COMMIT_PAGE = 100 

24 

25MODE_FULL = "full" 

26MODE_INCREMENTAL = "incremental" 

27 

28 

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

32 

33 

34def parse_reviewed_sha(comment_bodies) -> str | None: 

35 """Return the most recent reviewed SHA across jury comment bodies, or None. 

36 

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 

45 

46 

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. 

49 

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 ) 

64 

65 

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

68 

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): 

76 

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. 

83 

84 A full review is the chosen conservative behaviour in each case. 

85 

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 

99 

100 

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

104 

105 

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