Coverage for packages/workshop/src/livery/workshop/_tool_tasks.py: 100%

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 ``tools`` group: declare a tool, lock the versions, upgrade one, write the stubs.
2
3Every verb resolves against the catalogue `[toolroom] index` names and
4writes `toolroom.lock` at the root; a lock that cannot be met refuses
5naming the tool, each floor with the site that declared it, and the
6host no eligible version has. Each lock verb then writes the stubs
7under `typings/`, and `restub` writes them alone.
8"""
9
10from __future__ import annotations
11
12from typing import TYPE_CHECKING, Annotated
13
14from livery.footman import doc, fail, group, prog
15
16if TYPE_CHECKING:
17 from pathlib import Path
18
19 from livery.toolroom.store import Lock
20
21tools = group(
22 "toolroom",
23 help="The tools the workspace requires: declare, lock, upgrade, restub",
24)
25
26
27def _root() -> Path:
28 from livery.workshop._extensions import workspace_root
29
30 root = workspace_root()
31 if root is None:
32 fail("no workspace: no workshop.toml above the working directory")
33 return root
34
35
36def _report(lock: Lock, moved: tuple[str, ...] = ()) -> None:
37 from livery.toolroom.store import LOCK_FILE
38
39 for name in sorted(lock.tools):
40 mark = " moved" if name in moved else ""
41 scope = lock.tools[name].on
42 where = f" on {', '.join(scope)}" if scope else ""
43 print(f" {name} {lock.tools[name].version}{where}{mark}")
44 print(f" {LOCK_FILE}: {len(lock.tools)} tool(s) on {', '.join(lock.hosts)}")
45
46
47@tools.task(name="lock")
48def tools_lock(
49 upgrade: Annotated[
50 bool, doc("move every entry to the newest version that satisfies")
51 ] = False,
52 upgrade_tool: Annotated[
53 list[str] | None, doc("move just these entries to their newest")
54 ] = None,
55 check: Annotated[bool, doc("report whether the lock is current; write nothing")] = (
56 False
57 ),
58 relock: Annotated[
59 list[str] | None, doc("delegated tools whose graph is resolved again")
60 ] = None,
61) -> None:
62 """Resolve every site's requirements and write `toolroom.lock`.
63
64 An entry the lock already holds stands while it still satisfies
65 every floor and resolves on every locked host; a tool no site
66 requires any more leaves the lock. Nothing on a machine changes:
67 the lock says what a checkout installs, and `sync` installs it.
68
69 ``--upgrade`` moves every entry to the newest version that
70 satisfies, and ``--upgrade-tool`` moves the ones it names. An
71 upgrade is an act on the repository: every package runs the version
72 the lock names, so one entry moving moves every package with it.
73
74 ``--check`` answers whether the lock is current and writes nothing,
75 exiting non-zero when it would move. A delegated tool's resolved
76 graph is written when its version enters the lock and kept after;
77 ``--relock`` writes one again though the version stands, which is
78 what an install asks for when it refuses because the runtime has no
79 build for what the graph pins.
80 """
81 from livery.toolroom.store import LOCK_FILE
82 from livery.workshop._tools import (
83 current_lock,
84 lock_is_current,
85 stub_lines,
86 tool_names,
87 write_lock,
88 )
89
90 root = _root()
91 named = tuple(upgrade_tool or ())
92 if check:
93 if upgrade or named or relock:
94 fail("--check writes nothing, so it cannot be asked to upgrade or relock")
95 current, why = lock_is_current(root)
96 if not current:
97 fail(f"the lock is not current: {why}; run `{prog()} toolroom.lock`")
98 print(f" {LOCK_FILE}: current")
99 return
100 before = current_lock(root)
101 moving = tool_names(root) if upgrade else named
102 lock = write_lock(root, upgrade=moving, relock=tuple(relock or ()))
103 for name in named:
104 if name not in lock.tools:
105 held = ", ".join(sorted(lock.tools)) or "nothing"
106 fail(f"{name} is not a tool the sites require; the lock holds {held}")
107 moved = tuple(
108 name
109 for name in moving
110 if before is None
111 or name not in before.tools
112 or name not in lock.tools
113 or before.tools[name].version != lock.tools[name].version
114 )
115 _report(lock, moved)
116 if moving and not moved:
117 listed = ", ".join(moving)
118 print(f" nothing moved: {listed} already at the newest eligible version")
119 for line in stub_lines(root, strict=False):
120 print(line)
121
122
123@tools.task(name="add")
124def tools_add(
125 requirement: Annotated[str, doc("the tool, `name` or `name>=floor`")],
126) -> None:
127 """Declare a tool at the project site, lock it, and materialise it.
128
129 The requirement joins `[toolroom] requires` in the root `workshop.toml`
130 unless it is already there, the lock is resolved with it, and the
131 tool is supplied through the store on this machine with its receipt
132 written. A spelling that is not a requirement refuses before
133 anything is written.
134 """
135 from livery.toolroom.store import Requirement
136 from livery.workshop._tools import declare, materialise, stub_lines, write_lock
137
138 root = _root()
139 if declare(root, requirement):
140 print(f" workshop.toml: [toolroom] requires {requirement}")
141 else:
142 print(f" workshop.toml: {requirement} was declared already")
143 lock = write_lock(root)
144 _report(lock)
145 name = Requirement.parse(requirement).name
146 (made,) = materialise(root, (name,))
147 assert made.receipt is not None # strict: a refusal never reaches here
148 where = made.receipt.tool_dir
149 state = "installed" if made.installed else "present"
150 print(f" {name} {made.receipt.version}: {state} at {where}, receipt written")
151 for line in stub_lines(root, strict=False):
152 print(line)
153
154
155@tools.task(name="sync")
156def tools_sync(
157 frozen: Annotated[bool, doc("install the lock as it is; never resolve")] = False,
158 locked: Annotated[bool, doc("refuse if the lock is not current")] = False,
159 offline: Annotated[
160 bool, doc("supply from the machine's store and its sources only")
161 ] = False,
162) -> None:
163 """Match this machine to `toolroom.lock`, writing the lock first if it must.
164
165 What `sync` does for the tools alone, in uv's shape. By default the
166 lock is written when there is none or when the sites' requirements
167 have moved past it, and then every tool it names is supplied
168 through the store, a receipt per tool says what reached PATH, and
169 the stubs follow. A tool the store cannot supply is reported and
170 the others are supplied.
171
172 ``--frozen`` installs the lock exactly as it is and resolves
173 nothing, which is what a CI job wants: a runner's checkout is
174 judged, never re-resolved. ``--locked`` refuses when the lock is
175 not current instead of writing it, which is the assertion a gate
176 makes. ``--offline`` reads the catalogue and the deployments from
177 the machine's store alone.
178 """
179 if frozen and locked:
180 fail(
181 "--frozen and --locked are two answers to one question: frozen"
182 " installs the lock as it is, locked refuses when it is not"
183 " current. Pass one."
184 )
185 sync_tools(_root(), frozen=frozen, locked=locked, offline=offline)
186
187
188def sync_tools(
189 root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False
190) -> None:
191 """Match this machine to *root*'s `toolroom.lock`, writing it first if it must.
192
193 The engine behind ``toolroom.sync``, taking the workspace root as an
194 argument: a birth runs it for the newborn from inside its own
195 task, and a task may not change the process directory, so the
196 root travels as a value; ``sync`` calls it for the same reason.
197 The flags mean what the task's do. Once the lock stands, the
198 receipts are read before anything is supplied
199 ([livery.workshop._reconcile.tools_current][]): when every tool the
200 lock holds for this host has its receipt at the locked version and
201 its directory in the store, nothing is supplied and the line says
202 the tools are up to date. A receipt that is off names itself, and
203 the supply writes it again.
204 """
205 from livery.toolroom.store import LOCK_FILE
206 from livery.workshop._reconcile import tools_current
207 from livery.workshop._sync import materialise_tools
208 from livery.workshop._tools import lock_is_current, write_lock
209
210 if not frozen:
211 current, why = lock_is_current(root, offline=offline)
212 if not current:
213 if locked:
214 fail(
215 f"--locked: {why}. Run `{prog()} toolroom.lock` and"
216 " commit what it writes."
217 )
218 print(f" {LOCK_FILE}: {why}; writing it")
219 _report(write_lock(root, offline=offline))
220 if (root / LOCK_FILE).is_file():
221 off = tools_current(root)
222 if not off:
223 print(" tools: up to date")
224 return
225 print(f" tools: {off}; supplying")
226 for line in materialise_tools(root, offline=offline):
227 print(line)
228
229
230@tools.task(name="restub")
231def tools_restub(
232 offline: Annotated[
233 bool, doc("read the index from the machine's store only")
234 ] = False,
235) -> None:
236 """Write the stubs the catalogue offers into `typings/`.
237
238 One stub per tool the lock holds, at the locked version, as
239 `livery.toolroom.stubs` modules, and `livery.toolroom.handles`
240 beside them declaring the handles for the tools package's index to
241 import. The four checkers read `typings/` first,
242 so a locked tool's handle completes with its own verbs and flags;
243 a tool the workspace does not deploy gets no stub and types as a
244 bare `Tool`. `sync` and the lock verbs write them too; this writes
245 them alone, offline from the machine's store with `--offline`.
246 """
247 from livery.workshop._tools import stub_lines
248
249 for line in stub_lines(_root(), offline=offline):
250 print(line)