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
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3import difflib
4import os
5from collections.abc import Callable, Iterable
6from dataclasses import dataclass
7from pathlib import Path
9from governed_harness.evidence.hashing import sha256_bytes, sha256_file, sha256_json
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}
26NO_NEWLINE_MARKER = "\\ No newline at end of file\n"
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.
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
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 [])
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."""
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
82TextResolver = Callable[[str, FileState], str | None]
83"""(side, state) -> the text of a file whose text was not loaded; side is before or after."""
86@dataclass(frozen=True)
87class WorkspaceSnapshot:
88 files: dict[str, FileState]
89 digest: str
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
102@dataclass(frozen=True)
103class WorkspaceDiff:
104 changes: tuple[WorkspaceChange, ...]
105 unified_diff: bytes
106 digest: str
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
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)
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)
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
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
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)
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"
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
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