Coverage for packages/workshop/src/livery/workshop/_shipped_files.py: 96%

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"""Deliver the files the listed extensions ship, through the fragment engine.
2
3An extension ships a workspace file as a template in its wheel, under
4`content/root/<path>` for a file at the workspace root and
5`content/package/<path>` for that file in every package listing the
6extension; a `.jinja` suffix on the source is dropped for the
7target. Under `content/for/<target>/root/` and
8`content/for/<target>/package/` it ships the files it adds to another
9extension, delivered while its `[for.<target>]` table applies
10([livery.workshop._extensions.contributing][]). `fm sync` composes them with
11[livery.workshop._fragment_engine.plan][] and writes them with
12[livery.workshop._fragment_engine.apply][]; the gate's ``drift.check``
13judges them with [livery.workshop._fragment_engine.drift][].
14
15An extension takes the place of a shipped file of the base or of an
16extension it requires by declaring it in its `extension.toml`:
17`[replaces] "<owner>:<name>" = "<reason>"`, where its own file of the
18same name is the replacement, or `[deletes]` with the same shape to
19remove it. Each applies after what it requires, so the replacement
20follows no list's order. The same declarations govern seeds
21([livery.workshop._seeds.create][]).
22
23An extension also writes files from its own code: each
24`[fragments."<target>"]` table in its `extension.toml` names a render
25the engine calls with the workspace root, for one file or, with a
26target ending in `/`, a directory of them
27([livery.workshop._shipped_files.computed_outputs][]), and a
28`[for.<target>.fragments]` table does the same while it applies. An
29extension's files are written while the installed set holds it, the
30root's set or a package's, and withdrawn when no list holds it any
31more ([livery.workshop._shipped_files.delivery_order][]).
32"""
33
34from __future__ import annotations
35
36import json
37from dataclasses import replace
38from operator import itemgetter
39from pathlib import Path
40from typing import Any, cast
41
42import livery.footman as footman
43from livery.footman import fail
44from livery.workshop._extensions import (
45 SELF,
46 contributing,
47 declaration,
48 extension_content,
49 stack_names,
50)
51from livery.workshop._fragment_engine import (
52 PACKAGE_PREFIX,
53 Fragment,
54 Output,
55 apply,
56 drift,
57 plan,
58 write_root_file,
59)
60
61ROOT_CONTENT = "root"
62"""The `content/` subdirectory whose files land at the workspace root."""
63
64PACKAGE_CONTENT = "package"
65"""The `content/` subdirectory whose files land in each package."""
66
67FOR_CONTENT = "for"
68"""The `content/` subdirectory holding, per target, the files an extension
69adds to another: `for/<target>/root/` and `for/<target>/package/`."""
70
71TEMPLATE = ".jinja"
72"""The suffix a shipped template may carry, dropped for its target: a
73template named like a tool's configuration file (`pyproject.toml`) would
74otherwise be read as one by the tool that searches the tree for it."""
75
76PROJECT_FILE = "pyproject.toml"
77"""The workspace's project file, which renders from the contract's identity."""
78
79
80def delivery_order(root: Path) -> list[str]:
81 """The owners whose files a sync delivers to *root*, in the order they apply.
82
83 The stack ([livery.workshop._extensions.stack_names][]): the base,
84 then every extension of the installed set in composition order,
85 which holds every extension a package's set holds.
86 """
87 return list(stack_names(root))
88
89
90def shipped(root: Path) -> tuple[list[Fragment], list[str]]:
91 """Every listed extension's shipped files as fragments, and the order they apply.
92
93 The order is the delivery's
94 ([livery.workshop._shipped_files.delivery_order][]). A file under
95 `content/for/<target>/` comes while the extension's `[for.<target>]`
96 table applies, named `for/<target>/<path>` among the extension's
97 fragments, after its own.
98 """
99 order = delivery_order(root)
100 contributes = contributing(root)
101 fragments: list[Fragment] = []
102 for extension in order:
103 content = extension_content(extension)
104 if content is None:
105 continue
106 trees = [(content, "")] + [
107 (content / FOR_CONTENT / target, f"{FOR_CONTENT}/{target}/")
108 for target in contributes.get(extension, ())
109 ]
110 for tree, named in trees:
111 for kind, prefix in ((ROOT_CONTENT, ""), (PACKAGE_CONTENT, PACKAGE_PREFIX)):
112 base = tree / kind
113 if not base.is_dir():
114 continue
115 for source in sorted(base.rglob("*")):
116 if not source.is_file() or "__pycache__" in source.parts:
117 continue
118 relative = (
119 source.relative_to(base).as_posix().removesuffix(TEMPLATE)
120 )
121 fragments.append(
122 Fragment(
123 extension,
124 f"{named}{relative}",
125 f"{prefix}{relative}",
126 source=source,
127 )
128 )
129 fragments = declared(fragments, order)
130 fragments += _editor_contributions(order, root)
131 from livery.workshop._identity import is_born
132
133 if not is_born(root):
134 # The project file renders from the contract's identity: the
135 # name, the namespace, the authors. A workspace whose contract
136 # names no project composes none.
137 fragments = [f for f in fragments if f.target != PROJECT_FILE]
138 return fragments, order
139
140
141def declared(
142 fragments: list[Fragment], order: list[str], *, seeds: bool = False
143) -> list[Fragment]:
144 """*fragments* with each listed extension's `[replaces]` and `[deletes]` applied.
145
146 A replacement marks the declaring extension's own fragment of the
147 lower one's name; a deletion adds a fragment that only deletes. The
148 lower fragment is the base's or that of an extension the declaring
149 one requires, transitively, so it applies first in *order*, which is
150 composition order. The engine's resolution then checks that the
151 lower fragment exists. Seed declarations (names under `seeds/`)
152 apply with *seeds* set, every other one without.
153
154 Raises:
155 Failed: for a replacement whose extension ships no file of that
156 name, and for a replacement or a deletion of a file of an
157 extension the declaring one does not require.
158 """
159 from livery.workshop._composition import closure
160 from livery.workshop._extensions import installed_declaration
161 from livery.workshop._seeds import SEEDS
162
163 by_ref = {fragment.ref: index for index, fragment in enumerate(fragments)}
164 result = list(fragments)
165 for extension in order:
166 found = None if extension == SELF else declaration(extension)
167 if found is None:
168 continue
169 reached = {SELF, *closure(found.requires, installed_declaration)}
170 for verb, held in (("replaces", found.replaces), ("deletes", found.deletes)):
171 for ref in held:
172 owner = ref.partition(":")[0]
173 named = ref.partition(":")[2].startswith(f"{SEEDS}/") == seeds
174 if named and owner not in reached:
175 fail(
176 f"{extension} {verb} {ref} in its extension.toml, and does"
177 f" not require {owner}; add {owner} to its [extension]"
178 " requires"
179 )
180 for ref, reason in found.deletes.items():
181 if ref.partition(":")[2].startswith(f"{SEEDS}/") == seeds:181 ↛ 180line 181 didn't jump to line 180 because the condition on line 181 was always true
182 result.append(
183 Fragment(
184 extension, f"deletes {ref}", "", deletes=ref, reason=reason
185 )
186 )
187 for ref, reason in found.replaces.items():
188 name = ref.partition(":")[2]
189 if name.startswith(f"{SEEDS}/") != seeds:189 ↛ 190line 189 didn't jump to line 190 because the condition on line 189 was never true
190 continue
191 index = by_ref.get(f"{extension}:{name}")
192 if index is None:192 ↛ 193line 192 didn't jump to line 193 because the condition on line 192 was never true
193 fail(
194 f"{extension} replaces {ref} in its extension.toml and ships no"
195 f" {name} of its own to take its place"
196 )
197 result[index] = replace(result[index], replaces=ref, reason=reason)
198 return result
199
200
201def _editor_contributions(order: list[str], root: Path) -> list[Fragment]:
202 """What the steps and the listed extensions say to the editor, as contributed data.
203
204 A step's settings land in `.vscode/settings.json`, a fragment of
205 its own, so a step that is unregistered takes its lines with it;
206 each listed extension's answer to the ``editor-extensions`` query
207 lands in `.vscode/extensions.json`, so an extension taken off the
208 list takes its recommendations with it.
209 """
210 from livery.workshop._queries import EDITOR_EXTENSIONS, answers
211 from livery.workshop._steps import steps_by_name
212
213 found: list[Fragment] = []
214 for extension, ids in answers(root, EDITOR_EXTENSIONS).items():
215 if extension in order:215 ↛ 214line 215 didn't jump to line 214 because the condition on line 215 was always true
216 found.append(
217 Fragment(
218 extension,
219 f"{extension} recommendations",
220 ".vscode/extensions.json",
221 json.dumps({"recommendations": list(ids)}),
222 contributes=True,
223 )
224 )
225 for name, record in sorted(steps_by_name().items()):
226 if record.extension not in order:
227 continue
228 for fragment in record.fragments:
229 if fragment.file == PROJECT_FILE:229 ↛ 230line 229 didn't jump to line 230 because the condition on line 229 was never true
230 found.append(
231 Fragment(
232 record.extension,
233 f"step {name} tables",
234 PROJECT_FILE,
235 fragment.text,
236 )
237 )
238 if fragment.file == ".vscode/settings.json":
239 found.append(
240 Fragment(
241 record.extension,
242 f"step {name} settings",
243 fragment.file,
244 fragment.text,
245 contributes=True,
246 )
247 )
248 return found
249
250
251def _data(root: Path) -> dict[str, Any]:
252 """What every shipped template reads.
253
254 The runner's name and the project's always; once the contract names
255 the project, also its identity and everything the workspace's state
256 gives the render: the roster, the Python floor, the queries'
257 answers, the extension requirements and the registry.
258 """
259 from livery.workshop._identity import is_born, project_facts
260 from livery.workshop._templates import fragment_data, render_injections
261
262 data: dict[str, Any] = {"prog": footman.prog(), "project_name": root.resolve().name}
263 if is_born(root):
264 answers = project_facts(root)
265 data = fragment_data({**data, **answers, **render_injections(root, answers)})
266 return data
267
268
269def _packaged(
270 root: Path, order: list[str]
271) -> tuple[list[Fragment], dict[str, tuple[str, ...]], dict[str, dict[str, Any]]]:
272 """Each package's per-package files, with the package map and its data.
273
274 A package's own files, its native tools' configuration, come from the
275 first step by name whose fragment names an extension the package
276 holds ([livery.workshop.extension_set][]).
277 """
278 from livery.workshop._composition import extension_set
279 from livery.workshop._fragments import package_files, package_fragment
280 from livery.workshop._packages import discover_packages
281 from livery.workshop._steps import steps_by_name
282
283 packages = discover_packages(root) if (root / "packages").is_dir() else ()
284 fragments: list[Fragment] = []
285 files = package_files()
286 for package in packages:
287 for file in files:
288 found = package_fragment(extension_set(package), file)
289 if found is None:
290 continue
291 text, step = found
292 owner = steps_by_name()[step].extension
293 if owner in order:293 ↛ 287line 293 didn't jump to line 287 because the condition on line 293 was always true
294 fragments.append(
295 Fragment(
296 owner,
297 f"step {step} {package.path}",
298 f"{package.path}/{file}",
299 text,
300 )
301 )
302 from livery.workshop._identity import package_facts
303 from livery.workshop._templates import _release_baseline, package_injections
304
305 # Every package takes the base and every extension the workspace
306 # lists, so each one's `content/package/` files (the changelog
307 # extension's cliff.toml) reach every member, rendered with the
308 # member's own facts.
309 paths: dict[str, tuple[str, ...]] = {
310 package.path: tuple(order) for package in packages
311 }
312 injected = package_injections(root) if packages else {}
313 data: dict[str, dict[str, Any]] = {
314 package.path: {
315 **package_facts(root, package.directory),
316 **injected,
317 "release_baseline": _release_baseline(package.directory),
318 }
319 for package in packages
320 }
321 return fragments, paths, data
322
323
324def outputs(root: Path) -> tuple[Output, ...]:
325 """The shipped files as the listed extensions render them for *root*."""
326 fragments, order = shipped(root)
327 per_package, packages, package_data = _packaged(root, order)
328 planned = plan(
329 root,
330 [*fragments, *per_package],
331 order,
332 _data(root),
333 packages=packages,
334 package_data=package_data,
335 )
336 # Every output beside the composed ones: an output the list leaves
337 # out is one the delivery withdraws.
338 rest = _schema_outputs(root)
339 taken = {output.path: output.owners[0] for output in (*planned, *rest)}
340 return (*planned, *computed_outputs(root, order, taken), *rest)
341
342
343def _schema_outputs(root: Path) -> list[Output]:
344 """Each contract's composed JSON Schema, this checkout's own.
345
346 The schema follows what is installed and listed, so it is written
347 for this checkout alone, as the agent's fragments are, and the
348 committed ``.taplo.toml`` points the editor at it.
349 """
350 from livery.workshop._schema import schema_files
351
352 return [
353 Output(path, body, (f"{SELF}:{path}",), local=True)
354 for path, body in schema_files(root).items()
355 ]
356
357
358def deliver(root: Path, *, local_only: bool = False) -> list[str]:
359 """Write the shipped files into *root*; one line per file that changed.
360
361 A pass that changed anything is followed by one more: a rendered
362 fragment may read a file the same pass wrote (the verbs fragment
363 reads `tasks.py`), and the second pass renders it from what is now
364 on disk, so a sync leaves a tree the next sync finds settled.
365 *local_only* writes only the local outputs git does not track
366 ([livery.workshop._fragment_engine.apply_untracked][]): what a
367 commit holds is judged by the drift check, never rewritten.
368 """
369 from livery.workshop._packages import discover_packages
370
371 if local_only:
372 from livery.workshop._fragment_engine import apply_untracked(empty)
373
374 lines = apply_untracked(root, outputs(root))(empty)
375 if lines:375 ↛ 376line 375 didn't jump to line 376 because the condition on line 375 was never true(empty)
376 lines += apply_untracked(root, outputs(root))
377 return lines(empty)
378
379 homes = (
380 [package.path for package in discover_packages(root)]
381 if (root / "packages").is_dir()
382 else []
383 )
384 lines = apply(root, outputs(root), packages=homes)
385 if lines:
386 lines += apply(root, outputs(root), packages=homes)
387 return lines
388
389
390def deliver_project_file(root: Path) -> list[str]:
391 """Write the workspace's project file alone, as the installed set renders it now.
392
393 The dev group the file renders names the distribution of each
394 extension of the installed set, one no installed distribution
395 declares yet among them, so a ``uv sync`` after this write locks
396 and installs that distribution through the file's
397 ``[tool.uv.sources]`` and indexes. No other file is written or
398 withdrawn: a whole delivery while a listed extension is not
399 installed would withdraw that extension's files. A file edited
400 here is kept and named, as a delivery keeps it, and a workspace
401 whose contract names no project renders no project file.
402
403 Returns:
404 The line for the file when it changed or was kept; empty when
405 it already held the render or none renders.
406 """
407 fragments, order = shipped(root)
408 for output in plan(root, fragments, order, _data(root)):408 ↛ 411line 408 didn't jump to line 411 because the loop on line 408 didn't complete
409 if output.path == PROJECT_FILE:
410 return write_root_file(root, output)
411 return []
412
413
414def shipped_drift(root: Path) -> list[str]:
415 """One line per shipped file whose committed bytes are not its render."""
416 from livery.workshop._packages import discover_packages
417
418 homes = (
419 [package.path for package in discover_packages(root)]
420 if (root / "packages").is_dir()
421 else []
422 )
423 from livery.workshop._fragment_engine import tracked_local
424
425 found = outputs(root)
426 lines = [line.strip() for line in drift(root, found, packages=homes)]
427 return lines + [
428 f"{path}: written for this checkout alone, and git tracks it;"
429 f" `git rm --cached {path}` stops tracking it, and its directory's"
430 " .gitignore keeps it out"
431 for path in tracked_local(root, found)
432 ]
433
434
435def relocate(root: Path) -> list[str]:
436 """Move what a composed JSON file has and its render lacks into its region.
437
438 VS Code writes a setting changed through its UI into `settings.json`
439 just before the closing brace, and a recommendation into the list,
440 both outside the repository's region. A top-level key the render does
441 not produce, or an item a list holds that the render's list does not,
442 is the repository's: it moves into the file's first region, and the
443 file is written as the render with that region. A key the render does
444 produce, set here to another value, is an override of an extension's
445 or a step's setting; it refuses, naming the key and both values,
446 since which one should stand is a person's call.
447
448 Returns:
449 One line per key or item moved.
450
451 Raises:
452 Failed: for a key the render owns that is set to another value.
453 """
454 from livery.workshop._regions import regions_in
455
456 lines: list[str] = []
457 for output in outputs(root):
458 target = root / output.path
459 if not output.path.endswith(".json") or not target.is_file():
460 continue
461 rendered = output.body.decode()
462 regions = regions_in(rendered)
463 theirs = _jsonc(target.read_text(encoding="utf-8"))
464 ours = _jsonc(rendered)
465 if not regions or theirs is None or ours is None:
466 continue
467 added: list[str] = []
468 clashes: list[str] = []
469 for key, value in theirs.items():
470 if key not in ours:
471 body = json.dumps(value, indent=2).replace("\n", "\n ")
472 added.append(f" {json.dumps(key)}: {body},")
473 lines.append(f" {output.path}: moved {key} into the region")
474 elif isinstance(value, list) and isinstance(ours[key], list):
475 for item in cast("list[object]", value):
476 if item not in ours[key]:
477 added.append(f" {json.dumps(item)},")
478 lines.append(f" {output.path}: moved {item} into the region")
479 elif value != ours[key]:
480 clashes.append(
481 f"{key}: the render sets {json.dumps(ours[key])}, the file"
482 f" {json.dumps(value)}"
483 )
484 if clashes:
485 fail(
486 f"{output.path}: a setting the render owns was changed here; keep"
487 " the render's value, or change it where its extension takes"
488 " configuration:\n " + "\n ".join(clashes)
489 )
490 if not added:
491 continue
492 text = rendered.split("\n")
493 text[regions[0].last - 1 : regions[0].last - 1] = added
494 target.write_text("\n".join(text), encoding="utf-8")
495 return lines
496
497
498def _jsonc(text: str) -> dict[str, Any] | None:
499 """*text* read as JSON with whole-line comments and trailing commas, or None."""
500 import re
501
502 kept = "\n".join(
503 line for line in text.split("\n") if not line.lstrip().startswith("//")
504 )
505 kept = re.sub(r",(\s*[}\]])", r"\1", kept)
506 try:
507 loaded = json.loads(kept)
508 except ValueError:
509 return None
510 return cast("dict[str, Any]", loaded) if isinstance(loaded, dict) else None
511
512
513def _package_outputs(member: Path, extensions: tuple[str, ...]) -> tuple[Output, ...]:
514 """The per-package files a package holding *extensions* renders, under *member*."""
515 from livery.workshop._fragments import package_files, package_fragment
516 from livery.workshop._steps import steps_by_name
517
518 fragments: list[Fragment] = []
519 owners: list[str] = []
520 for file in package_files():
521 found = package_fragment(extensions, file)
522 if found is None:
523 continue
524 text, step = found
525 owner = steps_by_name()[step].extension
526 owners.append(owner)
527 fragments.append(Fragment(owner, f"step {step}", file, text))
528 return plan(member, fragments, list(dict.fromkeys(owners)), {})
529
530
531def settle_package(member: Path, extensions: tuple[str, ...]) -> list[str]:
532 """Compose the per-package files of a package holding *extensions*, at *member*.
533
534 What a sync does for one package, without a workspace around it: the
535 conformance kit and a birth's probe settle a package directory this
536 way. *extensions* is the set the package holds, its list completed.
537 """
538 return apply(member, _package_outputs(member, extensions))
539
540
541def judge_package(member: Path, extensions: tuple[str, ...]) -> list[str]:
542 """The drift lines for the per-package files of a package holding *extensions*."""
543 outputs = _package_outputs(member, extensions)
544 return [line.strip() for line in drift(member, outputs)]
545
546
547def computed_outputs(
548 root: Path, order: list[str], taken: dict[str, str] | None = None
549) -> list[Output]:
550 """The files the listed extensions' code writes, in *order*.
551
552 *order* is the delivery's
553 ([livery.workshop._shipped_files.delivery_order][]), so an
554 extension's files are written while the installed set holds it and
555 withdrawn when no list holds it any more.
556 Each ``[fragments."<target>"]`` table names a render the engine
557 calls with *root*, and so does each ``[for.<target>.fragments]``
558 table while its ``[for.<target>]`` table applies. For a file target
559 the render answers the text, or nothing for no file; for a target
560 ending in ``/`` it answers each file's path under the target, to its
561 text or to the shipped file or directory the file links to. Every
562 file is owned ``<extension>:<target>``, and a ``local`` table's files
563 belong to this checkout alone.
564
565 Raises:
566 Failed: for a path two writers claim: another extension's
567 render, or a file *taken* names by its owner.
568 """
569 held = dict(taken or {})
570 outputs: list[Output] = []
571 contributes = contributing(root)
572 for extension in order:
573 found = None if extension == SELF else declaration(extension)
574 if found is None:
575 continue
576 renders = [*found.fragments]
577 for target in contributes.get(extension, ()):
578 renders += found.target_fragments.get(target, ())
579 for fragment in renders:
580 owner = f"{extension}:{fragment.target}"
581 answer = fragment.render(root)
582 written: list[tuple[str, object]]
583 if fragment.target.endswith("/"):
584 files = cast("dict[str, object]", dict(answer or {}))
585 written = [(fragment.target + name, files[name]) for name in files]
586 else:
587 written = [(fragment.target, answer)] if answer else []
588 for path, value in sorted(written, key=itemgetter(0)):
589 if path in held:
590 fail(
591 f"{path} has one writer, and {held[path]} and {owner}"
592 " both write it"
593 )
594 held[path] = owner
595 if isinstance(value, Path):
596 outputs.append(
597 Output(path, b"", (owner,), link=value, local=fragment.local)
598 )
599 else:
600 body = str(value).encode("utf-8")
601 outputs.append(Output(path, body, (owner,), local=fragment.local))
602 return outputs