Coverage for packages/workshop/src/livery/workshop/_influence.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"""Which files a workspace step reads, and which of them a change touched.
2
3A workspace step declares its inputs on its record
4([livery.workshop._steps.StepRecord][] ``inputs``): the files it
5judges, whether it judges each changed one on its own or runs whole
6when any changed, and what widens it to every file it reads. The gate
7hands every step the paths changed since the tree it measures from,
8and [livery.workshop._influence.select][] answers for one step: skip
9it, judge these files, or judge everything.
10
11Two widenings hold for every step. A run that knows nothing of what
12changed (the whole gate) judges everything. A step whose own code
13changed judges everything, since its rule moved, not the files: the
14member package that ships it changed under its sources, or, for a
15step installed from an index, the lock moved.
16"""
17
18from __future__ import annotations(empty)
19
20import importlib.util(empty)
21from collections.abc import Callable(empty)
22from dataclasses import dataclass(empty)
23from pathlib import Path(empty)
24
25from livery import git(empty)
26from livery.workshop._categories import matches(empty)
27from livery.workshop._packages import Package(empty)
28
29#: The lock an installed step's version moves with.
30LOCK = "uv.lock"(empty)
31
32#: Patterns, root-relative and posix (``**`` spans directories), or a
33#: function of the root answering them.
34Patterns = tuple[str, ...] | Callable[[Path], tuple[str, ...]](empty)
35
36
37@dataclass(frozen=True)(empty)
38class Changes:(empty)
39 """What changed since the tree a gate measures from.
40
41 Attributes:
42 root: The workspace root.
43 paths: The changed paths, root-relative posix, deleted ones
44 included.
45 before: The commit or tree the paths were taken from; empty
46 when the caller named the paths itself.
47 """
48
49 root: Path(empty)
50 paths: tuple[str, ...](empty)
51 before: str = ""(empty)
52
53 def removed(self) -> tuple[str, ...]:(empty)
54 """The changed paths the working tree no longer holds: deleted or moved."""
55 return tuple(path for path in self.paths if not (self.root / path).exists())
56
57 def text_before(self, path: str) -> str:(empty)
58 """*path* where the change is measured from; empty if unknown."""
59 if not self.before:
60 return ""
61
62 return git.file_at(self.root, self.before, path)
63
64
65@dataclass(frozen=True)(empty)
66class Inputs:(empty)
67 """The files a workspace step reads, as the affected engine asks.
68
69 Attributes:
70 reads: The files the step judges.
71 per_file: Whether the step judges each changed file it reads
72 on its own; otherwise a change to any of them runs it
73 whole.
74 widens: Files the step does not judge whose change runs it
75 over everything it reads: the contracts, for a step of
76 what is composed from them.
77 on_removal: Whether a deleted or moved file anywhere runs it
78 whole: a link checker's, since a link in an unchanged page
79 may point at what went away.
80 widen: The step's own further reason to run whole, given the
81 changes: a link checker's removed heading.
82 ignores: Files that never count, though a pattern above names
83 them: a package's readme beside its manifests.
84 """
85
86 reads: Patterns(empty)
87 per_file: bool = True(empty)
88 widens: Patterns = ()(empty)
89 on_removal: bool = False(empty)
90 widen: Callable[[Changes], bool] | None = None(empty)
91 ignores: tuple[str, ...] = ()(empty)
92
93
94@dataclass(frozen=True)(empty)
95class Selection:(empty)
96 """What one step judges in a run.
97
98 Attributes:
99 whole: Whether it judges everything it reads.
100 files: Otherwise, the changed files it judges; with *whole*
101 false and no files, the step does not run.
102 """
103
104 whole: bool(empty)
105 files: tuple[str, ...] = ()(empty)
106
107 @property(empty)
108 def runs(self) -> bool:(empty)
109 """Whether the step runs at all."""
110 return self.whole or bool(self.files)
111
112
113WHOLE = Selection(whole=True)(empty)
114SKIP = Selection(whole=False)(empty)
115
116
117def _patterns(declared: Patterns, root: Path) -> tuple[str, ...]:(empty)
118 return declared if isinstance(declared, tuple) else declared(root)
119
120
121def _matched(patterns: tuple[str, ...], paths: tuple[str, ...]) -> tuple[str, ...]:(empty)
122 return tuple(
123 path for path in paths if any(matches(pattern, path) for pattern in patterns)
124 )
125
126
127def reads(inputs: Inputs, root: Path, path: str) -> bool:(empty)
128 """Whether *inputs* read *path*: a pattern of its reads names it, and no ignore."""
129 if _matched(inputs.ignores, (path,)):129 ↛ 130line 129 didn't jump to line 130 because the condition on line 129 was never true
130 return False
131 return bool(_matched(_patterns(inputs.reads, root), (path,)))
132
133
134def provider_of(extension: str, packages: tuple[Package, ...]) -> str:(empty)
135 """The member package whose sources ship *extension*, by its path; empty if none.
136
137 An extension installed from an index has no member: its code moves
138 with the lock instead.
139 """
140 try:
141 spec = importlib.util.find_spec(extension)
142 except (ImportError, ValueError):
143 return ""
144 if spec is None:
145 return ""
146 places = [*(spec.submodule_search_locations or ())]
147 if spec.origin:
148 places.append(str(Path(spec.origin).parent))
149 for place in places:
150 resolved = Path(place).resolve()
151 for package in packages:
152 if resolved.is_relative_to(package.directory.resolve()):
153 return package.path
154 return ""
155
156
157def select(inputs: Inputs, changes: Changes | None, *, provider: str = "") -> Selection:(empty)
158 """What a step with *inputs* judges for *changes*.
159
160 Everything when nothing is known of what changed, when the step's
161 own code changed (*provider*, the member that ships it, changed
162 under ``src/``; for a step with no member, the lock moved), or
163 when a widening input changed; else the changed files it reads,
164 each on its own, or everything when it does not judge per file;
165 nothing when no file it reads changed.
166 """
167 if changes is None:
168 return WHOLE
169 paths = tuple(
170 path for path in changes.paths if not _matched(inputs.ignores, (path,))
171 )
172 if provider:
173 if any(path.startswith(f"{provider}/src/") for path in paths):
174 return WHOLE
175 elif LOCK in paths:
176 return WHOLE
177 root = changes.root
178 if _matched(_patterns(inputs.widens, root), paths):
179 return WHOLE
180 if inputs.on_removal and changes.removed():
181 return WHOLE
182 if inputs.widen is not None and inputs.widen(changes):
183 return WHOLE
184 touched = _matched(_patterns(inputs.reads, root), paths)
185 if not touched:
186 return SKIP
187 return Selection(whole=False, files=touched) if inputs.per_file else WHOLE