Coverage for packages/workshop/src/livery/workshop/_update_driver.py: 82%

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"""``workflow.update``: the update family on the engine.
2
3One update: ``workflow.update.dependencies [names...]`` brings
4dependencies current in both of their homes, the lock for external
5dependencies and the floors for workspace siblings, which the lock
6cannot move because they resolve from source; the bare
7``workflow.update`` runs it for every dependency. The extensions are
8dependencies like any other: the update installs what the lock moved
9to and writes the files the new wheels compose, so a new workshop
10and its files arrive in one pull request.
11
12An update prepared while a release flies parks unarmed and waits,
13watching the releases; when the last completes it re-runs itself,
14picking up the fresh floors, and arms. Ctrl-C is safe: re-entry is
15the same state machine. A non-interactive run waits bounded, then
16parks at exit 0 with the same prose, parked is the verb having done
17its job.
18"""
19
20from __future__ import annotations
21
22import os
23import pathlib
24import subprocess
25from pathlib import Path
26from typing import Annotated
27
28import livery.footman as footman
29import livery.toolroom.tools as tools
30from livery import git
31from livery.footman import doc, fail
32from livery.forge import Repository
33from livery.workshop._packages import discover_packages
34from livery.workshop._update import bump_floors
35from livery.workshop._uv import run_uv
36from livery.workshop._workflow_engine import (
37 PARKS_UPDATES,
38 Submission,
39 run_workflow,
40)
41from livery.workshop._workflow_state import (
42 WorkflowKind,
43 workflow_states,
44)
45from livery.workshop._workflow_tasks import workflow
46
47#: How long a non-interactive parked update waits before exit 0.
48BOUNDED_WAIT = 15 * 60
49WAIT_POLL = 15
50
51#: The loop guard for the fresh-interpreter resubmit.
52_REEXEC_FLAG = "WORKSHOP_UPDATE_REEXEC"
53
54
55class UpdateDriver:
56 """One update flavor's driver for the shared engine."""
57
58 kind = WorkflowKind.UPDATE
59 members: tuple[str, ...] = ()
60 #: An update returns once its pull request is armed; nothing waits on it.
61 watch: float = 0.0
62
63 def __init__(
64 self,
65 root: Path,
66 flavor: str,
67 *,
68 armed: bool,
69 names: tuple[str, ...] = (),
70 refresh: bool = False,
71 ) -> None:
72 self._root = root
73 self._names = names
74 self._refresh = refresh
75 self.name = f"update/{flavor}"
76 self.armed = armed
77
78 @property
79 def branch(self) -> str:
80 return f"workflow/{self.name}"
81
82 @property
83 def base(self) -> str:
84 return "main"
85
86 def discard(self) -> None:
87 """Refuse: an update has no release set, so nothing makes it stale.
88
89 Only a release's moved set re-derives; an update behind its
90 base merges the base in instead.
91 """
92 fail(f"{self.name} never re-derives: an update has no release set")
93
94 def prepare(self) -> Submission | None:
95 """Do the flavor's work, or resume what a killed run committed.
96
97 Committed-but-unsubmitted work on the branch is submitted as
98 it stands, redoing nothing: every subject on the branch is the
99 driver's own conventional ``chore:`` line, so resuming is
100 safe; a foreign subject stops with the options, someone's
101 hand-made commits are not silently shipped. A *refresh*
102 driver (the re-run after a parked update's releases finish)
103 runs the work again on the branch instead, so the floors
104 those releases earned land as a second commit.
105 """
106 root = self._root
107 resumed = False
108 if git.current_branch(root) == self.branch or git.local_branch_exists(
109 root, self.branch
110 ):
111 if git.current_branch(root) != self.branch:111 ↛ 112line 111 didn't jump to line 112 because the condition on line 111 was never true
112 git.switch(root, self.branch)
113 subjects = git.subjects_ahead(root, self.base)
114 if subjects:114 ↛ 144line 114 didn't jump to line 144 because the condition on line 114 was always true
115 # A "Merge " subject is the engine's own MERGE_DEFAULT
116 # bringing the base in, never someone's hand-made work.
117 foreign = [
118 s
119 for s in subjects
120 if not s.startswith("chore:") and not s.startswith("Merge ")
121 ]
122 if foreign:
123 listed = "\n".join(f" {s}" for s in foreign)
124 fail(
125 "the update branch carries commits this driver did"
126 f" not make:\n{listed}\n submit them yourself with"
127 f" `{footman.prog()} submit`, or abort the update with"
128 f" `{footman.prog()} workflow.abort {self.name}` and"
129 " start over."
130 )
131 if not self._refresh:
132 print(" resuming the committed update from its branch")
133 return Submission(title=subjects[-1], body="")
134 resumed = True
135 elif self.branch in git.remote_branches(root, ""):
136 # The engine returns to the branch it started from and
137 # drops the local copy once the pull request holds the
138 # branch, so a re-run resumes from origin's copy.
139 git.fetch(root)
140 git.run(root, "checkout", "-b", self.branch, f"origin/{self.branch}")
141 return self.prepare()
142 else:
143 git.create_branch(root, self.branch)
144 toolchain_before = _locked_workshop(self._root)
145 notes = self._work()
146 # The new wheels ship the files they compose: install them, then
147 # write those files, so the lock and what it brings land together.
148 run_uv("sync", root=self._root)
149 from livery.workshop._templates import apply_project
150
151 notes += [f"composed: {path}" for path in apply_project(self._root)]
152 if git.is_clean(root):
153 if resumed:153 ↛ 155line 153 didn't jump to line 155 because the condition on line 153 was never true
154 # A refresh with nothing new: the committed work stands.
155 subjects = git.subjects_ahead(root, self.base)
156 return Submission(title=subjects[-1], body="")
157 git.switch(root, self.base)
158 git.delete_branch(root, self.branch)
159 return None
160 run_gate(self._root)
161 title = f"chore: {self.name.replace('/', ' ')}"
162 git.commit_all(root, title + "\n\n" + "\n".join(f"- {n}" for n in notes))
163 toolchain_after = _locked_workshop(self._root)
164 if (
165 toolchain_after != toolchain_before
166 and toolchain_after
167 and not os.environ.get(_REEXEC_FLAG)
168 ):
169 # The update just moved the running toolchain itself, and
170 # the synced venv now holds newer code than this process.
171 # The submit re-runs in a fresh interpreter so a fix the
172 # update ships can protect its own submission; the resume
173 # path submits the committed branch and redoes nothing.
174 self._reexec()
175 return Submission(title=title, body="\n".join(f"- {n}" for n in notes))
176
177 def _work(self) -> list[str]:
178 notes: list[str] = []
179 # A named workspace sibling resolves from source, so the lock
180 # cannot move it: its movement is the floor, and only the
181 # named floors move. External names go to the lock. Bare
182 # moves everything in both homes.
183 siblings = {p.name for p in discover_packages(self._root)}
184 named_siblings = tuple(n for n in self._names if n in siblings)
185 external = tuple(n for n in self._names if n not in siblings)
186 if not self._names:
187 run_uv("lock", "--upgrade", root=self._root)
188 notes.append("lock: upgraded every dependency")
189 notes += bump_floors(self._root)
190 return notes
191 for name in external:
192 run_uv("lock", "--upgrade-package", name, root=self._root)
193 notes.append(f"lock: upgraded {name}")
194 if named_siblings:194 ↛ 196line 194 didn't jump to line 196 because the condition on line 194 was always true
195 notes += bump_floors(self._root, only=named_siblings)
196 return notes
197
198 def _reexec(self) -> None:
199 """Finish in a fresh process running the just-synced toolchain."""
200 flavor = self.name.split("/", 1)[1]
201 print(
202 " the update moved livery-workshop itself; finishing in a"
203 " fresh interpreter running the new code"
204 )
205 command = [
206 "uv",
207 "run",
208 footman.prog(),
209 f"workflow.update.{flavor}",
210 ]
211 command += list(self._names)
212 if self.armed:212 ↛ 214line 212 didn't jump to line 214 because the condition on line 212 was always true
213 command.append("--armed")
214 code = _spawn(command, self._root, {**os.environ, _REEXEC_FLAG: "1"})
215 raise SystemExit(code)
216
217 def on_merged(self) -> None:
218 """Merging is an update's completion; nothing follows."""
219
220
221def _spawn(command: list[str], root: Path, env: dict[str, str]) -> int:
222 """Run *command* in *root* with *env*; the exit code."""
223 child = subprocess.run(command, cwd=root, env=env, check=False)
224 return child.returncode
225
226
227def run_gate(root: Path) -> None:
228 """Run the gate with ``--fix`` over the update's changes; red stops.
229
230 A red gate leaves the changes uncommitted on the workflow branch:
231 fix the tree there and run the same update verb again, it
232 resumes from that state. The gate's own output carries in the
233 refusal, because the caller is often a script that sees only
234 this message and would otherwise be told a gate is red with no
235 word about which step.
236 """
237 result = tools.uv.opts(cwd=root, nofail=True, recorded=False)(
238 "run", "fm", "check", "--fix"
239 )
240 if result.code != 0:240 ↛ exitline 240 didn't return from function 'run_gate' because the condition on line 240 was always true
241 fail(
242 f"the gate is red on the update's changes (exit"
243 f" {result.code}):\n{result.stdout[-6000:]}"
244 f"{result.stderr[-3000:]}\n"
245 " The changes are uncommitted on this branch: fix the"
246 " tree, then run the same update verb again to resume."
247 )
248
249
250def _live_releases(repo: Repository, root: Path) -> tuple[str, ...]:
251 """The release workflows currently parking updates, by name."""
252 return tuple(
253 wf.name
254 for wf in workflow_states(repo, root)
255 if wf.kind is WorkflowKind.RELEASE and wf.state in PARKS_UPDATES
256 )
257
258
259def wait_for_releases(
260 repo: Repository,
261 root: Path,
262 *,
263 interactive: bool,
264 timeout: float = BOUNDED_WAIT,
265 poll: float = WAIT_POLL,
266) -> bool:
267 """Wait while releases fly; True when none remains in flight.
268
269 The parked update's promise: it finishes itself once the last
270 release completes. Interactive runs wait indefinitely, Ctrl-C
271 always safe (re-entry resumes); non-interactive runs wait
272 *timeout* then answer False, and the caller parks at exit 0.
273 """
274 from livery.workshop._verdict import (
275 FollowTimedOut,
276 ForgeUnreachable,
277 Pending,
278 follow,
279 )
280
281 announced = False
282
283 def read() -> bool | Pending:
284 nonlocal announced
285 live = _live_releases(repo, root)
286 if not live:
287 return True
288 if not announced:
289 announced = True
290 listed = ", ".join(live)
291 print(
292 f" Release(s) in progress: {listed}. This update will be"
293 " finished automatically once they all finish. Ctrl-C is"
294 f" safe; run `{footman.prog()} workflow.update` any time to continue"
295 " later."
296 )
297 return Pending()
298
299 try:
300 follow(
301 repo,
302 read,
303 subject="the releases in flight",
304 interval=poll,
305 timeout=None if interactive else timeout,
306 quiet=None,
307 )
308 except FollowTimedOut:
309 return False
310 except ForgeUnreachable as exc:
311 fail(exc.line.strip())
312 return True
313
314
315def _drive(
316 flavor: str,
317 *,
318 armed: bool,
319 names: tuple[str, ...] = (),
320) -> None:
321 from livery.workshop._extensions import workspace_root
322 from livery.workshop._forge_lane import this_repository
323
324 root = workspace_root()
325 if root is None:325 ↛ 326line 325 didn't jump to line 326 because the condition on line 325 was never true
326 fail("no workspace: no workshop.toml above the working directory")
327 repo = this_repository(root)
328 driver = UpdateDriver(root, flavor, armed=armed, names=names)
329 run_workflow(driver, repo, root)
330 if not armed:330 ↛ 331line 330 didn't jump to line 331 because the condition on line 330 was never true
331 return
332 # Parked by a live release: wait, then finish ourselves. The
333 # re-run re-prepares (fresh floors included) and arms.
334 if not _live_releases(repo, root):
335 return
336 interactive = footman.attended()
337 # timeout and poll read at call time so a bounded test can move them.
338 if wait_for_releases(
339 repo, root, interactive=interactive, timeout=BOUNDED_WAIT, poll=WAIT_POLL
340 ):
341 fresh = UpdateDriver(root, flavor, armed=armed, names=names, refresh=True)
342 run_workflow(fresh, repo, root)
343 return
344 print(
345 " still parked: the release outlasted the wait. Run"
346 f" `{footman.prog()} workflow.update` any time to continue; the re-run also"
347 " raises floors to whatever released meanwhile."
348 )
349
350
351update_group = workflow.group("update", help="Bring the workspace current")
352
353
354@update_group.task(name="dependencies")
355def update_dependencies(
356 *names: str,
357 armed: Annotated[bool, doc("arm the update's PR to merge on green")] = False,
358) -> None:
359 """Bring dependencies current in both of their homes.
360
361 Bare upgrades every external dependency through the lock and
362 raises every sibling floor to its latest release; naming
363 dependencies scopes which move, never where, one workspace lock
364 is one resolution. A named sibling moves its floor and only its
365 floor, since the lock cannot move what resolves from source.
366 """
367 _drive("dependencies", armed=armed, names=names)
368
369
370@update_group.default
371def update_default(
372 armed: Annotated[bool, doc("arm the update's PR to merge on green")] = False,
373) -> None:
374 """Bring every dependency current: the bare `workflow.update.dependencies`."""
375 _drive("dependencies", armed=armed)
376
377
378def _locked_workshop(root: pathlib.Path) -> str:
379 """livery-workshop's locked registry version; empty when from source.
380
381 The monorepo consumes the workshop from source, where the lock
382 entry carries no registry version and the running code is always
383 the tree's; only an instance's locked wheel can go stale under
384 its own update.
385 """
386 lock = root / "uv.lock"
387 if not lock.is_file():387 ↛ 389line 387 didn't jump to line 389 because the condition on line 387 was always true
388 return ""
389 text = lock.read_text("utf-8")
390 marker = 'name = "livery-workshop"'
391 start = text.find(marker)
392 if start == -1:
393 return ""
394 block = text[start : start + 400]
395 if "registry" not in block:
396 return ""
397 for line in block.splitlines():
398 if line.startswith("version = "):
399 return line.split('"')[1]
400 return ""