Coverage for packages/workshop/src/livery/workshop/_reconcile.py: 99%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""The per-command hook: a sync runs before a command, frozen and offline.
2
3Runs at footman's per-task moment, before the first task of a command,
4from the hook in [livery.workshop._env_tasks][]. It runs the ``sync``
5verb's work on the root the hook found
6([livery.workshop._sync.sync_checkout][]), in the mode that changes
7nothing a commit holds and touches no network, as a plain call: footman
8gives a task called from a hook a directory of its own and a row in the
9run's report, and a failed row fails the command. The sync reads the
10receipts a checkout keeps of its last sync
11([livery.workshop._reconcile.current][]): the uv lock and the
12manifests the venv was installed from, the tool receipts against
13``toolroom.lock``, and the receipt of the files the extensions write
14for the checkout alone. A current checkout costs those reads and
15nothing else; one that is not is brought current from what the machine
16holds, and the command re-runs on the installed code when that sync
17changed it, so a pull that moved the lock never judges from stale
18code. When ``sync`` is the command, the hook leaves the work to it.
19
20The receipts live here beside the hook. What a sync records at its end
21and what it reads at its start are one record.
22
23Never fatal: on any failure the command proceeds and the failure is
24reported in the sync's own words. A task that cannot run without what
25is missing is still caught by its own gate.
26"""
27
28from __future__ import annotations
29
30import os
31import shutil
32import subprocess
33import sys
34from collections.abc import MutableMapping
35from pathlib import Path
36
37_GUARD = "WORKSHOP_RECONCILE_REEXEC"
38
39#: Why a command re-runs on the code on disk. The guard counts each
40#: cause once per command, so a sync that moves the checkout and then
41#: installs extensions re-runs twice, and none re-runs without end.
42MOVED = "moved"
43SYNCED = "synced"
44INSTALLED = "installed"
45RELOCATED = "relocated"
46
47#: Each cause as the guard's note names it.
48_REASONS = {
49 MOVED: "the checkout moved",
50 SYNCED: "the environment synced",
51 INSTALLED: "listed extensions were installed",
52 RELOCATED: "the install moved or removed a mounted extension",
53}
54
55#: Set while the hook's sync runs, so the processes it starts sync
56#: nothing: a delivery lists the workspace's tasks through the runner,
57#: and that child would find the receipts still missing and sync again,
58#: without end.
59_SYNCING = "WORKSHOP_SYNCING"
60
61#: The receipt's name under ``.venv``: a byte copy of ``uv.lock`` as
62#: the venv last saw it. The emitted ``setup.sh`` writes the same
63#: file after its own sync, so the two mechanisms share one record.
64RECEIPT_NAME = ".workshop-sync-receipt"
65
66#: The second receipt: a digest of the root manifest and every
67#: member's, as the venv last installed them. The lock records
68#: dependencies, not a member's entry points or its version, so a
69#: HEAD move that changes a member's ``pyproject.toml`` without
70#: moving the lock would leave the venv's metadata stale (a new
71#: ``pytest11`` entry point the venv never learned) with the lock
72#: receipt still matching.
73MANIFESTS_RECEIPT_NAME = ".workshop-manifests-receipt"
74
75
76def receipt_path(root: Path) -> Path:
77 """Where *root*'s sync receipt lives."""
78 return root / ".venv" / RECEIPT_NAME
79
80
81def manifests_receipt_path(root: Path) -> Path:
82 """Where *root*'s manifests receipt lives."""
83 return root / ".venv" / MANIFESTS_RECEIPT_NAME
84
85
86def manifests_digest(root: Path) -> str:
87 """A digest of the root ``pyproject.toml`` and every package's ``pyproject.toml``.
88
89 Path order, each path and its bytes, so a member added, removed,
90 or edited changes the digest.
91 """
92 import hashlib
93
94 from livery.workshop._packages import package_directories
95
96 digest = hashlib.sha256()
97 manifests = sorted(
98 [
99 root / "pyproject.toml",
100 *(directory / "pyproject.toml" for directory in package_directories(root)),
101 ]
102 )
103 for path in manifests:
104 if path.is_file():
105 digest.update(path.relative_to(root).as_posix().encode("utf-8"))
106 digest.update(b"\0")
107 digest.update(path.read_bytes())
108 digest.update(b"\0")
109 return digest.hexdigest()
110
111
112def record_receipt(root: Path) -> None:
113 """Record ``uv.lock`` and the manifests as the venv's receipts; silent otherwise.
114
115 Called after every successful sync so the next command's compare
116 is a no-op instead of a second sync.
117 """
118 lock = root / "uv.lock"
119 if lock.is_file() and (root / ".venv").is_dir():
120 receipt_path(root).write_bytes(lock.read_bytes())
121 manifests_receipt_path(root).write_text(manifests_digest(root), "utf-8")
122
123
124def is_cli_process() -> bool:
125 """Whether this process is a real runner invocation.
126
127 The reconcile is opt-in from the runner's own console script,
128 never opt-out by recognising footman's manifest-refresh child:
129 that child is spawned as ``python -c ...`` and a test suite runs
130 under pytest, so neither carries the runner's name in ``argv[0]``
131 and both leave the reconcile inert. The refresh child's contract
132 is quick and quiet (no network, no prompts), and a test that
133 shelled out to ``uv sync`` once per test would be slow and
134 destructive.
135 """
136 import livery.footman as footman
137
138 if not sys.argv or not sys.argv[0]:
139 return False
140 return Path(sys.argv[0]).stem.lower() == footman.prog()
141
142
143def installed_distributions(root: Path) -> dict[str, str]:
144 """Every ``*.dist-info`` name in the venv, to its entry points' digest.
145
146 Read across platform layouts. A name alone misses an editable
147 member re-installed at the same version with new entry points: its
148 directory keeps its name, and a process that mounted the old entry
149 points would go on with them. The digest of each
150 ``entry_points.txt`` (empty without one) makes that re-install a
151 change.
152 """
153 import hashlib
154
155 found: dict[str, str] = {}
156 for pattern in ("lib/python*/site-packages", "Lib/site-packages"):
157 for site in (root / ".venv").glob(pattern):
158 for entry in site.glob("*.dist-info"):
159 try:
160 points = (entry / "entry_points.txt").read_bytes()
161 except OSError:
162 points = b""
163 found[entry.name] = hashlib.sha256(points).hexdigest() if points else ""
164 return found
165
166
167def current(root: Path) -> str:
168 """Why *root* is not current, in a few words; empty when it is.
169
170 Four receipts, all local reads. The uv lock receipt and the
171 manifests receipt against ``uv.lock`` and the manifests on disk;
172 a venv synced before the manifests receipt existed adopts the
173 manifests on disk as the ones installed, since the emitted
174 ``setup.sh``'s fresh venv is that case, and the next move is seen.
175 Then a receipt per tool ``toolroom.lock`` holds for this host, at
176 the locked version and still in the store, with the stubs beside
177 them; then the receipt a delivery leaves. A checkout with no lock
178 or no venv has nothing to compare and is not current.
179 """
180 lock = root / "uv.lock"
181 if not lock.is_file():
182 return "there is no uv.lock yet"
183 if not (root / ".venv").is_dir():
184 return "there is no environment yet"
185 receipt = receipt_path(root)
186 if not receipt.is_file() or receipt.read_bytes() != lock.read_bytes():
187 return "uv.lock moved past the environment"
188 digest = manifests_digest(root)
189 manifests = manifests_receipt_path(root)
190 if not manifests.is_file():
191 manifests.write_text(digest, "utf-8")
192 elif manifests.read_text("utf-8") != digest:
193 return "a package manifest moved past the environment"
194 why = tools_current(root)
195 if why:
196 return why
197 from livery.workshop._fragment_engine import LOCAL_RECEIPT
198
199 if not (root / LOCAL_RECEIPT).is_file():
200 return "this checkout's own files were never delivered"
201 return ""
202
203
204def tools_current(root: Path) -> str:
205 """Why the tool receipts do not match ``toolroom.lock``; empty when they do.
206
207 A receipt matches when it names the locked version and the
208 directory it points into is still in the store; a receipt whose
209 tool the store has lost reads as off, so a sync supplies it again.
210 The stubs the checkers read stand beside the receipts: a checkout
211 locked for this host with no ``typings/`` is off too. A checkout
212 with no ``toolroom.lock`` has nothing to match and is current here.
213 """
214 import platform
215
216 from livery.toolroom.store import LOCK_FILE, Lock, LockError, host_key
217 from livery.workshop._tools import TYPINGS, tool_receipts
218
219 if not (root / LOCK_FILE).is_file():
220 return ""
221 try:
222 lock = Lock.load(root / LOCK_FILE)
223 held = tool_receipts(root)
224 except (LockError, ValueError, OSError):
225 # An unreadable lock or receipt is the sync's to name, not
226 # the hook's to judge: the sync reads both and refuses by name.
227 return f"{LOCK_FILE} or a receipt could not be read"
228 host = host_key(platform.system(), platform.machine())
229 for name in lock.on_host(host):
230 receipt = held.get(name)
231 if receipt is None:
232 return f"no receipt for {name}"
233 if receipt.version != lock.tools[name].version:
234 locked = lock.tools[name].version
235 return f"{name} is at {receipt.version}, the lock holds {locked}"
236 if receipt.tool_dir and not Path(receipt.tool_dir).is_dir():
237 return f"the store no longer holds {name}"
238 if lock.on_host(host) and not (root / TYPINGS).is_dir():
239 return f"no stubs in {TYPINGS}/"
240 return ""
241
242
243def _say(message: str) -> None:
244 """One line to stderr, in ASCII, and never a failure of its own.
245
246 The reconcile speaks on any command, on every platform, and its
247 output is read back by machines that decode UTF-8. A Windows
248 console encodes to the ANSI codepage, where a non-ASCII byte
249 breaks that reader. Forced rather than trusted, and the write is
250 guarded: a hook that fails while formatting its own progress note
251 would take the command with it.
252 """
253 import contextlib
254
255 with contextlib.suppress(Exception):
256 sys.stderr.write(message.encode("ascii", "replace").decode("ascii") + "\n")
257
258
259def apply(root: Path, task: str, env: MutableMapping[str, str]) -> bool:
260 """Sync *root* before *task*, the command's first; whether the sync did work.
261
262 Nothing happens when *task* is ``sync``, the verb itself, or inside
263 a process the hook's own sync started, which *env*, the task's own
264 environment, marks for the processes the sync starts. Otherwise the
265 verb's work runs on *root*, frozen and offline, as a plain call
266 ([livery.workshop._sync.sync_checkout][]), its lines on stderr so
267 a command whose stdout a shell evaluates stays clean. It reads the
268 receipts first and does nothing, silently, for a current checkout;
269 otherwise it says what is off and brings the checkout current, and
270 the command re-runs on the installed code when that changed it. A
271 sync that fails is said and the command runs on what is here: the
272 sync is not a task of the run, so its failure adds no failed row,
273 and the command's verdict is its own.
274
275 Returns:
276 Whether the sync did work. The caller entered the environment
277 before it, from receipts the sync may have written since, so it
278 enters again.
279 """
280 import contextlib
281
282 import livery.footman as footman
283
284 if os.environ.get(_SYNCING) or env.get(_SYNCING) or task == "sync":
285 return False
286 prog = footman.prog()
287 # Set in the task's own environment, which the sync's children see
288 # and no sibling does, and removed after them.
289 env[_SYNCING] = "1"
290 try:
291 from livery.workshop._sync import sync_and_compare
292
293 with contextlib.redirect_stdout(sys.stderr):
294 synced = sync_and_compare(root, frozen=True, offline=True)
295 except Exception as error: # the hook never stops the command it precedes
296 _say(f"{prog}: the sync did not complete ({error}); running on what is here")
297 return False
298 finally:
299 env.pop(_SYNCING, None)
300 if synced.installs_changed:
301 _reexec(root, SYNCED)
302 return synced.ran
303
304
305def _reexec(root: Path, cause: str) -> None:
306 """Re-run this command through uv on the code the sync installed, for *cause*.
307
308 The sync replaced packages underneath a process already running
309 them; modules imported before it are the old version, ones
310 imported lazily afterwards the new, and a mixed process fails in
311 ways that look like nothing in particular. Re-running costs one
312 process start on a path that only happens when the lock moved.
313
314 Guarded by an environment marker naming the causes the command
315 already re-ran for: each cause re-runs it once, so a sync that never
316 converges degrades to a note, not a spin. Launch failures degrade
317 the same way; killing the command because the restart could not
318 start would turn a repair into an outage. Windows has no real exec,
319 so it waits and forwards the exit code.
320
321 The guard is handed to the replacement, never written into this
322 process. An ambient write is a footman note, and rightly: a task
323 that changes its own environment surprises its siblings. It is
324 also invisible here, because the note is judged at the task's
325 boundary and an exec never reaches one, so the wall that catches
326 this everywhere else cannot catch it. Both spellings take the
327 environment explicitly, so there is nothing to catch.
328
329 The hook's sync marker is never handed on. The replacement runs the
330 command again; it is not a process the sync starts, so its own hook
331 syncs and its children start without the marker.
332 """
333 import livery.footman as footman
334
335 prog = footman.prog()
336 done = {part for part in os.environ.get(_GUARD, "").split(",") if part}
337 if cause in done:
338 _say(
339 f"{prog}: this command already re-ran once because"
340 f" {_REASONS[cause]}; continuing on the loaded code"
341 )
342 return
343 uv = shutil.which("uv")
344 if uv is None:
345 _say(f"{prog}: uv is not on PATH; continuing on the loaded code")
346 return
347 cmd = [uv, "run", "--project", str(root), "--no-sync", prog, *sys.argv[1:]]
348 try:
349 # Whatever a plugin wants to survive the replacement rides in the
350 # environment beside the guard: a profiled run's trace, and
351 # whatever else subscribes later. Nothing mounted hands nothing on.
352 with footman.handing_off() as handed:
353 handed_on: dict[str, str] = {
354 **os.environ,
355 _GUARD: ",".join(sorted({*done, cause})),
356 **handed,
357 }
358 handed_on.pop(_SYNCING, None)
359 if sys.platform == "win32":
360 completed = subprocess.run(cmd, check=False, env=handed_on)
361 # The successful handoff: SystemExit derives from
362 # BaseException, so the hook's Exception guard cannot
363 # swallow it.
364 raise SystemExit(completed.returncode)
365 os.execve(uv, cmd, handed_on)
366 except (OSError, ValueError) as error:
367 _say(
368 f"{prog}: could not re-run on the updated code ({error});"
369 " continuing on the loaded code"
370 )
371 return