Coverage for src/governed_harness/review/diff.py: 92%

235 statements  

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

1"""The unified diff a review reads: files, reportable locations and slices (#57). 

2 

3A reviewer may only report on lines the change touched. The reportable locations come from the 

4unified diff itself: 

5 

6* ``new``: an added line, with its line number in the new file; 

7* ``old``: a removed line, with its line number in the old file; 

8* context lines only advance the counters and are never reportable; 

9* a deleted file is reportable on the ``old`` side for every removed line (a whole-file deletion 

10 is reviewable), and on its line 1 when the diff shows no line of it (an empty or binary file). 

11 

12The parser counts the lines of every hunk, so a removed line that reads ``-- x`` followed by an 

13added ``++ y`` is never taken for a new file header. It reads Git diffs (``diff --git`` headers, 

14``Binary files ... differ``) and the ChangeSet diff the harness records (no ``diff --git`` line, 

15``Binary files differ: PATH``).""" 

16 

17from __future__ import annotations 

18 

19import fnmatch 

20import re 

21from collections.abc import Iterable, Sequence 

22from dataclasses import dataclass, field 

23from typing import Literal 

24 

25from governed_harness.checks.model import DiffFile, DiffLine 

26from governed_harness.evidence.hashing import sha256_bytes 

27 

28Side = Literal["new", "old"] 

29SIDES: tuple[Side, ...] = ("new", "old") 

30 

31_HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@") 

32_HARNESS_BINARY = re.compile(r"^Binary files differ: (.+)$") 

33_DEV_NULL = "/dev/null" 

34_GIT_HEADER_PREFIX = "diff --git " 

35_GIT_BINARY_PREFIX = "Binary files " 

36_GIT_BINARY_SEPARATOR = " and " 

37_GIT_BINARY_SUFFIX = " differ" 

38 

39 

40# The two paths of a Git header are read by scanning the line once: a path may hold spaces, and a 

41# single pattern with two lazy groups backtracks over every space. Each reader returns what 

42# ``^diff --git (?:"?a/)?(.+?)"? (?:"?b/)?(.+?)"?$`` and 

43# ``^Binary files (?:a/)?(.+?) and (?:b/)?(.+?) differ$`` capture on a line without line breaks 

44# (the parser reads ``str.splitlines()``), or ``None`` where they do not match. 

45def _side_starts(text: str, prefix: str, *, quoted: bool) -> list[int]: 

46 """Where a path may start after its optional ``a/``/``b/`` prefix (``"``-quoted when 

47 ``quoted``): past the prefix first, then at the very start.""" 

48 if quoted and text.startswith('"' + prefix): 48 ↛ 49line 48 didn't jump to line 49 because the condition on line 48 was never true

49 return [len(prefix) + 1, 0] 

50 if text.startswith(prefix): 

51 return [len(prefix), 0] 

52 return [0] 

53 

54 

55def _new_side(value: str, *, quoted: bool) -> str: 

56 """The second path: its prefix dropped unless nothing would be left, then (when ``quoted``) 

57 its closing quote.""" 

58 start = next(start for start in _side_starts(value, "b/", quoted=quoted) if start < len(value)) 

59 path = value[start:] 

60 return path[:-1] if quoted and len(path) > 1 and path.endswith('"') else path 

61 

62 

63def _git_header_paths(line: str) -> tuple[str, str] | None: 

64 """``diff --git a/OLD b/NEW``: the old path ends at the first space (with the closing quote 

65 before it, if any) that still leaves a new path.""" 

66 if not line.startswith(_GIT_HEADER_PREFIX): 

67 return None 

68 rest = line[len(_GIT_HEADER_PREFIX) :] 

69 for start in _side_starts(rest, "a/", quoted=True): 69 ↛ 75line 69 didn't jump to line 75 because the loop on line 69 didn't complete

70 space = rest.find(" ", start + 1) 

71 if space == -1 or space + 1 >= len(rest): 71 ↛ 72line 71 didn't jump to line 72 because the condition on line 71 was never true

