Coverage for packages/workshop/src/livery/workshop/_fragment_engine.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"""Compose, render and deliver the files the extensions keep current.
2
3Every piece of content an extension delivers into a workspace is a
4[livery.workshop._fragment_engine.Fragment][]: an owner, a name, a
5target path and the template its content renders from. `plan` turns the
6listed extensions' fragments into one
7[livery.workshop._fragment_engine.Output][] per file, and `apply`
8writes them and records what it wrote; `drift` compares them with the
9committed files instead.
10
11How the fragments of one target combine depends on the target's type:
12
13- a TOML file joins its fragments' tables in extension order;
14- an ignore or attribute file joins their lines, each line once, and
15 puts the repository's regions after every extension's lines;
16- a JSON file merges their objects key by key;
17- any other file has one owner.
18
19The fragments apply in the order the caller gives: for a sync, the base
20first, then the extensions in composition order, each after the ones it
21requires, and the repository's own fragments last. An extension that
22takes over or removes a fragment that applies before its own declares
23it, with a reason, through `replaces` or `deletes`; a second owner of a
24one-owner file without that declaration refuses, and so does a
25declaration naming a fragment no listed extension ships.
26
27A target is a path at the root, or `package/<path>` for that path in
28every package whose extensions include the owner.
29
30The receipts in `.workshop-rendered`, at the root and in each package,
31record the digest of each file as the engine last wrote it, its
32regions left out, so an edit inside a region does not count as an
33edit of the file. A file
34whose fragments are gone is removed only while it still has those
35bytes; a file edited since is kept and named as the repository's own,
36and so is an edited file the engine would otherwise rewrite. Regions,
37the repository's own lines between marker comments, are read from the
38committed file and written back in place on every render.
39"""
40
41from __future__ import annotations(empty)
42
43import hashlib(empty)
44import json(empty)
45from collections.abc import Callable, Mapping, Sequence(empty)
46from dataclasses import dataclass, field(empty)
47from pathlib import Path, PurePosixPath(empty)
48from typing import Any, Literal, cast(empty)
49
50from livery.footman import fail, prog(empty)
51
52PACKAGE_PREFIX = "package/"(empty)
53"""The target prefix that names a path inside each package of the owner."""(empty)
54
55RENDERED_MANIFEST = ".workshop-rendered"(empty)
56"""The receipt file, name to digest, at the root and in each package."""(empty)
57
58Composition = Literal["tables", "lines", "json", "whole"](empty)
59"""How the fragments of one target combine."""(empty)
60
61
62@dataclass(frozen=True)(empty)
63class Fragment:(empty)
64 """One piece of content an extension delivers.
65
66 Exactly one of *content*, *source* and *dynamic* carries the
67 template, except on a fragment that only `deletes`.
68
69 Attributes:
70 owner: The extension that ships it, by its listed name.
71 name: The fragment's name, unique within its owner.
72 target: The path it renders into, relative to the root, or
73 `package/<path>` for every package of the owner.
74 content: The template source as a string.
75 source: A file in the extension's wheel holding the template.
76 dynamic: A function of the render data returning the template
77 source, for content no static template can express.
78 replaces: `<owner>:<name>` of a lower fragment this one takes
79 the place of.
80 deletes: `<owner>:<name>` of a lower fragment this one removes.
81 reason: Why the replacement or deletion is wanted; required
82 with either.
83 contributes: Whether the fragment is data for its target's one
84 template rather than text: its rendered content is a JSON
85 object, merged by key with every other contribution to the
86 target, and the template reads the result.
87 """
88
89 owner: str(empty)
90 name: str(empty)
91 target: str(empty)
92 content: str = ""(empty)
93 source: Path | None = None(empty)
94 dynamic: Callable[[Mapping[str, Any]], str] | None = field((empty)
95 default=None, compare=False
96 )
97 replaces: str = ""(empty)
98 deletes: str = ""(empty)
99 reason: str = ""(empty)
100 contributes: bool = False(empty)
101
102 @property(empty)
103 def ref(self) -> str:(empty)
104 """The fragment as `replaces` and `deletes` name it: `<owner>:<name>`."""
105 return f"{self.owner}:{self.name}"
106
107 def template(self, data: Mapping[str, Any]) -> str:(empty)
108 """The template source this fragment renders from."""
109 if self.dynamic is not None:
110 return self.dynamic(data)
111 if self.source is not None:
112 return self.source.read_text(encoding="utf-8")
113 return self.content
114
115
116@dataclass(frozen=True)(empty)
117class Output:(empty)
118 """One file as the engine renders it.
119
120 Attributes:
121 path: The file, relative to the workspace root, with `/`.
122 body: The bytes the file should hold.
123 owners: The fragments it was composed from, as `<owner>:<name>`,
124 in the order they applied.
125 link: The shipped file or directory the output links to instead
126 of holding bytes; None for a written file.
127 local: Whether the output belongs to this checkout alone and is
128 never committed: a link into an installed wheel, a copy the
129 agent reads. Its receipt is the checkout's own.
130 """
131
132 path: str(empty)
133 body: bytes(empty)
134 owners: tuple[str, ...](empty)
135 link: Path | None = None(empty)
136 local: bool = False(empty)
137
138
139def composition(target: str) -> Composition:(empty)
140 """How the fragments of *target* combine, by the file's type."""
141 name = PurePosixPath(target).name
142 if name.endswith(".toml"):
143 return "tables"
144 if name in (".gitignore", ".gitattributes") or name.endswith("ignore"):
145 return "lines"
146 if name.endswith(".json"):
147 return "json"
148 return "whole"
149
150
151def _resolve(fragments: Sequence[Fragment], order: Sequence[str]) -> list[Fragment]:(empty)
152 """The fragments left once every `replaces` and `deletes` has applied."""
153 rank = {owner: index for index, owner in enumerate(order)}
154 by_ref: dict[str, Fragment] = {}
155 for fragment in fragments:
156 if fragment.owner not in rank:
157 fail(
158 f"fragment {fragment.ref}: {fragment.owner} is not a listed"
159 f" extension; the order is {', '.join(order)}"
160 )
161 if fragment.ref in by_ref:
162 fail(
163 f"fragment {fragment.ref} is shipped twice; a name is unique per owner"
164 )
165 by_ref[fragment.ref] = fragment
166 gone: set[str] = set()
167 for fragment in fragments:
168 for verb, ref in (
169 ("replaces", fragment.replaces),
170 ("deletes", fragment.deletes),
171 ):
172 if not ref:
173 continue
174 if not fragment.reason:
175 fail(f"fragment {fragment.ref} {verb} {ref} without a reason; give one")
176 lower = by_ref.get(ref)
177 if lower is None:
178 fail(
179 f"fragment {fragment.ref} {verb} {ref}, which no listed"
180 " extension ships"
181 )
182 if rank[lower.owner] >= rank[fragment.owner]:
183 fail(
184 f"fragment {fragment.ref} {verb} {ref}, which applies after"
185 f" it; a fragment {verb} one that applies before it"
186 )
187 gone.add(ref)
188 return [
189 fragment
190 for fragment in fragments
191 if fragment.ref not in gone and not fragment.deletes
192 ]
193
194
195def _targets(fragment: Fragment, packages: Mapping[str, Sequence[str]]) -> list[str]:(empty)
196 """The root-relative paths *fragment* renders into."""
197 if not fragment.target.startswith(PACKAGE_PREFIX):
198 return [fragment.target]
199 inner = fragment.target.removeprefix(PACKAGE_PREFIX)
200 return [
201 f"{package}/{inner}"
202 for package, extensions in sorted(packages.items())
203 if fragment.owner in extensions
204 ]
205
206
207def _package_of(path: str, packages: Mapping[str, Sequence[str]]) -> str:(empty)
208 """The package *path* lies in, or empty for the root."""
209 for package in packages:
210 if path.startswith(f"{package}/"):
211 return package
212 return ""
213
214
215def _digest(body: bytes) -> str:(empty)
216 return hashlib.sha256(body).hexdigest()
217
218
219_ENVIRONMENT: Any = None(empty)
220_COMPILED: set[str] = set()(empty)
221_CACHE: dict[tuple[str, str], str] = {}(empty)
222
223
224#: What a template error's kind means, in a refusal's words. A kind not
225#: named here is printed by its own name.
226_TEMPLATE_ERRORS = {(empty)
227 "SyntaxError": "the template does not parse",
228 "UndefinedError": "the template uses a value its data does not have",
229 "UnknownFilter": "the template uses a filter that does not exist",
230 "UnknownTest": "the template uses a test that does not exist",
231 "UnknownFunction": "the template calls a function that does not exist",
232 "UnknownMethod": "the template calls a method that does not exist",
233 "InvalidOperation": "the template does an operation its values do not allow",
234}
235
236
237def _template_error(fragment: Fragment, error: Any) -> str:(empty)
238 """The refusal for a template that does not compile or render.
239
240 Built from the error's ``kind`` and ``line``, the fields minijinja
241 keeps stable; its message text changes between releases. Its
242 ``detail``, where it gives one, follows in parentheses.
243 """
244 # The template is registered under its digest, which says nothing
245 # to a reader; the fragment's name and the line do.
246 kind = str(error.kind)
247 said = _TEMPLATE_ERRORS.get(kind, kind)
248 detail = f" ({error.detail})" if error.detail else ""
249 return f"fragment {fragment.ref}, line {error.line}: {said}{detail}"
250
251
252def _render(fragment: Fragment, data: Mapping[str, Any]) -> str:(empty)
253 """*fragment*'s text under *data*, rendered once per content and data."""
254 global _ENVIRONMENT
255 source = fragment.template(data)
256 plain = json.dumps(data, sort_keys=True, default=str)
257 key = (_digest(source.encode()), _digest(plain.encode()))
258 if key in _CACHE:
259 return _CACHE[key]
260 import minijinja
261
262 if _ENVIRONMENT is None:
263 _ENVIRONMENT = minijinja.Environment(
264 keep_trailing_newline=True, undefined_behavior="strict"
265 )
266 if key[0] not in _COMPILED:
267 try:
268 _ENVIRONMENT.add_template(key[0], source)
269 except minijinja.TemplateError as error:
270 fail(_template_error(fragment, error))
271 _COMPILED.add(key[0])
272 try:
273 text = cast("str", _ENVIRONMENT.render_template(key[0], **json.loads(plain)))
274 except minijinja.TemplateError as error:
275 fail(_template_error(fragment, error))
276 _CACHE[key] = text
277 return text
278
279
280def _merge((empty)
281 into: dict[str, Any], part: Mapping[str, Any], owners: dict[str, str], ref: str
282) -> None:
283 """Merge *part* into *into* by key; two owners of one value refuse."""
284
285 def walk(target: dict[str, Any], incoming: Mapping[str, Any], prefix: str) -> None:
286 for key, value in incoming.items():
287 where = f"{prefix}{key}"
288 if key not in target:
289 target[key] = value
290 owners[where] = ref
291 elif isinstance(target[key], dict) and isinstance(value, Mapping):
292 walk(
293 cast("dict[str, Any]", target[key]),
294 cast("Mapping[str, Any]", value),
295 f"{where}.",
296 )
297 elif isinstance(target[key], list) and isinstance(value, list):
298 merged = cast("list[Any]", target[key])
299 merged.extend(item for item in value if item not in merged)
300 elif target[key] != value:
301 # A value arrives inside the object that first carried
302 # it, so its owner is the nearest owned ancestor's.
303 path = where.split(".")
304 first = next(
305 owners[".".join(path[:end])]
306 for end in range(len(path), 0, -1)
307 if ".".join(path[:end]) in owners
308 )
309 fail(
310 f"{where} is set by both {first} and {ref}; declare"
311 " `replaces` with a reason on the later one"
312 )
313
314 walk(into, part, "")
315
316
317def _regions_apart(text: str) -> tuple[list[str], list[str]]:(empty)
318 """*text*'s lines outside its regions, and its regions' lines.
319
320 A region is the repository's, and it comes after every extension's
321 content, whichever fragment carries the markers. The comment lines
322 directly above a region's opening marker travel with it, since they
323 explain it.
324 """
325 from livery.workshop._regions import regions_in
326
327 lines = text.splitlines()
328 moving: set[int] = set()
329 for region in regions_in(text):
330 first = region.first
331 while first > 1 and lines[first - 2].lstrip().startswith(("#", "//")):
332 first -= 1
333 moving.update(range(first, region.last + 1))
334 outside = [line for n, line in enumerate(lines, start=1) if n not in moving]
335 inside = [line for n, line in enumerate(lines, start=1) if n in moving]
336 return outside, inside
337
338
339def _compose(path: str, parts: list[tuple[Fragment, str]]) -> str:(empty)
340 """The text of *path* from its rendered *parts*, in the order they apply."""
341 kind = composition(path)
342 if kind == "whole":
343 if len(parts) > 1:
344 names = " and ".join(fragment.ref for fragment, _text in parts)
345 fail(
346 f"{path} has one owner, and {names} both render it; declare"
347 " `replaces` or `deletes` with a reason on the later one"
348 )
349 return parts[0][1]
350 if kind == "tables":
351 import tomllib
352
353 kept: list[str] = []
354 tail: list[str] = []
355 for _fragment, text in parts:
356 outside, inside = _regions_apart(text)
357 kept.append("\n".join(outside).strip("\n") + "\n")
358 tail.extend(inside)
359 text = "\n".join(kept)
360 if tail:
361 text += "\n" + "\n".join(tail) + "\n"
362 try:
363 tomllib.loads(text)
364 except tomllib.TOMLDecodeError as error:
365 names = ", ".join(fragment.ref for fragment, _text in parts)
366 fail(f"{path}: the tables of {names} do not compose: {error}")
367 return text
368 if kind == "lines":
369 seen: set[str] = set()
370 lines: list[str] = []
371 regions: list[str] = []
372 for _fragment, text in parts:
373 outside, inside = _regions_apart(text)
374 regions.extend(inside)
375 for line in outside:
376 keyed = line.strip()
377 if keyed and not keyed.startswith("#"):
378 if keyed in seen:
379 continue
380 seen.add(keyed)
381 lines.append(line)
382 return "\n".join([*lines, *regions]) + "\n"
383 merged: dict[str, Any] = {}
384 owners: dict[str, str] = {}
385 for fragment, text in parts:
386 try:
387 part = json.loads(text)
388 except ValueError as error:
389 fail(f"{path}: fragment {fragment.ref} is not JSON: {error}")
390 if not isinstance(part, dict):390 ↛ 391line 390 didn't jump to line 391 because the condition on line 390 was never true
391 fail(f"{path}: fragment {fragment.ref} is not a JSON object")
392 _merge(merged, cast("dict[str, Any]", part), owners, fragment.ref)
393 return json.dumps(merged, indent=2) + "\n"
394
395
396def _collects(fragment: Fragment, data: Mapping[str, Any]) -> bool:(empty)
397 """Whether *fragment* is the template its target's contributions render into.
398
399 It reads ``contributed`` or ``contributed_entries``. With nothing
400 contributed it still renders, from an empty merge: composed as a
401 plain part instead, its comments would read as broken JSON. A
402 dynamic fragment is never asked, so it renders once.
403 """
404 return fragment.dynamic is None and "contributed" in fragment.template(data)
405
406
407def _entries(merged: Mapping[str, Any]) -> str:(empty)
408 """*merged* as the members of a JSON object, two spaces in, each with its comma."""
409 lines: list[str] = []
410 for key, value in merged.items():
411 body = json.dumps(value, indent=2).replace("\n", "\n ")
412 lines.append(f" {json.dumps(key)}: {body},\n")
413 return "".join(lines)
414
415
416def _contributed((empty)
417 path: str, contributions: list[Fragment], data: Mapping[str, Any]
418) -> dict[str, Any]:
419 """The contributions to *path* merged by key, in the order they apply."""
420 merged: dict[str, Any] = {}
421 owners: dict[str, str] = {}
422 for fragment in contributions:
423 text = _render(fragment, data)
424 try:
425 part = json.loads(text)
426 except ValueError as error:
427 fail(f"{path}: contribution {fragment.ref} is not JSON: {error}")
428 if not isinstance(part, dict):428 ↛ 429line 428 didn't jump to line 429 because the condition on line 428 was never true
429 fail(f"{path}: contribution {fragment.ref} is not a JSON object")
430 _merge(merged, cast("dict[str, Any]", part), owners, fragment.ref)
431 return merged
432
433
434def _splice(rendered: str, committed: str) -> str:(empty)
435 """*rendered* with each region's content taken from *committed*."""
436 from livery.workshop._regions import regions_in
437
438 kept = {region.name: region.content for region in regions_in(committed)}
439 lines = rendered.split("\n")
440 out: list[str] = []
441 cursor = 0
442 for region in regions_in(rendered):
443 out.extend(lines[cursor : region.first])
444 body = kept.get(region.name, region.content)
445 out.extend(body.split("\n")[:-1] if body else [])
446 cursor = region.last - 1
447 out.extend(lines[cursor:])
448 return "\n".join(out)
449
450
451def plan((empty)
452 root: Path,
453 fragments: Sequence[Fragment],
454 order: Sequence[str],
455 data: Mapping[str, Any],
456 *,
457 packages: Mapping[str, Sequence[str]] | None = None,
458 package_data: Mapping[str, Mapping[str, Any]] | None = None,
459) -> tuple[Output, ...]:
460 """Every file the listed fragments render, composed and with its regions kept.
461
462 Args:
463 root: The workspace root, where the committed files are read
464 for their regions.
465 fragments: What the listed extensions ship.
466 order: The owners in the order they apply, the base first and
467 the repository last.
468 data: The render data every template sees. A package target
469 also sees `package`, the package's path.
470 packages: Each package's path, relative to the root, to the
471 extensions it lists.
472 package_data: Render data for one package's files, by its
473 path: what differs per package, such as its name and its
474 release baseline.
475
476 Returns:
477 One output per file, sorted by path.
478
479 Raises:
480 Failed: for a second owner of a one-owner file, a `replaces`
481 or `deletes` without a reason or naming a fragment no
482 listed extension ships, a template that does not render,
483 and parts that do not compose.
484 """
485 packaged = dict(packages or {})
486 rank = {owner: index for index, owner in enumerate(order)}
487 grouped: dict[str, list[Fragment]] = {}
488 for fragment in _resolve(fragments, order):
489 for path in _targets(fragment, packaged):
490 grouped.setdefault(path, []).append(fragment)
491 outputs: list[Output] = []
492 for path, members in sorted(grouped.items()):
493 members.sort(key=lambda fragment: rank[fragment.owner])
494 package = _package_of(path, packaged)
495 seen = (
496 {**data, **(package_data or {}).get(package, {}), "package": package}
497 if package
498 else dict(data)
499 )
500 contributions = [fragment for fragment in members if fragment.contributes]
501 templates = [fragment for fragment in members if not fragment.contributes]
502 if contributions or (len(templates) == 1 and _collects(templates[0], seen)):
503 if len(templates) != 1:503 ↛ 504line 503 didn't jump to line 504 because the condition on line 503 was never true
504 fail(
505 f"{path}: contributions need one template to render them;"
506 f" it has {len(templates)}"
507 )
508 merged = _contributed(path, contributions, seen)
509 seen = {
510 **seen,
511 "contributed": merged,
512 "contributed_entries": _entries(merged),
513 }
514 text = _render(templates[0], seen)
515 else:
516 seen = {**seen, "contributed": {}, "contributed_entries": ""}
517 parts = [(fragment, _render(fragment, seen)) for fragment in members]
518 text = _compose(path, parts)
519 committed = root / path
520 if committed.is_file():
521 text = _splice(text, committed.read_text(encoding="utf-8"))
522 outputs.append(
523 Output(path, text.encode(), tuple(fragment.ref for fragment in members))
524 )
525 return tuple(outputs)
526
527
528def _owned(body: bytes) -> str:(empty)
529 """The digest of what the engine owns in *body*: everything but its regions.
530
531 A region's lines are the repository's, so an edit inside one is not
532 an edit of the engine's file, and a receipt never records them.
533 """
534 from livery.workshop._regions import regions_in
535
536 text = body.decode("utf-8", errors="replace")
537 regions = regions_in(text)
538 if not regions:
539 return _digest(body)
540 lines = text.split("\n")
541 inside = {n for r in regions for n in range(r.first + 1, r.last)}
542 kept = [line for number, line in enumerate(lines, start=1) if number not in inside]
543 return _digest("\n".join(kept).encode())
544
545
546def _committed(path: Path) -> bytes:(empty)
547 """*path*'s bytes with LF line endings, as the engine writes and compares them.
548
549 A Windows checkout may hold CRLF where the repository has LF; the
550 file is the same file, so neither an edit nor drift.
551 """
552 return path.read_bytes().replace(b"\r\n", b"\n")
553
554
555def read_rendered(directory: Path) -> dict[str, str]:(empty)
556 """The receipts in *directory*, name to digest; empty without any."""
557 path = directory / RENDERED_MANIFEST
558 return receipts_from(path.read_text("utf-8")) if path.is_file() else {}
559
560
561def receipts_from(text: str) -> dict[str, str]:(empty)
562 """The receipts *text* spells, name to digest; empty for anything else."""
563 try:
564 loaded = json.loads(text)
565 except ValueError:
566 return {}
567 if not isinstance(loaded, dict):567 ↛ 568line 567 didn't jump to line 568 because the condition on line 567 was never true
568 return {}
569 return {str(k): str(v) for k, v in cast("dict[object, object]", loaded).items()}
570
571
572def receipt_of(path: Path) -> str | None:(empty)
573 """The receipt *path* earns as it stands, its regions left out; None if absent."""
574 return _owned(_committed(path)) if path.is_file() else None
575
576
577def merge_receipts((empty)
578 base: Mapping[str, str],
579 ours: Mapping[str, str],
580 theirs: Mapping[str, str],
581 *,
582 beside: Path,
583) -> dict[str, str]:
584 """Two sides' receipts merged key by key, over the *base* they share.
585
586 A receipt one side changed takes that side's digest, a removal
587 included, and one both changed alike takes it too. One both
588 changed differently takes the digest of its file as the merge left
589 it in *beside*, the directory the receipts describe, and goes when
590 the file did: a digest that does not match its file reads as the
591 repository's edit, and the next render would keep that file instead
592 of rewriting it.
593 """
594 merged: dict[str, str] = {}
595 for name in sorted({*base, *ours, *theirs}):
596 was, mine, yours = base.get(name), ours.get(name), theirs.get(name)
597 if mine == yours or yours == was:
598 chosen = mine
599 elif mine == was:
600 chosen = yours
601 else:
602 chosen = receipt_of(beside / name)
603 if chosen is not None:
604 merged[name] = chosen
605 return merged
606
607
608def write_rendered(directory: Path, receipts: Mapping[str, str]) -> None:(empty)
609 """Write the receipts, or remove the file when there are none."""
610 path = directory / RENDERED_MANIFEST
611 if not receipts:
612 if path.is_file():
613 path.unlink()
614 return
615 path.write_bytes(
616 (json.dumps(dict(sorted(receipts.items())), indent=2) + "\n").encode()
617 )
618
619
620def _write(root: Path, output: Output, recorded: str | None) -> tuple[bool, str]:(empty)
621 """Write *output* when its receipt allows; whether the file holds it, and the line.
622
623 A missing file is written, and a file whose bytes are still what the
624 engine last wrote, *recorded*, is rewritten. A file edited since is
625 kept, and so is one with no receipt whose bytes differ: the file
626 then does not hold the output, and the line names it. The line is
627 empty when the file already holds the output.
628 """
629 target = root / output.path
630 if not target.is_file():
631 target.parent.mkdir(parents=True, exist_ok=True)
632 target.write_bytes(output.body)
633 return True, f" wrote {output.path}"
634 existing = _committed(target)
635 if existing == output.body:
636 return True, ""
637 if recorded is not None and _owned(existing) == recorded:
638 target.write_bytes(output.body)
639 return True, f" updated {output.path}"
640 return False, (
641 f" kept {output.path}: edited here, so it is not rewritten;"
642 " delete it to take the rendered file"
643 )
644
645
646def write_root_file(root: Path, output: Output) -> list[str]:(empty)
647 """Write one file at the root as `apply` writes it, and its receipt; the lines.
648
649 *output* is a file a commit holds, at the root, never in a package.
650 Every other file and receipt stays as it is: unlike `apply`, this
651 withdraws nothing, so it writes one file while the rest of the
652 delivery waits. A file edited here is kept and named, as `apply`
653 keeps it.
654 """
655 receipts = read_rendered(root)
656 held, line = _write(root, output, receipts.get(output.path))
657 if held:
658 receipts[output.path] = _owned(output.body)
659 write_rendered(root, receipts)
660 return [line] if line else []
661
662
663def apply((empty)
664 root: Path,
665 outputs: Sequence[Output],
666 *,
667 packages: Sequence[str] = (),
668) -> list[str]:
669 """Write *outputs*, withdraw what is gone, and say what changed.
670
671 A file is written when it is missing, and rewritten when its bytes
672 are still what the engine last wrote. A file edited since is kept
673 and named, and so is a file the engine has no receipt for whose
674 bytes differ. A receipted file no output renders any more is
675 removed when unedited and kept and named otherwise; either way its
676 receipt goes, so a kept file is the repository's from then on.
677
678 Args:
679 root: The workspace root.
680 outputs: What `plan` rendered.
681 packages: The package paths whose receipts the engine keeps,
682 relative to the root.
683
684 Returns:
685 One line per file written, removed or kept, in path order.
686 """
687 lines = _apply_local(root, [output for output in outputs if output.local])
688 outputs = [output for output in outputs if not output.local]
689 homes = ["", *sorted(packages, key=len, reverse=True)]
690
691 def home_of(path: str) -> str:
692 for home in homes[1:]:
693 if path.startswith(f"{home}/"):
694 return home
695 return ""
696
697 receipts = {home: read_rendered(root / home) for home in homes}
698 rendered: set[str] = set()
699 for output in outputs:
700 rendered.add(output.path)
701 home = home_of(output.path)
702 name = output.path.removeprefix(f"{home}/") if home else output.path
703 held, line = _write(root, output, receipts[home].get(name))
704 if line:
705 lines.append(line)
706 if held:
707 receipts[home][name] = _owned(output.body)
708 for home in homes:
709 for name, recorded in sorted(receipts[home].items()):
710 path = f"{home}/{name}" if home else name
711 if path in rendered:
712 continue
713 del receipts[home][name]
714 target = root / path
715 if not target.is_file():715 ↛ 716line 715 didn't jump to line 716 because the condition on line 715 was never true
716 continue
717 if _owned(_committed(target)) == recorded:
718 target.unlink()
719 lines.append(f" removed {path}: no listed extension renders it")
720 else:
721 lines.append(
722 f" kept {path}: no listed extension renders it, and it was"
723 " edited here, so it stays as the repository's own"
724 )
725 write_rendered(root / home, receipts[home])
726 return sorted(lines, key=lambda line: line.split()[1])
727
728
729LOCAL_RECEIPT = ".workshop/rendered/receipts.json"(empty)
730"""The checkout's own receipts: what the engine linked or copied for it alone.(empty)
731
732Written by every delivery, empty when there is nothing of its own, so
733its presence says the checkout's own files were delivered at all; a
734checkout without it never had them, which the per-command repair reads
735([livery.workshop._reconcile.current][]).
736"""
737
738_IGNORE_HEADER = ((empty)
739 "# Managed by `{prog} sync`: the entries below are linked or copied from\n"
740 "# the listed extensions. The list is self-scoped: an entry you add\n"
741 "# yourself is not ignored and commits normally.\n"
742)
743
744
745def local_receipts(root: Path) -> dict[str, str]:(empty)
746 """What the engine linked or copied for this checkout alone, path to receipt."""
747 return _read_local(root)
748
749
750def _read_local(root: Path) -> dict[str, str]:(empty)
751 path = root / LOCAL_RECEIPT
752 if not path.is_file():
753 return {}
754 try:
755 loaded = json.loads(path.read_text("utf-8"))
756 except ValueError:
757 return {}
758 if not isinstance(loaded, dict):758 ↛ 759line 758 didn't jump to line 759 because the condition on line 758 was never true
759 return {}
760 return {str(k): str(v) for k, v in cast("dict[object, object]", loaded).items()}
761
762
763def _write_local(root: Path, receipts: Mapping[str, str]) -> None:(empty)
764 path = root / LOCAL_RECEIPT
765 path.parent.mkdir(parents=True, exist_ok=True)
766 path.write_bytes(
767 (json.dumps(dict(sorted(receipts.items())), indent=2) + "\n").encode()
768 )
769
770
771def apply_untracked(root: Path, outputs: Sequence[Output]) -> list[str]:(empty)
772 """Write the local *outputs* git does not track, and nothing else.
773
774 The write `fm sync --locked` makes: a checkout's own files (the
775 agent's fragments, skills and settings) are made current, and no
776 file a commit holds is written, removed or receipted. A local
777 output git tracks is left as it is; the drift check names it.
778 """
779 # Even with nothing of its own, the delivery runs: it withdraws what
780 # an earlier one wrote and leaves the receipt that says it ran.
781 local = [output for output in outputs if output.local]
782 tracked = set(tracked_local(root, local))
783 return _apply_local(
784 root, [output for output in local if output.path not in tracked]
785 )
786
787
788def tracked_local(root: Path, outputs: Sequence[Output]) -> list[str]:(empty)
789 """The local outputs among *outputs* that git tracks, in path order.
790
791 A local output is the checkout's own, written for it alone and
792 ignored through its directory's managed `.gitignore`; a tracked one
793 was committed before that, and stays tracked whatever the ignore
794 file says. Empty when git cannot answer.
795 """
796 from livery import git
797
798 local = [output.path for output in outputs if output.local]
799 if not local:
800 return []
801 try:
802 return sorted(set(git.ls_files(root, *local)) & set(local))
803 except git.GitError:
804 return []
805
806
807def _apply_local(root: Path, outputs: Sequence[Output]) -> list[str]:(empty)
808 """Link or write the checkout's own outputs, and withdraw what is gone.
809
810 A link goes through the materialiser's mechanism: a relative symlink,
811 a junction or a copy where links are refused, an identical copy
812 reclaimed, an edited one kept as an override. Its receipt says `link`,
813 or the copy's digest. A written local file follows the committed
814 rule. A receipted entry nothing renders any more is removed while it
815 is a link or an unedited copy, and kept and named otherwise. Each
816 directory holding local entries outside `.workshop/` gets a
817 self-scoped `.gitignore` naming them, so an override commits.
818 """
819 from livery.workshop import _materialise
820
821 receipts = _read_local(root)
822 lines: list[str] = []
823 ours: dict[Path, list[str]] = {}
824 seen: set[str] = set()
825 for output in outputs:
826 seen.add(output.path)
827 target = root / output.path
828 recorded = receipts.get(output.path)
829 if output.link is not None:
830 target.parent.mkdir(parents=True, exist_ok=True)
831 overrides: list[str] = []
832 reclaimed: list[str] = []
833 copied = recorded if recorded not in (None, "link") else None
834 mine, mode = _materialise._entry(
835 target, output.link, overrides, reclaimed, copied_digest=copied
836 )
837 if not mine:
838 lines.append(
839 f" kept {output.path}: edited here, so it is not replaced;"
840 " delete it to take the shipped one"
841 )
842 receipts.pop(output.path, None)
843 ours.setdefault(target.parent, [])
844 continue
845 if reclaimed:
846 lines.append(f" reclaimed {output.path}: a committed copy of it")
847 elif mode:
848 lines.append(f" {mode} {output.path}")
849 receipts[output.path] = (
850 "link"
851 if _materialise._is_link(target)
852 else _materialise._digest(target)
853 )
854 else:
855 if _materialise._is_link(target):
856 # A link would take an editor's write into the wheel, so a
857 # written local file is always a copy.
858 _materialise._remove(target)
859 target.write_bytes(output.body)
860 lines.append(f" wrote {output.path} in place of a link")
861 elif not target.is_file():
862 target.parent.mkdir(parents=True, exist_ok=True)
863 target.write_bytes(output.body)
864 lines.append(f" wrote {output.path}")
865 elif (existing := _committed(target)) == output.body:
866 pass
867 elif recorded is not None and _owned(existing) == recorded:
868 target.write_bytes(output.body)
869 lines.append(f" updated {output.path}")
870 else:
871 lines.append(
872 f" kept {output.path}: edited here, so it is not rewritten;"
873 " delete it to take the rendered file"
874 )
875 receipts.pop(output.path, None)
876 ours.setdefault(target.parent, [])
877 continue
878 receipts[output.path] = _owned(output.body)
879 ours.setdefault(target.parent, []).append(target.name)
880 for path, recorded in sorted(receipts.items()):
881 if path in seen:
882 continue
883 del receipts[path]
884 target = root / path
885 if _materialise._is_link(target):
886 _materialise._remove(target)
887 lines.append(f" removed {path}: no listed extension ships it")
888 elif target.exists():888 ↛ 899line 888 didn't jump to line 899 because the condition on line 888 was always true
889 if _materialise._digest(target) == recorded or (889 ↛ 895line 889 didn't jump to line 895 because the condition on line 889 was always true
890 target.is_file() and _owned(_committed(target)) == recorded
891 ):
892 _materialise._remove(target)
893 lines.append(f" removed {path}: no listed extension ships it")
894 else:
895 lines.append(
896 f" kept {path}: no listed extension ships it, and it was"
897 " edited here, so it stays as the repository's own"
898 )
899 ours.setdefault(target.parent, [])
900 workshop = root / ".workshop"
901 for directory, names in ours.items():
902 if directory == workshop or workshop in directory.parents:
903 continue
904 ignore = directory / ".gitignore"
905 if not names:
906 if ignore.is_file() and ignore.read_text(encoding="utf-8").startswith(
907 _IGNORE_HEADER.format(prog=prog())
908 ):
909 ignore.unlink()
910 continue
911 body = _IGNORE_HEADER.format(prog=prog()) + "".join(
912 f"/{name}\n" for name in sorted(names)
913 )
914 body += "/.gitignore\n"
915 if not ignore.is_file() or ignore.read_text(encoding="utf-8") != body:
916 ignore.write_text(body, encoding="utf-8", newline="\n")
917 _write_local(root, receipts)
918 return lines
919
920
921def drift((empty)
922 root: Path, outputs: Sequence[Output], *, packages: Sequence[str] = ()
923) -> list[str]:
924 """One line per file whose committed bytes are not what it renders.
925
926 A receipted file no output renders any more is drift too while it is
927 unedited, since the next apply removes it; an edited one is the
928 repository's and says nothing.
929 """
930 lines: list[str] = []
931 # What a checkout holds for itself alone is never committed, so the
932 # gate does not judge it.
933 outputs = [output for output in outputs if not output.local]
934 rendered = {output.path for output in outputs}
935 for home in ["", *packages]:
936 for name, recorded in sorted(read_rendered(root / home).items()):
937 path = f"{home}/{name}" if home else name
938 target = root / path
939 if path in rendered or not target.is_file():939 ↛ 941line 939 didn't jump to line 941 because the condition on line 939 was always true
940 continue
941 if _owned(_committed(target)) == recorded:
942 lines.append(
943 f" {path}: written for an owner no longer listed;"
944 f" `{prog()} sync` removes it"
945 )
946 for output in outputs:
947 target = root / output.path
948 if not target.is_file():
949 lines.append(f" {output.path}: missing; `{prog()} sync` writes it")
950 elif _committed(target) != output.body:
951 owners = ", ".join(output.owners)
952 lines.append(f" {output.path}: differs from what {owners} render")
953 return lines