Coverage for packages/workshop/src/livery/workshop/_run.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"""Start a package's executable after a development build of what it needs.
2
3``fm run <package>[:<executable>] -- <arguments>`` names a package and
4one of the executables its extensions answer under ``executables``
5([livery.workshop.EXECUTABLES][]). It first builds the package's
6dependency closure, dependencies first, each member through the steps
7its set adds to the ``build`` phase's tree side, in the ``debug``
8configuration, and skips each member whose files and dependencies are
9unchanged since its last good build in this checkout; the record of
10those builds lives under ``.workshop/.cache/run/``. Then it runs the
11``run`` phase through the one walk
12([livery.workshop._phases.walk_steps][]): every step the
13package's set adds to it, except that of the extensions answering
14``executables`` only the owner's steps run. The engine gives the phase
15the executable under ``executable``, which a step reads as it reads
16any engine key, and the words after ``--`` are the context's
17``arguments``. The verb exits with the code the step that started the
18executable recorded.
19"""
20
21from __future__ import annotations
22
23import hashlib
24import json
25import sys
26from pathlib import Path
27from typing import TYPE_CHECKING, Annotated
28
29from livery import git
30from livery.footman import Arg, cwd, doc, fail, passthrough, prog, suggest, task
31
32if TYPE_CHECKING:
33 from livery.workshop._packages import Package
34 from livery.workshop._steps import StepRecord
35
36#: The record of the development builds, under the workspace root.
37RECORD = Path(".workshop") / ".cache" / "run" / "built.json"
38
39#: What the development build gives the build phase: the tree side, in
40#: the debug configuration.
41DEVELOP_INPUTS: dict[str, dict[str, object]] = {
42 "build": {"isolated": False, "configuration": "debug"}
43}
44
45
46def _targets() -> list[str]:
47 """Each ``package:executable`` the workspace's packages answer, for completion.
48
49 A package with one executable is offered by its name alone too. A
50 package whose extensions answer in a way the query refuses is left
51 out: completion offers what runs.
52 """
53 from livery.workshop._extensions import workspace_root
54 from livery.workshop._packages import discover_packages
55 from livery.workshop._queries import EXECUTABLES, QueryError, answer
56
57 root = workspace_root()
58 if root is None:
59 return []
60 found: list[str] = []
61 for package in discover_packages(root):
62 try:
63 names = answer(package, EXECUTABLES)
64 except QueryError:
65 continue
66 if len(names) == 1:
67 found.append(package.member)
68 found += [f"{package.member}:{name}" for name in names]
69 return found
70
71
72@task(cwd="asinvoked")
73def run(
74 target: Annotated[
75 Arg[str],
76 doc(
77 "package[:executable]; the package may be left out inside its directory,"
78 " and the executable when the package has one"
79 ),
80 suggest(_targets, strict=False),
81 ] = "",
82) -> int:
83 """Build what a package's executable needs, start it, and exit with its code.
84
85 The build phase's tree side runs over the package's dependency
86 closure first, skipping what is unchanged since its last good
87 build; then the run phase starts the executable with the words
88 after ``--``.
89 """
90 from livery.workshop._extensions import workspace_root
91
92 here = cwd()
93 root = workspace_root(here)
94 if root is None:
95 fail("no workspace: no workshop.toml above the working directory")
96 return start(root, target, tuple(passthrough()), here)
97
98
99def start(root: Path, target: str, arguments: tuple[str, ...], cwd: Path) -> int:
100 """Run *target*'s executable in the workspace at *root*; its exit code.
101
102 *cwd* decides the package a target that names none means. The
103 development build runs first ([livery.workshop._run.develop][]).
104 """
105 from livery.workshop._composition import closure
106 from livery.workshop._extensions import installed_declaration
107 from livery.workshop._packages import discover_packages
108 from livery.workshop._phases import (
109 PhaseContext,
110 PhaseError,
111 phase_steps,
112 walk_steps,
113 )
114 from livery.workshop._queries import EXECUTABLES, QueryError, answer, answers
115
116 packages = discover_packages(root)
117 package, executable = _resolve(root, packages, target, cwd)
118 try:
119 names = answer(package, EXECUTABLES)
120 except QueryError as error:
121 fail(str(error))
122 if not names:
123 fail(f"{package.path} has no executable: no extension of its set answers one")
124 if not executable:
125 if len(names) != 1:
126 fail(
127 f"{package.path} has the executables {', '.join(names)}; name one:"
128 f" `{prog()} run {package.member}:{names[0]}`"
129 )
130 (executable,) = names
131 answering = answers(package, EXECUTABLES)
132 owners = {name for name, held in answering.items() if executable in held}
133 if not owners:
134 fail(
135 f"{package.path} has no executable named {executable}; its executables"
136 f" are {', '.join(names)}"
137 )
138 develop(root, package, packages)
139 # The run steps of an extension answering executables start them,
140 # so of those the owner's run alone; every other extension's run.
141 members = closure(package.extensions, installed_declaration)
142 steps = tuple(
143 record
144 for record in phase_steps("run", members, installed_declaration)
145 if record.extension not in answering or record.extension in owners
146 )
147 ctx = PhaseContext(
148 root=root,
149 packages=(package,),
150 package=package,
151 phase="run",
152 arguments=arguments,
153 )
154 try:
155 ctx = walk_steps(ctx, steps, inputs={"run": {"executable": executable}})
156 except PhaseError as error:
157 fail(str(error))
158 return ctx.exit_code
159
160
161def _resolve(
162 root: Path, packages: tuple[Package, ...], target: str, cwd: Path
163) -> tuple[Package, str]:
164 """The package and the executable *target* names; an empty name for none.
165
166 ``package:executable`` names both. A bare word is a package when one
167 is named so, by its directory under ``packages/``, its path or its
168 distribution's name; else, inside a package's directory, an
169 executable of that package. Inside it, nothing at all names the
170 package.
171 """
172 named, colon, executable = target.partition(":")
173 package = _named(packages, named) if named else None
174 if package is not None:
175 return package, executable
176 here = None if named and colon else _holding(root, packages, cwd)
177 if here is not None:
178 # Inside a package, a bare word names one of its executables.
179 return here, executable if colon else named
180 if named:
181 fail(f"no package is named {named}: {_known(packages)}")
182 fail(
183 f"name a package, `{prog()} run <package>[:<executable>]`, or run it"
184 f" inside a package's directory: {_known(packages)}"
185 )
186
187
188def _named(packages: tuple[Package, ...], name: str) -> Package | None:
189 """The package named *name* by its member, its path or its distribution; None."""
190 for package in packages:
191 if name in (package.member, package.path, package.name):
192 return package
193 return None
194
195
196def _holding(root: Path, packages: tuple[Package, ...], cwd: Path) -> Package | None:
197 """The package whose directory holds *cwd*; None outside every package."""
198 here = cwd.resolve()
199 for package in packages:
200 directory = (root / package.path).resolve()
201 if here == directory or directory in here.parents:
202 return package
203 return None
204
205
206def _known(packages: tuple[Package, ...]) -> str:
207 """The packages a target may name, for a refusal."""
208 if not packages:
209 return "the workspace has no packages"
210 return "the packages are " + ", ".join(package.member for package in packages)
211
212
213def develop(root: Path, package: Package, packages: tuple[Package, ...]) -> list[str]:
214 """Build *package*'s dependency closure in the build phase; the paths built.
215
216 Dependencies come first, each through the steps its set adds to the
217 build phase that serve the tree side, in the ``debug``
218 configuration ([livery.workshop._run.DEVELOP_INPUTS][]), run
219 through the one walk as the release train runs a package's phase.
220 A member is built when its files, or the fingerprint of a
221 dependency, differ from its last good build in this checkout, so a
222 dependency that changed rebuilds what depends on it; a member whose
223 set adds no such step is never built. With nothing changed, no
224 build step runs. A checkout git cannot read is built whole, and
225 says so.
226 """
227 from livery.workshop._graph import dependencies_closure, order_topologically
228
229 closure = order_topologically(dependencies_closure(packages, {package.path}))
230 try:
231 tree = git.working_tree_id(root)
232 except git.GitError as error:
233 print(
234 f" run: git cannot read this checkout, so every member builds: {error}",
235 file=sys.stderr,
236 )
237 tree = ""
238 ids = _subtrees(root, tree, closure)
239 record = _read(root)
240 prints: dict[str, str] = {}
241 built: list[str] = []
242 for member in closure:
243 own = ids.get(member.path, "")
244 needs = sorted(
245 prints[edge.path] for edge in member.depends if edge.path in prints
246 )
247 fingerprint = hashlib.sha256("\n".join((own, *needs)).encode()).hexdigest()
248 prints[member.path] = fingerprint
249 steps = _build_steps(member)
250 if not steps or (own and record.get(member.path) == fingerprint):
251 continue
252 _build(root, member, steps)
253 built.append(member.path)
254 if own:
255 record[member.path] = fingerprint
256 _write(root, record)
257 return built
258
259
260def _build_steps(member: Package) -> tuple[StepRecord, ...]:
261 """The steps *member*'s set adds to the build phase that serve the tree side."""
262 from livery.workshop._composition import extension_set
263 from livery.workshop._extensions import installed_declaration
264 from livery.workshop._phases import phase_steps, serves
265
266 side = DEVELOP_INPUTS["build"]
267 return tuple(
268 record
269 for record in phase_steps("build", extension_set(member), installed_declaration)
270 if serves(record, side)
271 )
272
273
274def _build(root: Path, member: Package, steps: tuple[StepRecord, ...]) -> None:
275 """Run *steps* over *member*, the development build's inputs given the phase.
276
277 Raises:
278 Failed: when the steps cannot run as declared, with the walk's
279 reason.
280 """
281 from livery.workshop._phases import PhaseContext, PhaseError, walk_steps
282
283 ctx = PhaseContext(root=root, packages=(member,), package=member, phase="build")
284 try:
285 walk_steps(ctx, steps, inputs=DEVELOP_INPUTS)
286 except PhaseError as error:
287 fail(str(error))
288
289
290def _subtrees(root: Path, tree: str, members: tuple[Package, ...]) -> dict[str, str]:
291 """Each of *members*' paths that *tree* holds, to its id, read in one process.
292
293 Empty without a tree, so every member builds.
294 """
295 if not tree:
296 return {}
297 return git.object_ids(root, tree, [member.path for member in members])
298
299
300def _read(root: Path) -> dict[str, str]:
301 """The record of good builds: each member's path to its fingerprint."""
302 path = root / RECORD
303 try:
304 data = json.loads(path.read_text("utf-8"))
305 except (OSError, ValueError):
306 return {}
307 return (
308 {str(key): str(value) for key, value in data.items()}
309 if isinstance(data, dict)
310 else {}
311 )
312
313
314def _write(root: Path, record: dict[str, str]) -> None:
315 """Keep *record* for the next run in this checkout."""
316 path = root / RECORD
317 path.parent.mkdir(parents=True, exist_ok=True)
318 path.write_text(json.dumps(record, indent=2, sort_keys=True) + "\n", "utf-8")