72 continue 

73 end = space - 1 if space - 1 > start and rest[space - 1] == '"' else space 

74 return rest[start:end], _new_side(rest[space + 1 :], quoted=True) 

75 return None 

76 

77 

78def _git_binary_paths(line: str) -> tuple[str, str] | None: 

79 """``Binary files a/OLD and b/NEW differ``: the old path ends at the first `` and `` that 

80 still leaves a new path.""" 

81 rest = line[len(_GIT_BINARY_PREFIX) :] 

82 if not (line.startswith(_GIT_BINARY_PREFIX) and rest.endswith(_GIT_BINARY_SUFFIX)): 

83 return None 

84 body = rest[: -len(_GIT_BINARY_SUFFIX)] 

85 for start in _side_starts(body, "a/", quoted=False): 85 ↛ 91line 85 didn't jump to line 91 because the loop on line 85 didn't complete

86 separator = body.find(_GIT_BINARY_SEPARATOR, start + 1) 

87 new_start = separator + len(_GIT_BINARY_SEPARATOR) 

88 if separator == -1 or new_start >= len(body): 88 ↛ 89line 88 didn't jump to line 89 because the condition on line 88 was never true

89 continue 

90 return body[start:separator], _new_side(body[new_start:], quoted=False) 

91 return None 

92 

93 

94@dataclass 

95class FileChange: 

96 """One file of a unified diff, with its numbered added and removed lines and the text of 

97 its own section (for a slice).""" 

98 

99 old_path: str | None 

100 new_path: str | None 

101 added: list[DiffLine] = field(default_factory=list) 

102 removed: list[DiffLine] = field(default_factory=list) 

103 binary: bool = False 

104 lines: list[str] = field(default_factory=list) 

105 

106 @property 

107 def path(self) -> str: 

108 return self.new_path or self.old_path or "" 

109 

110 @property 

111 def is_deleted(self) -> bool: 

112 return self.new_path is None 

113 

114 @property 

115 def is_added(self) -> bool: 

116 return self.old_path is None 

117 

118 @property 

119 def text(self) -> str: 

120 return "".join(line if line.endswith("\n") else line + "\n" for line in self.lines) 

121 

122 @property 

123 def changed_lines(self) -> int: 

124 return len(self.added) + len(self.removed) 

125 

126 def as_diff_file(self) -> DiffFile: 

127 """The form the deterministic checks of ``governed_harness.checks`` read.""" 

128 return DiffFile(self.old_path, self.new_path, list(self.added), list(self.removed)) 

129 

130 

131def _side_path(value: str, prefix: str) -> str | None: 

132 value = value.split("\t", 1)[0].strip() 

133 if value.startswith('"') and value.endswith('"'): 133 ↛ 134line 133 didn't jump to line 134 because the condition on line 133 was never true

134 value = value[1:-1] 

135 if value == _DEV_NULL: 

136 return None 

137 return value[len(prefix) :] if value.startswith(prefix) else value 

138 

139 

140def parse_diff(text: str) -> list[FileChange]: 

141 """The files of a unified diff, in diff order.""" 

142 return _DiffParser(text.splitlines()).parse() 

143 

144 

145class _DiffParser: 

146 """A single pass over the lines of a unified diff. Inside a hunk the counters of its header 

147 decide what a line is; outside, each header kind is tried in turn.""" 

148 

149 def __init__(self, lines: list[str]) -> None: 

150 self.lines = lines 

151 self.files: list[FileChange] = [] 

152 self.current: FileChange | None = None 

153 self.old_left = self.new_left = 0 

154 self.old_line = self.new_line = 0 

155 self.open_header = False 

156 

157 def parse(self) -> list[FileChange]: 

158 index = 0 

159 while index < len(self.lines): 

160 index += self._step(index) 

161 return self.files 

162 

163 def _step(self, index: int) -> int: 

164 """Read the line at ``index``; the number of lines it consumed.""" 

