Coverage for packages/workshop/src/livery/workshop/_materialise.py: 87%

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/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/lfs, packages/extensions/conan, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright, packages/extensions/python, packages/extensions/mkdocstrings, packages/extensions/docs, packages/extensions/coverage, packages/extensions/cmake ran.

1"""Link wheel-shipped content into a checkout, the way the fragment engine does it.
2
3The fragment engine delivers skills and hooks as links into the listed
4extensions' shipped content ([livery.workshop._fragment_engine][]) and
5calls these for the mechanism. Links are the zero-drift way (an
6extension upgrade moves every checkout at once, nothing to re-copy) but
7they are an optimisation, not the contract: where a link cannot be made,
8the same content is copied and refreshed on every sync.
9
10Link mechanism, in order of preference: a relative ``os.symlink`` (a
11relative target survives the repository moving; in the monorepo the
12target sits inside the repository, so containment holds by
13construction); a Windows directory junction, which needs no privilege
14where symlinks do; a copy, whose digest the engine records so the next
15sync tells a stale copy of ours from a local edit.
16
17**Local content always wins.** A real entry whose content differs from
18the shipped one is a deliberate override: it is kept and named, and the
19engine's self-scoped ``.gitignore`` leaves it out, so the override
20commits like any repository file.
21
22**Editing through a link writes into the wheel.** In the monorepo that
23is correct: the target is the source tree. In an instance it edits
24site-packages, machine-wide and lost on the next upgrade; the escape is
25to copy the entry to a real directory of the same name, which then
26takes precedence.
27"""
28
29from __future__ import annotations
30
31import filecmp
32import hashlib
33import os
34import shutil
35import stat
36import sys
37from collections.abc import Callable
38from pathlib import Path
39
40
41def _is_link(path: Path) -> bool:
42 """Whether *path* is a symlink or a Windows reparse point (junction)."""
43 if path.is_symlink():
44 return True
45 try:
46 tag = getattr(path.lstat(), "st_reparse_tag", 0)
47 except OSError:
48 return False
49 return bool(tag)
50
51
52def _points_at(link: Path, target: Path) -> bool:
53 """Whether *link* already resolves to *target* (False when dangling)."""
54 try:
55 return os.path.samestat(link.stat(), target.stat())
56 except OSError:
57 return False
58
59
60def _relative_target(link: Path, target: Path) -> str:
61 """*target* relative to *link*'s directory, or absolute if impossible.
62
63 A relative target is what makes the link survive the repository
64 moving; a cross-volume layout falls back to the absolute path.
65 """
66 try:
67 return os.path.relpath(target, link.parent)
68 except ValueError: # different drives on Windows
69 return str(target)
70
71
72def _make_link(link: Path, target: Path) -> str:
73 """Materialise *link* to *target*: "linked", "junction", or "copied"."""
74 link.parent.mkdir(parents=True, exist_ok=True)
75 try:
76 os.symlink(
77 _relative_target(link, target), link, target_is_directory=target.is_dir()
78 )
79 except (OSError, NotImplementedError):
80 pass
81 else:
82 return "linked"
83 if sys.platform == "win32" and target.is_dir():
84 try:
85 import _winapi
86
87 _winapi.CreateJunction(str(target), str(link))
88 except (ImportError, OSError, AttributeError):
89 pass
90 else:
91 return "junction"
92 if target.is_dir():
93 shutil.copytree(target, link)
94 else:
95 shutil.copy2(target, link)
96 return "copied"
97
98
99def _remove(path: Path) -> None:
100 """Remove a link, a plain file, or a directory we own."""
101 if _is_link(path):
102 try:
103 path.unlink()
104 except OSError:
105 os.rmdir(path) # a junction reads as a directory to some APIs
106 return
107 if not path.is_dir():
108 path.unlink()
109 return
110
111 def _force(func: Callable[[str], object], target: str, _exc: object) -> None:
112 os.chmod(target, stat.S_IWRITE)
113 func(target)
114
115 shutil.rmtree(path, onerror=_force)
116
117
118def _same_content(local: Path, shipped: Path) -> bool:
119 """Whether a real entry matches the shipped copy byte for byte.
120
121 The one question that separates a stale committed copy (safe to
122 replace with a link) from a deliberate local override (keep, and
123 say so).
124 """
125 if not local.is_dir() or not shipped.is_dir():
126 return (
127 local.is_file()
128 and shipped.is_file()
129 and filecmp.cmp(local, shipped, shallow=False)
130 )
131 comparison = filecmp.dircmp(str(local), str(shipped))
132 # common_funny holds names present on both sides with different
133 # types; those appear in neither common_files nor common_dirs, so
134 # omitting the check would call the trees identical and delete the
135 # local one.
136 if (136 ↛ 142line 136 didn't jump to line 142 because the condition on line 136 was never true
137 comparison.left_only
138 or comparison.right_only
139 or comparison.funny_files
140 or comparison.common_funny
141 ):
142 return False
143 mismatch, errors = filecmp.cmpfiles(
144 str(local), str(shipped), comparison.common_files, shallow=False
145 )[1:]
146 if mismatch or errors:
147 return False
148 return all(
149 _same_content(local / sub, shipped / sub) for sub in comparison.common_dirs
150 )
151
152
153def _digest(target: Path) -> str:
154 """A stable digest of a file's bytes or a directory's whole content."""
155 digest = hashlib.sha256()
156 if target.is_file():
157 digest.update(target.read_bytes())
158 return digest.hexdigest()
159 for child in sorted(target.rglob("*")):
160 if child.is_file():160 ↛ 159line 160 didn't jump to line 159 because the condition on line 160 was always true
161 digest.update(str(child.relative_to(target)).encode())
162 digest.update(child.read_bytes())
163 return digest.hexdigest()
164
165
166def _entry(
167 link: Path,
168 target: Path,
169 overrides: list[str],
170 reclaimed: list[str],
171 *,
172 copied_digest: str | None,
173) -> tuple[bool, str]:
174 """Reconcile one materialised entry. Never raises.
175
176 Returns ``(ours, mode)``: whether the entry is ours afterwards (a
177 link or a copy we own) and which mechanism this call used (empty
178 when nothing changed). ``ours=False`` means a local override is in
179 place, which keeps its name out of the managed ``.gitignore`` so
180 the developer can commit it.
181 """
182 if not link.exists() and not _is_link(link):
183 return True, _make_link(link, target)
184 if _is_link(link):
185 if _points_at(link, target):185 ↛ 187line 185 didn't jump to line 187 because the condition on line 185 was always true
186 return True, ""
187 _remove(link) # wrong or dangling target: re-point it
188 return True, _make_link(link, target)
189 if copied_digest is not None:
190 if _same_content(link, target):
191 return True, "" # our copy, current: nothing to do or say
192 if copied_digest and _digest(link) != copied_digest:
193 # Changed since we copied it: a local edit, not staleness.
194 # The override is kept and named, exactly as on a link
195 # platform where a replaced link means the same thing.
196 overrides.append(link.name)
197 return False, ""
198 # Stale (or legacy-owned without a digest): ours to refresh.
199 _remove(link)
200 return True, _make_link(link, target)
201 if link.is_dir() and not any(link.iterdir()):201 ↛ 202line 201 didn't jump to line 202 because the condition on line 201 was never true
202 link.rmdir()
203 return True, _make_link(link, target)
204 if _same_content(link, target):
205 _remove(link) # a committed copy identical to ours: reclaim it
206 reclaimed.append(link.name)
207 return True, _make_link(link, target)
208 overrides.append(link.name)
209 return False, ""