Coverage for src/governed_harness/runtime/workspace.py: 88%

136 statements  

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

1from __future__ import annotations 

2 

3import difflib 

4import os 

5from collections.abc import Callable, Iterable 

6from dataclasses import dataclass 

7from pathlib import Path 

8 

9from governed_harness.evidence.hashing import sha256_bytes, sha256_file, sha256_json 

10 

11DEFAULT_EXCLUDES = { 

12 ".git", 

13 ".harness", 

14 ".venv", 

15 "venv", 

16 "node_modules", 

17 "dist", 

18 "build", 

19 "__pycache__", 

20 ".pytest_cache", 

21 ".mypy_cache", 

22 ".ruff_cache", 

23} 

24 

25 

26NO_NEWLINE_MARKER = "\\ No newline at end of file\n" 

27 

28 

29def unified_file_diff( 

30 path: str, old_text: str, new_text: str, *, added: bool = False, deleted: bool = False 

31) -> list[str]: 

32 """The unified diff of one text file as lines that each end with a newline, in the form 

33 ``git apply`` and ``patch`` read: an added file is diffed from ``/dev/null`` and a deleted 

34 one to it, and a last line without a newline is followed by the ``\\ No newline at end of 

35 file`` marker. 

36 

37 Before 2.0 the lines were joined with an extra newline (every line was followed by an empty 

38 line), so ChangeSet diffs recorded by earlier versions are not valid patches; their digests 

39 stay as recorded.""" 

40 lines: list[str] = [] 

41 for line in difflib.unified_diff( 

42 _text_lines(old_text), 

43 _text_lines(new_text), 

44 fromfile="/dev/null" if added else f"a/{path}", 

45 tofile="/dev/null" if deleted else f"b/{path}", 

46 ): 

47 if line.endswith("\n"): 

48 lines.append(line) 

49 else: 

50 lines.extend((line + "\n", NO_NEWLINE_MARKER)) 

51 return lines 

52 

53 

54def _text_lines(text: str) -> list[str]: 

55 # Split on newlines only, as Git does: str.splitlines also breaks on form feeds, vertical 

56 # tabs and other separators, which would make the hunks disagree with the file. 

57 parts = text.split("\n") 

58 return [part + "\n" for part in parts[:-1]] + ([parts[-1]] if parts[-1] else []) 

59 

60 

61@dataclass(frozen=True) 

62class FileState: 

63 path: str 

64 digest: str 

65 size_bytes: int 

66 text: str | None 

67 text_loaded: bool = True 

68 """False when ``text`` was not read (a manifest snapshot): the diff asks its text resolver 

69 for the text of a changed file only.""" 

70 

71 

72def recorded_bytes(state: FileState) -> bytes | None: 

73 """The bytes of a file as its state recorded them, from its text: ``None`` when no text was 

74 recorded or when the text is not the recorded content (a snapshot read back from a redacted 

75 artifact, #178), so that a caller writing it back never writes a redacted value.""" 

76 if not state.text_loaded or state.text is None: 76 ↛ 77line 76 didn't jump to line 77 because the condition on line 76 was never true

77 return None 

78 data = state.text.encode("utf-8", "surrogatepass") 

79 return data if sha256_bytes(data) == state.digest else None 

80 

81 

82TextResolver = Callable[[str, FileState], str | None] 

83"""(side, state) -> the text of a file whose text was not loaded; side is before or after.""" 

84 

85 

86@dataclass(frozen=True) 

87class WorkspaceSnapshot: 

88 files: dict[str, FileState] 

89 digest: str 

90 

91 

92@dataclass(frozen=True) 

93class WorkspaceChange: 

94 path: str 

95 status: str 

96 before_digest: str | None 

97 after_digest: str | None 

98 additions: int 

99 deletions: int 

100 

101 

102@dataclass(frozen=True) 

103class WorkspaceDiff: 

104 changes: tuple[WorkspaceChange, ...] 

105 unified_diff: bytes 

106 digest: str 

107 

108 

109class WorkspaceSnapshotter: 

110 def __init__( 

111 self, 

112 root: Path, 

113 *, 

114 excludes: Iterable[str] = DEFAULT_EXCLUDES, 

115 max_text_bytes: int = 2_000_000, 

116 ) -> None: 

117 self.root = root.resolve(strict=True) 

118 self.excludes = set(excludes) 

119 self.max_text_bytes = max_text_bytes 

120 

121 def snapshot(self) -> WorkspaceSnapshot: 

122 states: dict[str, FileState] = {} 

123 for directory, dirnames, filenames in os.walk(self.root, followlinks=False): 

124 dirnames[:] = [ 

125 name 

126 for name in sorted(dirnames) 

127 if name not in self.excludes and not (Path(directory) / name).is_symlink() 

128 ] 

129 for filename in sorted(filenames): 

130 path = Path(directory) / filename 