165 line = self.lines[index] 

166 if self.current is not None and (self.old_left > 0 or self.new_left > 0): 

167 self._hunk_line(self.current, line) 

168 return 1 

169 for header in (self._git_header, self._file_header, self._mode, self._binary, self._hunk): 

170 used = header(index) 

171 if used: 

172 return used 

173 if self.current is not None: 173 ↛ 175line 173 didn't jump to line 175 because the condition on line 173 was always true

174 self.current.lines.append(line) 

175 return 1 

176 

177 def _hunk_line(self, current: FileChange, line: str) -> None: 

178 current.lines.append(line) 

179 if line.startswith("+"): 

180 current.added.append(DiffLine(self.new_line, line[1:])) 

181 self.new_line += 1 

182 self.new_left -= 1 

183 elif line.startswith("-"): 

184 current.removed.append(DiffLine(self.old_line, line[1:])) 

185 self.old_line += 1 

186 self.old_left -= 1 

187 elif not line.startswith("\\"): 187 ↛ exitline 187 didn't return from function '_hunk_line' because the condition on line 187 was always true

188 self.old_line += 1 

189 self.new_line += 1 

190 self.old_left -= 1 

191 self.new_left -= 1 

192 

193 def _git_header(self, index: int) -> int: 

194 line = self.lines[index] 

195 paths = _git_header_paths(line) 

196 if paths is None: 

197 return 0 

198 self.current = FileChange(*paths, lines=[line]) 

199 self.files.append(self.current) 

200 self.open_header = True 

201 return 1 

202 

203 def _file_header(self, index: int) -> int: 

204 """A ``---``/``+++`` pair: the paths of the file the ``diff --git`` line opened, or a 

205 new file of a diff without such lines.""" 

206 line = self.lines[index] 

207 following = self.lines[index + 1] if index + 1 < len(self.lines) else "" 

208 if not (line.startswith("--- ") and following.startswith("+++ ")): 

209 return 0 

210 old_path = _side_path(line[4:], "a/") 

211 new_path = _side_path(following[4:], "b/") 

212 if self.current is not None and self.open_header: 

213 self.current.old_path, self.current.new_path = old_path, new_path 

214 else: 

215 self.current = FileChange(old_path, new_path) 

216 self.files.append(self.current) 

217 self.open_header = False 

218 self.current.lines.extend((line, following)) 

219 return 2 

220 

221 def _mode(self, index: int) -> int: 

222 line = self.lines[index] 

223 current = self.current 

224 if current is None or not line.startswith(("new file mode", "deleted file mode")): 

225 return 0 

226 current.lines.append(line) 

227 if line.startswith("new file mode"): 

228 current.old_path = None 

229 else: 

230 current.new_path = None 

231 return 1 

232 

233 def _binary(self, index: int) -> int: 

234 line = self.lines[index] 

235 harness = _HARNESS_BINARY.match(line) 

236 git = _git_binary_paths(line) 

237 if harness is None and git is None: 

238 return 0 

239 self.open_header = False 

240 if harness: 

241 # A line both forms read keeps the Git reading of its first path. 

242 path = git[0] if git else harness.group(1) 

243 self.current = FileChange(path, path, binary=True, lines=[line]) 

244 self.files.append(self.current) 

245 elif self.current is not None and git is not None: 245 ↛ 252line 245 didn't jump to line 252 because the condition on line 245 was always true

246 self.current.binary = True 

247 self.current.lines.append(line) 

248 if git[0] == _DEV_NULL: 248 ↛ 250line 248 didn't jump to line 250 because the condition on line 248 was always true

249 self.current.old_path = None 

250 if git[1] == _DEV_NULL: 250 ↛ 251line 250 didn't jump to line 251 because the condition on line 250 was never true

251 self.current.new_path = None 

252 return 1 

253 

254 def _hunk(self, index: int) -> int: 

255 line = self.lines[index] 

256 hunk = _HUNK.match(line) 

257 if not hunk or self.current is None: 

258 return 0 

