Coverage for packages/workshop/src/livery/workshop/_graph.py: 95%

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"""The affected engine: which packages a change can influence.
2
3The workspace graph is the ``[[depends]]`` edges the contracts
4declare. A changed file maps to the package whose directory holds it,
5and the affected set is that package plus everything that depends on
6it, transitively (the dependents' closure): a change can break its
7consumers, never its dependencies. A change outside every package,
8the root configuration, the templates, the workspace tests, affects
9everything, because the root files configure every gate. A change
10can reach further than its package's dependents: a listed extension
11says how far through the ``reaches`` query, as python does for a
12module pytest loads as a plugin into every suite it runs.
13
14``fm graph.affected`` prints the verdict; the quality family's
15the reflex and the CI legs scope work to it.
16"""
17
18from __future__ import annotations(empty)
19
20import functools(empty)
21from collections.abc import Callable, Iterable, Mapping(empty)
22from dataclasses import dataclass, field(empty)
23from pathlib import Path(empty)
24
25from livery import git(empty)
26from livery.footman import group(empty)
27from livery.workshop._packages import Package, discover_packages(empty)
28
29graph = group("graph", help="The workspace dependency graph")(empty)
30
31
32def dependents_closure((empty)
33 packages: tuple[Package, ...], seeds: set[str]
34) -> tuple[Package, ...]:
35 """*seeds* (package paths) plus everything depending on them.
36
37 Follows the reversed ``[[depends]]`` edges to a fixed point, and
38 answers in discovery order so output stays deterministic.
39 """
40 dependents: dict[str, set[str]] = {package.path: set() for package in packages}
41 for package in packages:
42 for edge in package.depends:
43 dependents.setdefault(edge.path, set()).add(package.path)
44 affected = set(seeds)
45 frontier = list(seeds)
46 while frontier:
47 for consumer in dependents.get(frontier.pop(), ()):
48 if consumer not in affected:
49 affected.add(consumer)
50 frontier.append(consumer)
51 return tuple(package for package in packages if package.path in affected)
52
53
54def dependencies_closure((empty)
55 packages: tuple[Package, ...], seeds: set[str]
56) -> tuple[Package, ...]:
57 """*seeds* (package paths) plus everything they depend on, transitively.
58
59 Follows the ``[[depends]]`` edges to a fixed point, and answers in
60 discovery order; [livery.workshop.order_topologically][]
61 puts each dependency before its dependents.
62 """
63 by_path = {package.path: package for package in packages}
64 needed = set(seeds)
65 frontier = list(seeds)
66 while frontier:
67 package = by_path.get(frontier.pop())
68 for edge in package.depends if package is not None else ():
69 if edge.path not in needed:
70 needed.add(edge.path)
71 frontier.append(edge.path)
72 return tuple(package for package in packages if package.path in needed)
73
74
75#: The prose directory: nothing under it reaches a gate.
76NOTES = "notes/"(empty)
77
78#: The site's own files at the root: its configuration and its pages.
79SITE_CONFIG = "zensical.toml"(empty)
80SITE_DOCS = "docs/"(empty)
81
82#: Files at the root that configure no package's steps: the licence,
83#: the CI files and the code-owners file the forge reads, the editor's
84#: and the agent's settings, git's own files, the entry script, the
85#: release's member list, the site's theme and the render's receipt.
86#: A workspace step that reads one still judges it.
87NO_PACKAGE = ((empty)
88 "LICENSE",
89 ".github/**",
90 ".gitea/**",
91 ".gitlab/**",
92 ".gitlab-ci.yml",
93 "CODEOWNERS",
94 "docs/CODEOWNERS",
95 ".vscode/**",
96 ".claude/**",
97 ".gitattributes",
98 ".gitignore",
99 "setup.sh",
100 ".release-manifest.json",
101 "overrides/**",
102 ".workshop-rendered",
103)
104
105
106def reaches_no_package(path: str) -> bool:(empty)
107 """Whether *path* is a root file no package's steps read.
108
109 A change to one gates no package; the workspace steps that read it
110 still judge it ([livery.workshop._steps.selected][]).
111 """
112 from livery.workshop._categories import matches
113
114 return any(matches(pattern, path) for pattern in NO_PACKAGE)
115
116
117def is_site(path: str) -> bool:(empty)
118 """Whether *path* is the site's own: the root ``zensical.toml`` or ``docs/`` tree.
119
120 Only the site build reads them, and it runs on every run, so
121 they reach no format, lint, type, or test gate. A package's
122 ``docs/`` directory is the package's, not the site's.
123 """
124 return path == SITE_CONFIG or path.startswith(SITE_DOCS)
125
126
127def is_prose(path: str) -> bool:(empty)
128 """Whether *path* is prose: under ``notes/``, or a markdown file anywhere.
129
130 Prose reaches no format, lint, type, or test gate. The site build
131 is where markdown is judged, and it runs on every run.
132 """
133 return path.startswith(NOTES) or path.endswith(".md")
134
135
136def affected_packages(root: Path, *, base: str = "main") -> tuple[Package, ...] | None:(empty)
137 """The packages this branch's changes can influence, and the workspace's own tests.
138
139 None means everything: a touched file outside every package (the
140 root configuration, templates) configures every gate, so no
141 narrowing is honest, and the file is named. Prose (`is_prose`)
142 and the site's own files (`is_site`) affect no package wherever
143 they live, so a diff confined to them affects nothing. A change
144 under the workspace's own ``tests/`` affects that unit alone,
145 which the answer then carries as a package of its own
146 ([livery.workshop.workspace_suite][]): its tests
147 reach every package, and every leg that runs a suite runs them
148 anyway, so no package's suite has to run for it. An empty tuple
149 means the branch changes nothing a gate reads.
150 """
151 scope = affected_by(
152 root,
153 git.changed_paths(root, base),
154 # Asked only for a change outside every package, or one inside a
155 # package the listed extensions are asked about.
156 before=lambda: git.merge_base(root, base),
157 )
158 return None if scope is None else scope.packages
159
160
161def affected_by((empty)
162 root: Path, paths: Iterable[str], *, before: str | Callable[[], str]
163) -> Scope | None:
164 """What *paths*, changed since *before*, reach among the workspace's packages.
165
166 `affected_from_paths` over the packages discovered under *root*.
167 ``None`` means everything.
168 """
169 packages = discover_packages(root)
170 return affected_from_paths(root, packages, paths, before=before)
171
172
173@dataclass(frozen=True)(empty)
174class Scope:(empty)
175 """What a change reaches: the packages, and the tests that stand for some.
176
177 Attributes:
178 packages: The packages to gate, in discovery order, the
179 workspace's own tests unit last when its files changed.
180 tests: Per package, the test files that stand for its suite;
181 the walk names none until a better narrowing exists, so
182 every package runs its suite whole.
183 examples: The package paths whose changed files are examples
184 and nothing else: their examples run and no suite. A
185 package reached through its source runs both.
186 """
187
188 packages: tuple[Package, ...](empty)
189 tests: Mapping[str, tuple[str, ...]] = field(default_factory=dict)(empty)
190 examples: tuple[str, ...] = ()(empty)
191
192
193def docs_page(packages: tuple[Package, ...], path: str) -> Package | None:(empty)
194 """The package whose authored docs page *path* is, or None for any other path."""
195 if not path.endswith(".md") or "/_generated/" in path:
196 return None
197 for package in packages:
198 if path.startswith(package.path + "/docs/"):
199 return package
200 return None
201
202
203def affected_from_paths((empty)
204 root: Path,
205 packages: tuple[Package, ...],
206 paths: Iterable[str],
207 *,
208 before: str | Callable[[], str] = "",
209) -> Scope | None:
210 """What a change to *paths* reaches: the packages, and the tests that stand alone.
211
212 The classification `affected_packages` applies to a branch's
213 changes, for any set of paths: the reflex hands it the paths
214 between a proved tree and the working tree. Each path is
215 classified by its package's kind: a test file reaches its own
216 package alone, since nothing imports a test, and that package
217 runs its whole suite; source, test support, and configuration
218 reach the package's dependents and run the suites. A change under
219 the workspace's own tests runs that unit whole. A docs page
220 reaches nothing: the site build reads it. An example file reaches
221 its package's examples step
222 and no suite, unless source of the package changed too. A file
223 outside every package reaches everything, unless *before* (the
224 commit or tree the paths were taken from) shows the change is
225 about the packages added or removed, or, for ``uv.lock``, about
226 the members whose resolution it moves
227 ([livery.workshop._root_attribution][]): then it reaches those.
228 A change inside a package reaches further when a listed extension
229 says so: each answer to the ``reaches`` query is called with the
230 change, and every member it names for a changed path runs with
231 its dependents (`_reached`).
232 *before* may be a function answering it, asked once, and only
233 when a path outside every package or an answer to ``reaches``
234 needs it.
235 ``None`` means everything, an empty scope nothing a gate reads.
236 """
237 from livery.workshop._categories import EXAMPLE, TEST, category_of
238 from livery.workshop._packages import WORKSPACE_TESTS, workspace_suite
239
240 paths = tuple(paths)
241 if not isinstance(before, str):
242 before = functools.cache(before)
243 seeds: set[str] = set()
244 # A package whose test files changed runs its whole suite; nothing
245 # imports a test, so its dependents' suites do not run. The suite
246 # is not narrowed to the changed files until a better narrowing
247 # exists: the tests a change reaches are more than the ones it edits.
248 suites: set[str] = set()
249 examples: set[str] = set()
250 tests_changed = False
251 inside = False
252 outside: list[str] = []
253 for path in paths:
254 if docs_page(packages, path) is not None:
255 continue
256 if is_prose(path) or is_site(path) or reaches_no_package(path):
257 continue
258 if path.startswith(WORKSPACE_TESTS + "/"):
259 tests_changed = True
260 continue
261 for package in packages:
262 if path.startswith(package.path + "/"):
263 inside = True
264 relative = path[len(package.path) + 1 :]
265 category = category_of(package, relative).name
266 if category == EXAMPLE:
267 examples.add(package.path)
268 elif category == TEST:
269 suites.add(package.path)
270 else:
271 seeds.add(package.path)
272 break
273 else:
274 outside.append(path)
275 if outside:
276 attributed = _attribute(root, packages, outside, before=before)
277 if attributed is None:
278 return None
279 seeds |= attributed
280 if inside:
281 widened = _reached(root, packages, paths, before=before)
282 if widened is None:
283 return None
284 seeds |= widened
285 reached = {package.path for package in dependents_closure(packages, seeds)}
286 alone = tuple(
287 sorted(path for path in examples if path not in reached and path not in suites)
288 )
289 members = tuple(
290 package
291 for package in packages
292 if package.path in reached or package.path in suites or package.path in alone
293 )
294 if not tests_changed:
295 return Scope(members, {}, alone)
296 unit = workspace_suite(root)
297 if unit is None:
298 print(f" {WORKSPACE_TESTS}/: changed and gone; everything runs")
299 return None
300 return Scope((*members, unit), {}, alone)
301
302
303def _attribute((empty)
304 root: Path,
305 packages: tuple[Package, ...],
306 paths: list[str],
307 *,
308 before: str | Callable[[], str],
309) -> set[str] | None:
310 """The packages the changes to *paths*, all outside every package, are about.
311
312 None means everything, and the first path that forces it is
313 named: without *before* there is nothing to compare with, and a
314 change the package set does not explain configures every gate.
315 """
316 from livery.workshop._root_attribution import (
317 LOCK,
318 explained,
319 lock_affected,
320 package_delta,
321 )
322
323 point = before if isinstance(before, str) else before()
324 if root is None or not point:
325 print(f" {paths[0]}: outside the packages; everything runs")
326 return None
327 delta = package_delta(root, point, packages)
328 seeds = {package.path for package in delta.added}
329 for path in paths:
330 if delta.holds(path):
331 continue # a removed package's own files: nothing depends on it now
332 old = git.file_at(root, point, path)
333 target = root / path
334 new = target.read_text("utf-8") if target.is_file() else ""
335 if path == LOCK:335 ↛ 336line 335 didn't jump to line 336 because the condition on line 335 was never true
336 moved = lock_affected(old, new, delta)
337 if moved is None:
338 print(
339 f" {path}: a resolution beyond the members moved; everything runs"
340 )
341 return None
342 seeds |= moved
343 continue
344 if not explained(old, new, delta):
345 print(f" {path}: outside the packages; everything runs")
346 return None
347 print(f" {path}: names only the packages added or removed")
348 return seeds
349
350
351def _reached((empty)
352 root: Path,
353 packages: tuple[Package, ...],
354 paths: tuple[str, ...],
355 *,
356 before: str | Callable[[], str],
357) -> set[str] | None:
358 """The members the listed extensions say the change to *paths* reaches.
359
360 Each function the extensions answer the ``reaches`` query with
361 ([livery.workshop._queries.REACHES][]) is called with the change,
362 *before* resolved only when one answers. Each changed path an
363 answer widens is printed with why, and with how many members it
364 reaches. None means everything, and the line names the extension:
365 an answer raised, or named a path outside the members.
366 """
367 from livery.workshop._influence import Changes
368 from livery.workshop._queries import REACHES, answers
369
370 try:
371 answered = answers(root, REACHES)
372 except Exception as error:
373 print(f" reaches: {error}; everything runs")
374 return None
375 if not answered:
376 return set()
377 point = before if isinstance(before, str) else before()
378 changes = Changes(root, paths, point)
379 members = {package.path for package in packages}
380 seeds: set[str] = set()
381 for name, functions in answered.items():
382 try:
383 widened = [
384 (path, why, tuple(found))
385 for function in functions
386 for path, (why, found) in function(changes).items()
387 ]
388 except Exception as error:
389 print(
390 f" {name} could not say what the change reaches ({error});"
391 " everything runs"
392 )
393 return None
394 for path, why, found in widened:
395 unknown = sorted(set(found) - members)
396 if unknown:
397 print(
398 f" {path}: {name} says it reaches {', '.join(unknown)},"
399 " outside the members; everything runs"
400 )
401 return None
402 print(f" {path}: {why}; it reaches {len(found)} package(s)")
403 seeds.update(found)
404 return seeds
405
406
407@graph.task(name="affected")(empty)
408def graph_affected(base: str = "main") -> None:(empty)
409 """Print the affected packages for this branch, one per line.
410
411 Args:
412 base: the branch the change will merge into
413 """
414 from livery.workshop._extensions import workspace_root
415
416 root = workspace_root()
417 if root is None:417 ↛ 418line 417 didn't jump to line 418 because the condition on line 417 was never true
418 print(" no workspace: no workshop.toml above the working directory")
419 return
420 git.fetch(root)
421 affected = affected_packages(root, base=base)
422 if affected is None:
423 print(" everything: a change outside the packages configures every gate")
424 return
425 if not affected:425 ↛ 426line 425 didn't jump to line 426 because the condition on line 425 was never true
426 print(" nothing: the branch changes no files")
427 return
428 for package in affected:
429 print(f" {package.path} ({package.name})")
430
431
432def order_topologically(packages: tuple[Package, ...]) -> tuple[Package, ...]:(empty)
433 """*packages* in release order: every dependency before its dependents.
434
435 Kahn's walk over the ``[[depends]]`` edges restricted to the given
436 set; ties keep the input order so the result is deterministic. A
437 cycle cannot arise, the layering lint refuses one long before a
438 release asks.
439 """
440 chosen = {p.path for p in packages}
441 remaining = list(packages)
442 ordered: list[Package] = []
443 placed: set[str] = set()
444 while remaining:
445 for index, package in enumerate(remaining):
446 needs = {
447 edge.path
448 for edge in package.depends
449 if edge.path in chosen and edge.path not in placed
450 }
451 if not needs:
452 ordered.append(package)
453 placed.add(package.path)
454 del remaining[index]
455 break
456 else: # pragma: no cover - guarded by the layering lint
457 ordered.extend(remaining)
458 break
459 return tuple(ordered)