131 if path.is_symlink(): 131 ↛ 132line 131 didn't jump to line 132 because the condition on line 131 was never true

132 continue 

133 relative = path.relative_to(self.root).as_posix() 

134 try: 

135 size = path.stat().st_size 

136 digest = sha256_file(path) 

137 text = self._read_text(path, size) 

138 except OSError: 

139 continue 

140 states[relative] = FileState(relative, digest, size, text) 

141 digest = sha256_json({path: state.digest for path, state in sorted(states.items())}) 

142 return WorkspaceSnapshot(files=states, digest=digest) 

143 

144 def diff( 

145 self, 

146 before: WorkspaceSnapshot, 

147 after: WorkspaceSnapshot, 

148 *, 

149 resolve_text: TextResolver | None = None, 

150 ) -> WorkspaceDiff: 

151 paths = sorted(set(before.files) | set(after.files)) 

152 changes: list[WorkspaceChange] = [] 

153 diff_chunks: list[str] = [] 

154 for path in paths: 

155 old = before.files.get(path) 

156 new = after.files.get(path) 

157 if old and new and old.digest == new.digest: 

158 continue 

159 text, additions, deletions = self._file_diff(path, old, new, resolve_text) 

160 if text is not None: 

161 diff_chunks.append(text) 

162 changes.append( 

163 WorkspaceChange( 

164 path=path, 

165 status=_change_status(old, new), 

166 before_digest=old.digest if old else None, 

167 after_digest=new.digest if new else None, 

168 additions=additions, 

169 deletions=deletions, 

170 ) 

171 ) 

172 unified = "".join(diff_chunks).encode("utf-8") 

173 digest = sha256_json( 

174 { 

175 "changes": [change.__dict__ for change in changes], 

176 "diffDigest": sha256_bytes(unified), 

177 } 

178 ) 

179 return WorkspaceDiff(tuple(changes), unified, digest) 

180 

181 def _file_diff( 

182 self, 

183 path: str, 

184 old: FileState | None, 

185 new: FileState | None, 

186 resolve_text: TextResolver | None, 

187 ) -> tuple[str | None, int, int]: 

188 """The diff text of one changed file (``None`` for an empty diff) with its added and 

189 deleted line counts.""" 

190 # A missing side diffs as empty text; a present binary side (text None) is not diffed. 

191 old_text = "" if old is None else self._text("before", old, resolve_text) 

192 new_text = "" if new is None else self._text("after", new, resolve_text) 

193 if old_text is None or new_text is None: 

194 return f"Binary files differ: {path}\n", 0, 0 

195 chunk = unified_file_diff(path, old_text, new_text, added=old is None, deleted=new is None) 

196 additions, deletions = _line_counts(chunk) 

197 return ("".join(chunk) if chunk else None), additions, deletions 

198 

199 def _text(self, side: str, state: FileState, resolve: TextResolver | None) -> str | None: 

200 if state.text_loaded: 

201 return state.text 

202 if resolve is not None: 202 ↛ 204line 202 didn't jump to line 204 because the condition on line 202 was always true

203 return resolve(side, state) 

204 if side == "after": 

205 path = self.root / state.path 

206 try: 

207 data = path.read_bytes() 

208 except OSError: 

209 return None 

210 # A file that changed again since the snapshot is diffed as binary rather than with 

211 # a text that does not match its recorded digest. 

212 return ( 

213 decode_text(data, self.max_text_bytes) 

214 if sha256_bytes(data) == state.digest 

215 else None 

216 ) 

217 return None 

218 

219 def _read_text(self, path: Path, size: int) -> str | None: 

220 if size > self.max_text_bytes: 220 ↛ 221line 220 didn't jump to line 221 because the condition on line 220 was never true

221 return None 

222 return decode_text(path.read_bytes(), self.max_text_bytes) 

223 

224 

225def _change_status(old: FileState | None, new: FileState | None) -> str: 

226 if old is None: 

227 return "ADDED" 

228 if new is None: 

229 return "DELETED" 

230 return "MODIFIED" 

231 

232 

233def _line_counts(chunk: list[str]) -> tuple[int, int]: 

234 """The added and deleted lines of a unified diff, without its file headers.""" 

235 additions = deletions = 0 

236 for line in chunk: 

237 if line.startswith("+") and not line.startswith("+++"): 

238 additions += 1 

239 elif line.startswith("-") and not line.startswith("---"): 

240 deletions += 1 

241 return additions, deletions 

242 

243 

244def decode_text(data: bytes, max_text_bytes: int = 2_000_000) -> str | None: 

245 """The text of a file's bytes as the ChangeSet diff reads it: ``None`` for a file larger 

246 than ``max_text_bytes``, with a NUL byte or that is not UTF-8 (diffed as binary).""" 

247 if len(data) > max_text_bytes or b"\x00" in data: 

248 return None 

249 try: 

250 return data.decode("utf-8") 

251 except UnicodeDecodeError: 

252 return None