259 self.open_header = False 

260 self.old_line, self.new_line = int(hunk.group(1)), int(hunk.group(3)) 

261 self.old_left = int(hunk.group(2)) if hunk.group(2) is not None else 1 

262 self.new_left = int(hunk.group(4)) if hunk.group(4) is not None else 1 

263 self.current.lines.append(line) 

264 return 1 

265 

266 

267# ----- reportable locations --------------------------------------------------------------------- 

268@dataclass(frozen=True) 

269class Locations: 

270 """The lines a reviewer may report on: ``(path, side) -> line numbers``.""" 

271 

272 lines: dict[tuple[str, Side], frozenset[int]] 

273 

274 def allows(self, path: str, side: str, line: int) -> bool: 

275 if side == "new": 

276 return line in self.lines.get((path, "new"), frozenset()) 

277 if side == "old": 277 ↛ 279line 277 didn't jump to line 279 because the condition on line 277 was always true

278 return line in self.lines.get((path, "old"), frozenset()) 

279 return False 

280 

281 def paths(self) -> list[str]: 

282 return sorted({key[0] for key in self.lines}) 

283 

284 def as_ranges(self) -> dict[str, dict[str, list[list[int]]]]: 

285 """``{path: {side: [[first, last], ...]}}``: what the request shows the reviewer.""" 

286 value: dict[str, dict[str, list[list[int]]]] = {} 

287 for (path, side), numbers in sorted(self.lines.items()): 

288 if numbers: 288 ↛ 287line 288 didn't jump to line 287 because the condition on line 288 was always true

289 value.setdefault(path, {})[side] = _ranges(sorted(numbers)) 

290 return value 

291 

292 def count(self) -> int: 

293 return sum(len(numbers) for numbers in self.lines.values()) 

294 

295 

296def _ranges(numbers: Sequence[int]) -> list[list[int]]: 

297 ranges: list[list[int]] = [] 

298 for number in numbers: 

299 if ranges and number == ranges[-1][1] + 1: 

300 ranges[-1][1] = number 

301 else: 

302 ranges.append([number, number]) 

303 return ranges 

304 

305 

306def reportable_locations(files: Iterable[FileChange]) -> Locations: 

307 lines: dict[tuple[str, Side], set[int]] = {} 

308 for item in files: 

309 if item.added and item.new_path: 

310 lines.setdefault((item.new_path, "new"), set()).update( 

311 line.number for line in item.added 

312 ) 

313 if item.removed and item.old_path: 

314 lines.setdefault((item.old_path, "old"), set()).update( 

315 line.number for line in item.removed 

316 ) 

317 if item.is_deleted and item.old_path and not item.removed: 

318 lines.setdefault((item.old_path, "old"), set()).add(1) 

319 return Locations({key: frozenset(value) for key, value in lines.items()}) 

320 

321 

322# ----- slices ----------------------------------------------------------------------------------- 

323def glob_match(path: str, pattern: str) -> bool: 

324 path = path.replace("\\", "/") 

325 if fnmatch.fnmatchcase(path, pattern): 

326 return True 

327 if pattern.startswith("**/") and fnmatch.fnmatchcase(path, pattern[3:]): 327 ↛ 328line 327 didn't jump to line 328 because the condition on line 327 was never true

328 return True 

329 return "/" not in pattern and fnmatch.fnmatchcase(path.rsplit("/", 1)[-1], pattern) 

330 

331 

332def render(files: Iterable[FileChange]) -> str: 

333 """The diff text of some files (a slice), section by section as parsed.""" 

334 return "".join(item.text for item in files) 

335 

336 

337def diff_hash(text: str) -> str: 

338 return sha256_bytes(text.encode("utf-8")) 

339 

340 

341__all__ = [ 

342 "SIDES", 

343 "FileChange", 

344 "Locations", 

345 "Side", 

346 "diff_hash", 

347 "glob_match", 

348 "parse_diff", 

349 "render", 

350 "reportable_locations", 

351]