Coverage for packages/workshop/src/livery/workshop/_sweep.py: 90%

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"""What the workshop leaves in the runner's directories, and the sweep that bounds it.
2
3The runner's data directory holds the workshop's durable state: the
4issue worktrees under ``worktrees/<repo>/`` and the loop's workspace.
5footman's collector never touches it, by design. This module is the
6workshop's sweeper, registered under footman's ``footman.sweepers``
7entry point and run by ``fm janitor``, by the daily collector child,
8and, for the worktrees alone, by every ``fm start``.
9It also runs the state store's own janitor over every series the
10workshop keeps ([livery.workshop._series][]), in the scope the run
11has: the checkout's local series on a machine, the remote series too
12inside CI.
13
14The rules, each saying what went or why it stayed:
15
16- A worktree whose linked git directory is gone (its checkout was
17 deleted) goes. This rule is quick and offline: no forge is asked.
18- A worktree whose issue is closed, or whose branch's pull request
19 merged, goes when the branch holds nothing that exists nowhere else,
20 decided by the one keep-or-drop rule ``fm issue.close`` uses
21 ([livery.workshop._submit.only_local_work][]): a tree whose tip the
22 merge took holds nothing only there, whatever a squash did to the
23 ancestry. A tree with uncommitted changes or commits past the merge
24 stays and is named, and so is a tree whose issue is open or whose
25 forge cannot be asked. A closed issue's tree also stays while its
26 branch heads an open pull request, as ``fm issue.close`` leaves it,
27 since that pull request still needs the branch. A tree whose name
28 carries no issue number is judged by its branch's pull request
29 alone. This rule asks the forge, since asking is what proves the
30 removal safe.
31- A local branch of the checkout whose pull request merged and took
32 its tip goes by the same rule; the branch a linked worktree holds
33 belongs to the worktree rule, and the branch the checkout stands on
34 is named for ``fm sync`` to step off. On demand only, like the rule
35 above.
36- Every declared series of the state store is bounded, windows,
37 ages, and orphans, as [livery.git.sweep][] says.
38- The config directory is reported, never touched: anything beside the
39 user's config, tasks file, and shared env file is named. The loop's
40 workspace is reported by size and kept.
41"""
42
43from __future__ import annotations
44
45import shutil
46from datetime import datetime
47from pathlib import Path
48from typing import Any
49
50import livery.footman as footman
51from livery import git
52
53#: The workshop's homes under the data directory.
54WORKTREES = "worktrees"
55LOOP = "workshop-e2e"
56
57#: What the config directory is for; anything else is reported.
58CONFIG_OWN = ("config.toml", ".repo.shared.env", "__pycache__")
59
60
61def sweep(
62 *, data_dir: Path, config_dir: Path, dry_run: bool, now: datetime, **facts: Any
63) -> list[str]:
64 """The workshop's sweep, footman's sweeper contract; the lines to print.
65
66 The state store's series are the checkout's: the one above the
67 working directory, or the ``root`` among *facts* when one is
68 given, ``None`` for no checkout at all.
69 """
70 from livery.workshop._extensions import workspace_root
71
72 root = facts["root"] if "root" in facts else workspace_root()
73 lines = sweep_worktrees(data_dir / WORKTREES, dry_run=dry_run)
74 lines += sweep_branches(root, dry_run=dry_run)
75 lines += sweep_store(root, dry_run=dry_run, now=now)
76 lines += report_config(config_dir)
77 lines += report_loop(data_dir / LOOP)
78 return lines
79
80
81# --- the worktrees -------------------------------------------------------------
82
83
84def _gitdir(tree: Path) -> Path | None:
85 """The linked git directory a worktree's ``.git`` file names, or None."""
86 marker = tree / ".git"
87 if not marker.is_file():
88 return None
89 text = marker.read_text("utf-8").strip()
90 if not text.startswith("gitdir:"):90 ↛ 91line 90 didn't jump to line 91 because the condition on line 90 was never true
91 return None
92 return Path(text[len("gitdir:") :].strip())
93
94
95def _remove_worktree(tree: Path, gitdir: Path | None) -> None:
96 """Remove *tree* through its checkout's git when that checkout exists."""
97 if gitdir is not None and gitdir.exists():
98 # <checkout>/.git/worktrees/<name>: the checkout is three up.
99 checkout = gitdir.parent.parent.parent
100 try:
101 git.run(checkout, "worktree", "remove", "--force", str(tree))
102 return
103 except git.GitError:
104 pass
105 shutil.rmtree(tree, ignore_errors=True)
106 if gitdir is not None and gitdir.exists():106 ↛ 107line 106 didn't jump to line 107 because the condition on line 106 was never true
107 with _quiet():
108 git.run(gitdir.parent.parent.parent, "worktree", "prune")
109
110
111class _quiet:
112 def __enter__(self) -> None:
113 return None
114
115 def __exit__(self, *exc: object) -> bool:
116 return True
117
118
119def _repository(tree: Path) -> Any:
120 from livery.workshop._forge_lane import this_repository
121
122 return this_repository(tree)
123
124
125def _done(
126 tree: Path, number: int | None, branch: str, root: Path
127) -> tuple[bool, str, str]:
128 """Whether the work landed, why or why not, and the merged pull request's head.
129
130 Landed is the issue closed or the branch's pull request merged; a
131 tree named after no issue has only the pull request to answer.
132 A closed issue whose branch still heads an open pull request has
133 not landed: the tree stays for that pull request, as
134 ``fm issue.close`` leaves it. The merged head is ``""`` when no
135 pull request merged.
136 """
137 from livery.workshop._submit import merged_pull_request
138
139 try:
140 repo = _repository(tree)
141 pull = merged_pull_request(repo, root, branch)
142 head = pull.head_sha if pull is not None else ""
143 if number is not None:
144 work = repo.issue.get(number)
145 if work is not None and work.state == "closed":
146 live = repo.pr.find_by_head(branch) if pull is None else None
147 if live is not None and live.state == "open":
148 return (
149 False,
150 f"issue #{number} is closed, but PR #{live.number}"
151 " is open from its branch",
152 "",
153 )
154 return True, f"issue #{number} is closed", head
155 if pull is not None:
156 return True, f"PR #{pull.number} merged", head
157 except Exception as error:
158 return False, f"the forge could not be asked ({error})", ""
159 if number is None:
160 return False, "no merged pull request", ""
161 return False, f"issue #{number} is open", ""
162
163
164def sweep_worktrees(home: Path, *, dry_run: bool) -> list[str]:
165 """Sweep every ``<repo>/<number>-<slug>`` worktree under *home*; the lines."""
166 from livery.workshop._submit import only_local_work
167
168 lines: list[str] = []
169 if not home.is_dir():
170 return lines
171 verb = "would remove" if dry_run else "removed"
172 for repo_dir in sorted(p for p in home.iterdir() if p.is_dir()):
173 for tree in sorted(p for p in repo_dir.iterdir() if p.is_dir()):
174 name = f"{repo_dir.name}/{tree.name}"
175 gitdir = _gitdir(tree)
176 if gitdir is None:
177 lines.append(f"worktree {name}: not a linked worktree; kept")
178 continue
179 if not gitdir.exists():
180 lines.append(f"worktree {name}: its checkout is gone; {verb}")
181 if not dry_run:181 ↛ 183line 181 didn't jump to line 183 because the condition on line 181 was always true
182 _remove_worktree(tree, None)
183 continue
184 head, _, _rest = tree.name.partition("-")
185 number = int(head) if head.isdigit() else None
186 try:
187 branch = git.current_branch(tree)
188 except git.GitError as error:
189 lines.append(f"worktree {name}: git could not answer ({error}); kept")
190 continue
191 done, why, merged_head = _done(tree, number, branch, tree)
192 if not done:
193 lines.append(f"worktree {name}: {why}; kept")
194 continue
195 try:
196 only_local = only_local_work(tree, branch, merged_head=merged_head)
197 except git.GitError as error:
198 lines.append(f"worktree {name}: git could not answer ({error}); kept")
199 continue
200 if only_local:
201 lines.append(f"worktree {name}: {why}, but it holds {only_local}; kept")
202 continue
203 lines.append(f"worktree {name}: {why}, nothing only here; {verb}")
204 if not dry_run:
205 _remove_worktree(tree, gitdir)
206 return lines
207
208
209def sweep_branches(root: Path | None, *, dry_run: bool) -> list[str]:
210 """Drop the checkout's local branches whose pull request merged and took their tip.
211
212 A branch a linked worktree holds is the worktree rule's; the base
213 branch is never touched; the branch the checkout stands on is
214 named, since a sweep never moves a person's HEAD. Asks the forge,
215 since asking is what proves the removal safe. The lines say what
216 went and why the rest stayed.
217 """
218 if root is None:
219 return []
220 from livery.workshop._submit import worktree_for
221
222 try:
223 current = git.current_branch(root)
224 branches = git.local_branches(root, "")
225 except git.GitError as error:
226 return [f"branches: git could not answer ({error}); kept"]
227 lines: list[str] = []
228 for branch in branches:
229 if branch == "main" or worktree_for(root, branch):
230 continue
231 _went, line = sweep_branch(root, branch, current=current, dry_run=dry_run)
232 lines.append(line)
233 return lines
234
235
236def sweep_branch(
237 root: Path,
238 branch: str,
239 *,
240 current: str,
241 dry_run: bool,
242 repo: Any = None,
243) -> tuple[bool, str]:
244 """Drop *branch* when its pull request merged and took its tip; whether it went.
245
246 The rule `sweep_branches` applies to each of the checkout's
247 branches, for one. ``fm start`` asks it before it re-enters a
248 branch that has no worktree, since a merged branch is finished work
249 and a start begins fresh. The branch the checkout stands on
250 (*current*) stays, named for ``fm sync`` to step off, and so does
251 one whose forge cannot be asked. *repo* is the forge's repository,
252 asked for when absent. The line says what went, or why it stayed.
253 """
254 from livery.workshop._submit import merged_pull_request, only_local_work
255
256 try:
257 found = merged_pull_request(
258 repo if repo is not None else _repository(root), root, branch
259 )
260 except Exception as error:
261 return False, f"branch {branch}: the forge could not be asked ({error}); kept"
262 if found is None:
263 return False, f"branch {branch}: no merged pull request; kept"
264 only_local = only_local_work(root, branch, merged_head=found.head_sha)
265 if only_local:
266 return False, (
267 f"branch {branch}: PR #{found.number} merged, but it holds"
268 f" {only_local}; kept"
269 )
270 if branch == current:
271 return False, (
272 f"branch {branch}: PR #{found.number} merged, but the checkout"
273 f" stands on it; `{footman.prog()} sync` steps off it"
274 )
275 if not dry_run:
276 git.delete_branch(root, branch)
277 verb = "would remove" if dry_run else "removed"
278 return (
279 True,
280 f"branch {branch}: PR #{found.number} merged, nothing only here; {verb}",
281 )
282
283
284# --- the rest of the data directory --------------------------------------------
285
286
287def sweep_store(root: Path | None, *, dry_run: bool, now: datetime) -> list[str]:
288 """Bound every declared series of the state store in the run's scope; the lines."""
289 from contextlib import nullcontext
290
291 from livery.git import WHOLE, remote_snapshot
292 from livery.git import sweep as sweep_series
293 from livery.workshop._ci_context import run_context, state_store
294 from livery.workshop._series import declared
295
296 if root is None:
297 return ["state store: no checkout here; nothing swept"]
298 remote = run_context() is not None
299 # The remote sweep reads every series: one listing and one fetch.
300 scope = remote_snapshot(state_store(root), fetch=WHOLE) if remote else nullcontext()
301 with scope:
302 lines = sweep_series(
303 state_store(root), declared(root), remote=remote, dry_run=dry_run, now=now
304 )
305 return [f"state store: {line.strip()}" for line in lines]
306
307
308def report_config(config_dir: Path) -> list[str]:
309 """Name what sits in the config directory beside the user's own files."""
310 from livery.footman import tasks_file_name
311
312 if not config_dir.is_dir():
313 return []
314 own = {*CONFIG_OWN, tasks_file_name()}
315 foreign = sorted(p.name for p in config_dir.iterdir() if p.name not in own)
316 if not foreign:316 ↛ 317line 316 didn't jump to line 317 because the condition on line 316 was never true
317 return []
318 return [
319 f"config: {name} is not the config, the tasks file, or the shared env;"
320 " yours to remove"
321 for name in foreign
322 ]
323
324
325def report_loop(home: Path) -> list[str]:
326 """The loop's workspace by size, kept: `fm ci.e2e` reuses it."""
327 if not home.is_dir():
328 return []
329 total = sum(p.stat().st_size for p in home.rglob("*") if p.is_file())
330 import livery.footman as footman
331
332 return [
333 f"loop workspace: {total / 1e6:.0f} MB at {home};"
334 f" kept for `{footman.prog()} ci.e2e`"
335 ]