Coverage for packages/workshop/src/livery/workshop/_packages.py: 97%

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 package contracts: discovery, the graph, and the layering lint.
2
3A directory under ``packages/`` is a package exactly when it carries a
4``workshop.toml``; everything the workshop knows about a package it
5learns there. livery.workshop.verify_workspace is the layering lint:
6contracts present, declared edges agreeing with the native manifests
7in both directions, the graph acyclic, the base importing no
8extension, and each reference to a sibling declared as an edge.
9
10`holds_runtime_language` says whether a package holds the language the
11workshop runs on, `RUNTIME_LANGUAGE`; a member that does is a
12distribution of that language, and discovery requires its
13``pyproject.toml``.
14"""
15
16from __future__ import annotations(empty)
17
18import re(empty)
19from collections.abc import Callable, Iterable, Mapping(empty)
20from dataclasses import dataclass, field(empty)
21from itertools import takewhile(empty)
22from pathlib import Path, PurePosixPath(empty)
23
24from livery.workshop._contract import load_contract(empty)
25
26
27@dataclass(frozen=True)(empty)
28class Edge:(empty)
29 """One declared dependency edge of a package.
30
31 Attributes:
32 path: The dependency's identity: its directory path from the
33 workspace root, as the tags spell it.
34 kind: ``runtime``, ``build``, ``test``, or ``tool``. It
35 decides one thing: a ``runtime`` or ``build`` edge must
36 appear in the native manifest with a constraint carrying
37 its floor, and the other two have no native home. Every
38 edge counts everywhere else, whatever its kind: the
39 acyclicity check, the dependents' closure the gate
40 narrows by, the order the release wave publishes in, and
41 the floor bump.
42 floor: The released version the native manifest must require.
43 """
44
45 path: str(empty)
46 kind: str(empty)
47 floor: str(empty)
48
49
50@dataclass(frozen=True)(empty)
51class Package:(empty)
52 """One package, as its contract declares it.
53
54 Attributes:
55 directory: The package directory.
56 path: The identity path from the workspace root
57 (``packages/forge``, or ``packages/extensions/widgets`` for a
58 package in a group directory).
59 name: The distribution name (``livery-forge``).
60 depends: The declared edges, in contract order.
61 step_options: The options the package sets on its steps, by
62 the table that sets them: ``phases.<phase>`` (every step of
63 the phase) and ``phases.<phase>.<step>`` (one step), each to
64 its ``(option, value)`` pairs; the step registry validates
65 them against what the steps they reach declare.
66 categories: The package's own reassignments of its paths
67 among the categories, ``[categories] vendored =
68 ["docs/assets/vendor/**"]``: a fact about the package in
69 the narrow shape a coverage floor has, on the category
70 axis alone, winning over every extension's rule.
71 publish: Whether the release train uploads the package's
72 artifact to its registry. ``[release] publish = false``
73 keeps an internal tool versioned, tagged and built by the
74 train and never uploaded; the default is true.
75 extensions: The extensions the package lists, in its contract's
76 order: its canonical list, which the extensions it requires
77 complete into its set.
78 """
79
80 directory: Path(empty)
81 path: str(empty)
82 name: str(empty)
83 depends: tuple[Edge, ...](empty)
84 publish: bool = True(empty)
85 categories: tuple[tuple[str, tuple[str, ...]], ...] = ()(empty)
86 # Left out of the hash, so a package stays a set member and a key:
87 # an option's value may be a list, a strs option's, or anything a
88 # contract holds before the registry judges it.
89 step_options: tuple[tuple[str, tuple[tuple[str, object], ...]], ...] = field((empty)
90 default=(), hash=False
91 )
92 extensions: tuple[str, ...] = ()(empty)
93
94 @property(empty)
95 def member(self) -> str:(empty)
96 """The package's path under ``packages/``: ``forge``, ``extensions/widgets``.
97
98 It names the package in a release tag
99 (``packages/<member>/v<version>``) and everywhere else a
100 package is addressed by its place rather than its
101 distribution name.
102 """
103 return self.path.removeprefix(f"{PACKAGES_DIR}/")
104
105 @property(empty)
106 def root(self) -> Path:(empty)
107 """The root of the workspace the package is a member of.
108
109 The package's directory with its path's parts taken off, read
110 from the two fields alone, without touching the disk: the root
111 is two directories above ``packages/forge``, three above
112 ``packages/extensions/widgets``, and one above the workspace's
113 own tests ([livery.workshop.workspace_suite][]). A package whose
114 path is ``.`` is at the root, so its directory is the root.
115
116 Raises:
117 ValueError: when the directory does not end with the path,
118 naming both.
119 """
120 parts = PurePosixPath(self.path).parts
121 if not parts:
122 return self.directory
123 if self.directory.parts[-len(parts) :] != parts:
124 raise ValueError(
125 f"{self.directory} does not end with the package's path"
126 f" {self.path}, so it names no workspace root: a package's"
127 " directory is its path under the root"
128 )
129 return self.directory.parents[len(parts) - 1]
130
131
132#: The directory every package lives under, relative to the root.
133PACKAGES_DIR = "packages"(empty)
134
135
136#: How git sees a directory under ``packages/`` that has no contract.
137RESIDUE = "residue"(empty)
138TRACKED = "tracked"(empty)
139UNTRACKED = "untracked"(empty)
140SECRET = "secret"(empty)
141UNKNOWN = "unknown"(empty)
142
143
144@dataclass(frozen=True)(empty)
145class Leftover:(empty)
146 """A directory under ``packages/`` with no ``workshop.toml``, as git sees it.
147
148 Git removes a package's tracked files when a checkout moves past
149 the package's removal and keeps the files it ignores (bytecode,
150 built wheels, coverage pages), so the directory stays behind
151 without its contract.
152
153 Attributes:
154 directory: The directory.
155 state: ``residue`` when git tracks nothing under it and every
156 file it holds is one git ignores, none of them a machine
157 secret: what a removed package leaves behind, which can go.
158 ``tracked`` when git tracks a file there: a package
159 missing its contract. ``untracked`` when it holds a file
160 git neither tracks nor ignores: work nobody committed yet.
161 ``secret`` when an ignored file is a machine secret, which
162 no checkout can restore. ``unknown`` when git could not
163 answer.
164 paths: The files that decide the state, relative to the root:
165 the ignored files of residue, else the tracked, untracked
166 or secret ones.
167 reason: git's own words, when it could not answer.
168 """
169
170 directory: Path(empty)
171 state: str(empty)
172 paths: tuple[str, ...] = ()(empty)
173 reason: str = ""(empty)
174
175
176def _ls_files(root: Path, relative: str, *args: str) -> tuple[tuple[str, ...], str]:(empty)
177 """The files ``git ls-files`` lists under *relative*; git's words if it fails."""
178 from livery import git
179
180 result = git.call(root, "ls-files", "-z", *args, "--", relative)
181 if result.code != 0:
182 said = (result.stderr or result.stdout).strip()
183 return (), said or f"git ls-files exited {result.code}"
184 return tuple(sorted(entry for entry in result.stdout.split("\0") if entry)), ""
185
186
187def leftover(root: Path, directory: Path) -> Leftover:(empty)
188 """How git sees *directory*, a directory under ``packages/`` with no contract."""
189 from livery.workshop._clean import protected_within
190
191 # A pathspec in posix form: git reads a backslash as an escape.
192 relative = directory.relative_to(root).as_posix()
193 tracked, failed = _ls_files(root, relative)
194 if failed:
195 return Leftover(directory, UNKNOWN, reason=failed)
196 if tracked:
197 return Leftover(directory, TRACKED, tracked)
198 untracked, failed = _ls_files(root, relative, "--others", "--exclude-standard")
199 if failed:199 ↛ 200line 199 didn't jump to line 200 because the condition on line 199 was never true
200 return Leftover(directory, UNKNOWN, reason=failed)
201 if untracked:
202 return Leftover(directory, UNTRACKED, untracked)
203 secrets = protected_within(root, relative)
204 if secrets:
205 return Leftover(directory, SECRET, secrets)
206 ignored, failed = _ls_files(
207 root, relative, "--others", "--ignored", "--exclude-standard"
208 )
209 if failed:209 ↛ 210line 209 didn't jump to line 210 because the condition on line 209 was never true
210 return Leftover(directory, UNKNOWN, reason=failed)
211 return Leftover(directory, RESIDUE, ignored)
212
213
214def _no_contract(root: Path, directory: Path) -> str:(empty)
215 """Discovery's problem for *directory*, which has no contract.
216
217 The classification asks git, which costs a process or three, and
218 runs only here, on the way to a refusal.
219 """
220 member = directory.relative_to(root / PACKAGES_DIR).as_posix()
221 if leftover(root, directory).state != RESIDUE:
222 return f"{member}: no workshop.toml"
223 import livery.footman as footman
224
225 return (
226 f"{member}: no workshop.toml, and git tracks nothing under"
227 f" {PACKAGES_DIR}/{member}: it holds only ignored files, what a removed"
228 f" package leaves behind. `{footman.prog()} sync` removes the directory"
229 )
230
231
232def is_group(directory: Path) -> bool:(empty)
233 """Whether *directory* under ``packages/`` groups packages rather than being one.
234
235 A group has no ``workshop.toml`` of its own and at least one
236 subdirectory that has one. Groups do not nest.
237 """
238 if (directory / "workshop.toml").is_file():
239 return False
240 return any((child / "workshop.toml").is_file() for child in directory.iterdir())
241
242
243def package_directories(root: Path) -> tuple[Path, ...]:(empty)
244 """List every directory under ``packages/`` that should hold a package.
245
246 A package lives at ``packages/<name>/`` or, inside a group
247 directory, at ``packages/<group>/<name>/``. A group is a directory
248 with no ``workshop.toml`` of its own and at least one subdirectory
249 that has one. The directories are listed whether or not they carry
250 a contract, and nothing in them is judged;
251 [livery.workshop.discover_packages][] reads and judges the
252 contracts. Reach for this where a glob would assume one level.
253
254 Args:
255 root: The workspace root.
256
257 Returns:
258 The directories, sorted by path; empty when *root* has no
259 ``packages/`` directory.
260 """
261 packages_dir = root / PACKAGES_DIR
262 if not packages_dir.is_dir():
263 return ()
264 found: list[Path] = []
265 for directory in (p for p in packages_dir.iterdir() if p.is_dir()):
266 if is_group(directory):
267 found.extend(p for p in directory.iterdir() if p.is_dir())
268 else:
269 found.append(directory)
270 return tuple(sorted(found, key=lambda path: path.as_posix()))
271
272
273_RELEASE_TAG = re.compile(rf"({PACKAGES_DIR}(?:/[^/]+)+)/v(\d+\.\d+\.\d+)")(empty)
274
275
276def release_tag(tag: str) -> tuple[str, str] | None:(empty)
277 """The package path and version a release *tag* names; None for another tag.
278
279 A release tag is ``packages/<member>/v<major>.<minor>.<patch>``, and
280 the member may sit in a group directory:
281 ``packages/extensions/widgets/v1.2.0`` names
282 ``("packages/extensions/widgets", "1.2.0")``. Every reader of
283 release tags parses them here, so a package at any depth under
284 ``packages/`` releases like any other.
285 """
286 match = _RELEASE_TAG.fullmatch(tag)
287 return (match.group(1), match.group(2)) if match else None
288
289
290def receipt_member(tag: str) -> str:(empty)
291 """The member a release receipt *tag* names, or ``""`` for another tag.
292
293 ``packages/extensions/widgets/v1.2.0`` names ``extensions/widgets``.
294 """
295 found = release_tag(tag)
296 return found[0].removeprefix(f"{PACKAGES_DIR}/") if found else ""
297
298
299def member_depth(root: Path, relative: Path) -> int:(empty)
300 """How many leading parts of *relative* name a package's directory.
301
302 2 for ``packages/forge/...``, 3 for ``packages/<group>/<name>/...``
303 in a group directory, 0 for a path outside ``packages/`` or one
304 that is the package directory itself or above it.
305 """
306 parts = relative.parts
307 if len(parts) <= 2 or parts[0] != PACKAGES_DIR:
308 return 0
309 group = root / PACKAGES_DIR / parts[1]
310 if group.is_dir() and is_group(group):
311 return 3 if len(parts) > 3 else 0
312 return 2
313
314
315def member_of(relative: str, members: Iterable[str]) -> str:(empty)
316 """The member of *members* whose directory holds *relative*, or ``""``.
317
318 *relative* is a posix path from the workspace root
319 (``packages/extensions/widgets/src/x.py``); *members* are package
320 members as [livery.workshop.Package][] names them
321 (``extensions/widgets``). The longest match wins.
322 """
323 found = ""
324 for member in members:
325 if relative.startswith(f"{PACKAGES_DIR}/{member}/") and len(member) > len(
326 found
327 ):
328 found = member
329 return found
330
331
332#: The workspace's own test directory, a unit of the gate like a
333#: package's suite. It holds the root's set. Its tests reach any
334#: package, so every run of a test step that judges them runs them, and
335#: a change under it affects that unit alone.
336WORKSPACE_TESTS = "tests"(empty)
337
338
339def workspace_suite(root: Path) -> Package | None:(empty)
340 """The workspace's own tests, the ``tests`` directory at its root, as a unit.
341
342 ``None`` when the workspace has none. The unit lists no extension
343 and holds the root's set. A test step whose extensions that set
344 holds runs it beside the members it judges
345 ([livery.workshop.scoped_suite][]). It is no member, so no package
346 step judges it, and the workspace's category table answers for its
347 files (`is_workspace_unit`).
348 """
349 directory = root / WORKSPACE_TESTS
350 if not directory.is_dir():
351 return None
352 return Package(
353 directory=directory,
354 path=WORKSPACE_TESTS,
355 name="workspace-tests",
356 depends=(),
357 )
358
359
360def is_workspace_unit(package: Package) -> bool:(empty)
361 """Whether *package* is the workspace's own unit rather than a member.
362
363 The workspace's tests (`workspace_suite`) are its unit, and a root
364 without them is its own unit, for the files under no package. A
365 member's path is under ``packages/``, and a unit's is not.
366 """
367 return not package.path.startswith(f"{PACKAGES_DIR}/")
368
369
370#: The extension of the language the workshop runs on. A member
371#: holding it is a distribution of that language: discovery requires its
372#: project file, and it joins the uv workspace the venv is made from.
373RUNTIME_LANGUAGE = "python"(empty)
374
375
376def holds_runtime_language(package: Package) -> bool:(empty)
377 """Say whether *package* holds the extension of the workshop's own language.
378
379 That extension is ``python``. A member holds it when it lists it,
380 or when an extension it lists requires it. The workspace's own
381 tests hold it when the root's set does. Discovery asks this of
382 every member, so a member that lists it is answered without
383 reading any extension's declaration.
384 """
385 if RUNTIME_LANGUAGE in package.extensions:
386 return True
387 from livery.workshop._composition import extension_set
388
389 return RUNTIME_LANGUAGE in extension_set(package)
390
391
392def package_paths(packages: tuple[Package, ...]) -> tuple[str, ...]:(empty)
393 """The src and tests directories the *packages* own, as they exist.
394
395 The workspace's own tests, a unit whose directory is the tests
396 themselves, contribute that directory.
397 """
398 paths = []
399 for package in packages:
400 if package.path == WORKSPACE_TESTS:
401 if package.directory.is_dir():401 ↛ 403line 401 didn't jump to line 403 because the condition on line 401 was always true
402 paths.append(package.path)
403 continue
404 for name in ("src", "tests"):
405 directory = package.directory / name
406 if directory.is_dir():
407 paths.append(f"{package.path}/{name}")
408 return tuple(paths)
409
410
411def discover_packages(root: Path) -> tuple[Package, ...]:(empty)
412 """Every package the workspace carries, by its contract, sorted by path.
413
414 Raises ValueError, with every finding listed, when a directory
415 under ``packages/`` lacks its contract, or holds the runtime's
416 language (`holds_runtime_language`) and lacks the
417 ``pyproject.toml`` a distribution of that language carries: a
418 half-present package is a wrong state, not a lesser one. A
419 directory holding only what a removed package left behind is
420 named as such, with the ``fm sync`` that removes it. A package
421 that lists no extension holds none, and needs no project file.
422 """
423 problems = []
424 packages = []
425 # A workspace born a moment ago has no members yet; zero packages
426 # is a legal answer, not a missing directory.
427 for directory in package_directories(root):
428 member = directory.relative_to(root / PACKAGES_DIR).as_posix()
429 contract_file = directory / "workshop.toml"
430 if not contract_file.is_file():
431 problems.append(_no_contract(root, directory))
432 continue
433 contract = load_contract(contract_file)
434 depends = tuple(
435 Edge(
436 path=str(edge.get("path", "")),
437 kind=str(edge.get("kind", "build")),
438 floor=str(edge.get("floor", "")),
439 )
440 for edge in contract.get("depends", [])
441 )
442 release = contract.get("release") or {}
443 # The contract's judge has held every table below to its shape.
444 reassigned = [
445 (str(category), tuple(patterns))
446 for category, patterns in contract.get("categories", {}).items()
447 ]
448 options: list[tuple[str, tuple[tuple[str, object], ...]]] = []
449 for phase, table in contract.get("phases", {}).items():
450 # Scalars are the phase's own options, for every step of
451 # the phase; a table is one step's.
452 own = tuple(
453 (str(key), value)
454 for key, value in table.items()
455 if not isinstance(value, dict)
456 )
457 if own or not table:
458 options.append((f"phases.{phase}", own))
459 options.extend(
460 (
461 f"phases.{phase}.{step}",
462 tuple((str(key), value) for key, value in nested.items()),
463 )
464 for step, nested in table.items()
465 if isinstance(nested, dict)
466 )
467 publish = bool(release.get("publish", True))
468 package = Package(
469 directory=directory,
470 path=f"{PACKAGES_DIR}/{member}",
471 name=str(contract.get("name", "")),
472 depends=depends,
473 publish=publish,
474 categories=tuple(reassigned),
475 step_options=tuple(options),
476 extensions=tuple(str(name) for name in contract.get("extensions", ())),
477 )
478 if (
479 holds_runtime_language(package)
480 and not (directory / "pyproject.toml").is_file()
481 ):
482 problems.append(
483 f"{member}: holds {RUNTIME_LANGUAGE} and has no pyproject.toml"
484 )
485 continue
486 packages.append(package)
487 if problems:
488 raise ValueError(
489 "packages missing a file they need:\n " + "\n ".join(problems)
490 )
491 return tuple(packages)
492
493
494def verify_workspace(root: Path) -> tuple[Package, ...]:(empty)
495 """The layering lint: check every workspace invariant, or raise.
496
497 The graph's invariants ([livery.workshop._packages.verify_graph][]) and
498 the base's rules over every python source
499 ([livery.workshop._packages.import_problems][]) together, in one refusal.
500 Returns the discovered packages when everything holds. Raises
501 ValueError listing every violation verbatim otherwise:
502
503 - every ``build`` edge appears in the native manifest with a
504 constraint carrying its floor, and every workspace-internal
505 native dependency is a declared edge (agreement both ways);
506 - the dependency graph is acyclic, so dependencies only point
507 downward;
508 - the base imports no extension, and each reference a package's
509 sources make to a sibling is a declared edge.
510 """
511 packages = discover_packages(root)
512 problems = graph_problems(root, packages) + import_problems(root, packages)
513 if problems:
514 raise ValueError(
515 "the workspace breaks its layering:\n " + "\n ".join(problems)
516 )
517 return packages
518
519
520def verify_graph(root: Path) -> tuple[Package, ...]:(empty)
521 """The graph half of the layering lint: the contracts and the native manifests.
522
523 Each edge agrees with its native manifest, the graph is acyclic,
524 the extensions a contract lists close over what they require, each
525 contract's step options name what exists, and the root is no
526 package. What it reads is the contracts and the manifests, so a run
527 whose change touched none of them skips it. Returns the discovered
528 packages; raises ValueError listing every violation otherwise.
529 """
530 packages = discover_packages(root)
531 problems = graph_problems(root, packages)
532 if problems:532 ↛ 533line 532 didn't jump to line 533 because the condition on line 532 was never true
533 raise ValueError(
534 "the workspace breaks its layering:\n " + "\n ".join(problems)
535 )
536 return packages
537
538
539@dataclass(frozen=True)(empty)
540class RuleContext:(empty)
541 """What a rule of the layering phase judges: the workspace and its sources.
542
543 Attributes:
544 root: The workspace root.
545 packages: Every package the workspace carries.
546 files: The root-relative sources the run judges; None for every
547 one. A rule over the sources keeps to these, and a rule over
548 a package's references judges each package holding one
549 (`packages_in_scope`).
550 """
551
552 root: Path(empty)
553 packages: tuple[Package, ...](empty)
554 files: frozenset[str] | None = None(empty)
555
556 def packages_in_scope(self) -> tuple[Package, ...]:(empty)
557 """The packages holding a source this run judges, every one without a scope."""
558 if self.files is None:
559 return self.packages
560 files = self.files
561 return tuple(
562 package
563 for package in self.packages
564 if any(path.startswith(f"{package.path}/") for path in files)
565 )
566
567 def sources(self) -> tuple[SourceReferences, ...]:(empty)
568 """What each source this run judges references, one record per source.
569
570 Read from the ``references`` answer of each package in scope,
571 in package order.
572 """
573 from livery.workshop import _lifecycle
574
575 return tuple(
576 source
577 for package in self.packages_in_scope()
578 for source in _lifecycle.references(package)
579 if self.files is None or source.path in self.files
580 )
581
582
583#: A rule's judge: the context, to the problems, empty when the rule
584#: holds.
585Judge = Callable[[RuleContext], list[str]](empty)
586
587
588def import_problems((empty)
589 root: Path, packages: tuple[Package, ...], files: frozenset[str] | None = None
590) -> list[str]:
591 """Every base rule's findings over the sources in scope, each by its step's name."""
592 return [
593 f"{step}: {line}"
594 for step in RULES
595 for line in rule_problems(step, root, packages, files)
596 ]
597
598
599def rule_problems((empty)
600 step: str,
601 root: Path,
602 packages: tuple[Package, ...],
603 files: frozenset[str] | None = None,
604) -> list[str]:
605 """What the base's layering step *step* finds over the sources in scope.
606
607 *files* names the root-relative sources a narrowed run judges;
608 None judges every one. A rule over the sources judges the named
609 ones, and a rule over a package's references judges each package
610 holding one.
611 """
612 return RULES[step](RuleContext(root=root, packages=packages, files=files))
613
614
615def graph_problems(root: Path, packages: tuple[Package, ...]) -> list[str]:(empty)
616 """Every violation of the graph's invariants, verbatim; empty when they hold."""
617 from livery.workshop import _lifecycle
618 from livery.workshop._composition import extension_set
619
620 by_path = {package.path: package for package in packages}
621 names_by_path = {package.path: package.name for package in packages}
622 problems: list[str] = []
623
624 for package in packages:
625 # The set's answers say what the package declares natively:
626 # python's the pyproject's dependencies, conan's the recipe's
627 # references, combined.
628 native = _lifecycle.declared_requirements(package)
629 tested = _lifecycle.declared_test_requirements(package)
630 declared = {edge.path: edge for edge in package.depends}
631 for edge in package.depends:
632 if edge.path not in by_path:632 ↛ 633line 632 didn't jump to line 633 because the condition on line 632 was never true
633 problems.append(
634 f"{package.path}: declares an edge on {edge.path},"
635 " which is not a package here"
636 )
637 continue
638 if edge.kind == "test":
639 if tested is not None:
640 problems.extend(_test_problems(package, edge, by_path, tested))
641 continue
642 if edge.kind not in ("build", "runtime"):
643 continue # a tool edge has no native home
644 dep = by_path[edge.path]
645 constraint = native.get(dep.name)
646 if constraint is None:
647 # The sibling's set says which ecosystem's manifest the
648 # requirement belongs in: a writer takes its own alone.
649 held = ", ".join(extension_set(dep)) or "no extension"
650 problems.append(
651 f"{package.path}: the {edge.kind} edge on {edge.path} is not"
652 f" declared in the package's manifests ({dep.name} missing;"
653 f" {edge.path} holds {held})"
654 )
655 elif edge.floor and f">={edge.floor}" not in constraint:
656 problems.append(
657 f"{package.path}: the edge on {edge.path} floors at"
658 f" {edge.floor}, and the declared requirement says"
659 f" {dep.name}{constraint or ''}"
660 )
661 internal_names = set(names_by_path.values())
662 for name in native:
663 if name in internal_names and name != package.name:663 ↛ 662line 663 didn't jump to line 662 because the condition on line 663 was always true
664 dep_path = next(path for path, n in names_by_path.items() if n == name)
665 if dep_path not in declared:
666 problems.append(
667 f"{package.path}: depends on {name} natively, with no"
668 f" [[depends]] edge on {dep_path}"
669 )
670
671 problems.extend(_cycles(packages))
672 from livery.workshop._extensions import closure_problems
673
674 problems.extend(closure_problems(root))
675 from livery.workshop._steps import option_problems
676
677 problems.extend(option_problems(packages))
678 if (root / "src").is_dir():
679 problems.append(
680 "src/ at the workspace root is not a member: the root is never a"
681 " package, so nothing claims, formats, lints or tests it; a"
682 " package lives under packages/<name>/, one directory per"
683 " package, and a project shipping one package has one"
684 )
685 return problems
686
687
688@dataclass(frozen=True)(empty)
689class ReferencedName:(empty)
690 """One name a source references, and how the source makes the reference.
691
692 A record of [livery.workshop.SourceReferences][]: an extension that
693 answers the ``references`` query makes one for each name a source
694 references, once for each way the source makes the reference.
695
696 Attributes:
697 name: The dotted name, as the source spells it.
698 lazy: Whether only a function or a method body makes the
699 reference, so importing the source does not.
700 type_checking: Whether only a type checker makes it, so no run
701 of the source does.
702 optional: Whether the source handles the name being absent, so
703 it runs without it.
704 """
705
706 name: str(empty)
707 lazy: bool = False(empty)
708 type_checking: bool = False(empty)
709 optional: bool = False(empty)
710
711
712@dataclass(frozen=True)(empty)
713class SourceReferences:(empty)
714 """What one source references: one record of a package's ``references`` answer.
715
716 An extension that reads a language's sources answers the
717 ``references`` query with one record for each source file of the
718 package, and the layering steps resolve each name to the member
719 that owns it with [livery.workshop.neighbours][].
720
721 Attributes:
722 path: The source, relative to the workspace root, posix: a file
723 inside the package the answer is about.
724 module: The name other code references the source by; empty for
725 a source nothing references by name, such as a test.
726 references: Every name the source references, in source order,
727 once for each way the source makes the reference.
728 accounted: The names among them that the conventions of the
729 source's language account for, so they need no dependency
730 edge.
731 """
732
733 path: str(empty)
734 module: str = ""(empty)
735 references: tuple[ReferencedName, ...] = ()(empty)
736 accounted: tuple[str, ...] = ()(empty)
737
738
739@dataclass(frozen=True)(empty)
740class Neighbours:(empty)
741 """Who owns each name the workspace's members reference each other by.
742
743 [livery.workshop.neighbours][] makes it from the members; a rule
744 over the sources asks it which member a referenced name belongs to.
745
746 Attributes:
747 owners: Each module root a member ships, to the member's path.
748 Each member's extensions answer its roots
749 ([livery.workshop.MODULE_ROOTS][]), so a reference resolves
750 the same way whichever extension made it.
751 by_path: Every member by its path.
752 """
753
754 owners: Mapping[str, str](empty)
755 by_path: Mapping[str, Package](empty)
756
757 def owner_of(self, reference: str) -> str:(empty)
758 """The package path owning *reference*, longest prefix winning.
759
760 Empty when no package owns it: a third-party name, or the
761 standard library. Longest prefix, because three distributions
762 share the ``livery.toolroom`` namespace and the shortest match
763 would attribute two of them to the third.
764 """
765 best = ""
766 for prefix in self.owners:
767 matches = reference == prefix or reference.startswith(prefix + ".")
768 if matches and len(prefix) > len(best):
769 best = prefix
770 return self.owners[best] if best else ""
771
772
773def neighbours(packages: tuple[Package, ...]) -> Neighbours:(empty)
774 """Map each module root *packages* ship to the member that ships it.
775
776 Each member's set answers the roots it ships
777 ([livery.workshop.MODULE_ROOTS][]), so the map names no language.
778 A member whose set answers no root owns no name.
779
780 Args:
781 packages: The workspace's members, as
782 [livery.workshop.discover_packages][] reads them.
783
784 Returns:
785 The roots by owner and the members by path.
786 """
787 from livery.workshop import _lifecycle
788
789 owners: dict[str, str] = {}
790 for package in packages:
791 for prefix in _lifecycle.module_roots(package):
792 owners[prefix] = package.path
793 return Neighbours(owners=owners, by_path={p.path: p for p in packages})
794
795
796def _reachable(by_path: Mapping[str, Package], start: str) -> set[str]:(empty)
797 """Every package path *start* reaches through declared edges."""
798 seen: set[str] = set()
799 queue = [edge.path for edge in by_path[start].depends]
800 while queue:
801 path = queue.pop()
802 if path in seen or path not in by_path:
803 continue
804 seen.add(path)
805 queue += [edge.path for edge in by_path[path].depends]
806 return seen
807
808
809def inherited_floor(by_path: Mapping[str, Package], reach: set[str], dep: str) -> str:(empty)
810 """The floor *dep* already carries within *reach*; the highest declared.
811
812 Every declaration inside the reachable set is installed, so the
813 highest of them is what resolution already guarantees. That floor
814 claims nothing new: raising one is a decision, and the release's
815 lowest-direct leg is what proves a floor is high enough.
816 """
817 floors = [
818 edge.floor
819 for path in reach
820 for edge in by_path[path].depends
821 if edge.path == dep and edge.floor
822 ]
823 if not floors:823 ↛ 824line 823 didn't jump to line 824 because the condition on line 823 was never true
824 return "0.0.0"
825 return max(floors, key=_version_key)
826
827
828def _version_key(version: str) -> tuple[int, ...]:(empty)
829 """*version* as comparable integers; a non-numeric part sorts as zero."""
830 parts = []
831 for piece in version.split("."):
832 digits = "".join(takewhile(str.isdigit, piece))
833 parts.append(int(digits) if digits else 0)
834 return tuple(parts)
835
836
837def undeclared_references((empty)
838 packages: tuple[Package, ...], *, only: set[str] | None = None
839) -> tuple[list[tuple[Package, Package, str, str]], list[tuple[Package, Package]]]:
840 """Sibling references no edge declares, split by what the graph reaches.
841
842 Each package's ``references`` answer says what its sources
843 reference and which names its language's conventions account for;
844 this resolves each other name to the sibling that owns it and walks
845 the graph over them. A reference the declared graph already
846 reaches can be declared without changing what the graph reaches,
847 so it can introduce neither a cycle nor an upward edge, and it is
848 returned as (package, dependency, edge kind, floor). Anything else
849 is a new dependency for a person to decide, returned as
850 (package, dependency). *only* judges the packages at those paths
851 and walks the graph over every one.
852 """
853 around = neighbours(packages)
854 writable: list[tuple[Package, Package, str, str]] = []
855 refused: list[tuple[Package, Package]] = []
856 for package in packages:
857 if only is not None and package.path not in only:
858 continue
859 referenced = _referenced_siblings(package, around)
860 declared = {edge.path for edge in package.depends}
861 reach = _reachable(around.by_path, package.path)
862 for dep_path, kind in sorted(referenced.items()):
863 if dep_path in declared or dep_path not in around.by_path:
864 continue
865 dependency = around.by_path[dep_path]
866 if dep_path in reach:
867 floor = inherited_floor(around.by_path, reach, dep_path)
868 writable.append((package, dependency, kind, floor))
869 else:
870 refused.append((package, dependency))
871 return writable, refused
872
873
874def _referenced_siblings(package: Package, around: Neighbours) -> dict[str, str]:(empty)
875 """The siblings *package*'s sources reference that nothing accounts for.
876
877 Each to the edge it asks for. A name the source runs without, or
878 one the conventions of its language account for, needs no edge. A
879 sibling that only test and test-support files reference, by their
880 category, asks for a ``test`` edge; one that any other file
881 references asks for a ``runtime`` edge.
882 """
883 from livery.workshop import _lifecycle
884 from livery.workshop._categories import TEST, TEST_SUPPORT, category_of
885
886 found: dict[str, str] = {}
887 for source in _lifecycle.references(package):
888 accounted = set(source.accounted)
889 owners = {
890 owner
891 for reference in source.references
892 if not reference.optional and reference.name not in accounted
893 if (owner := around.owner_of(reference.name)) not in ("", package.path)
894 }
895 if not owners:
896 continue
897 relative = source.path.removeprefix(f"{package.path}/")
898 tested = category_of(package, relative).name in (TEST, TEST_SUPPORT)
899 for owner in owners:
900 if found.get(owner) != "runtime":900 ↛ 899line 900 didn't jump to line 899 because the condition on line 900 was always true
901 found[owner] = "test" if tested else "runtime"
902 return found
903
904
905def declare_edge((empty)
906 package: Package, dependency: Package, *, kind: str, floor: str
907) -> list[str]:
908 """Declare *package*'s *kind* edge on *dependency* at *floor*; the files written.
909
910 For a build, runtime or test edge, the writers of the package's set
911 first write the native requirement at the same floor
912 (``_lifecycle.declare_requirement``), so ``layering.graph`` finds
913 the two in agreement; then the ``[[depends]]`` edge joins the
914 package's contract. A sibling no writer takes refuses before the
915 contract changes. A test edge in a set with no writer of a test
916 requirement, and a tool edge, write no requirement. The files are
917 relative to the package, the contract first.
918 """
919 from livery.workshop import _lifecycle
920
921 required = (
922 _lifecycle.declare_requirement(package, dependency, floor, kind=kind)
923 if kind != "tool"
924 else []
925 )
926 contract = package.directory / "workshop.toml"
927 text = contract.read_text("utf-8")
928 edge = (
929 f'\n[[depends]]\npath = "{dependency.path}"\nkind = "{kind}"\n'
930 f'floor = "{floor}"\n'
931 )
932 contract.write_text(text.rstrip("\n") + "\n" + edge, encoding="utf-8")
933 return ["workshop.toml", *required]
934
935
936def write_edges(root: Path) -> list[str]:(empty)
937 """Declare every sibling reference the graph already reaches; the lines written.
938
939 The fix of the layering phase's sibling-references step. For each reference
940 [livery.workshop._packages.undeclared_references][] can write, the
941 writers of the package's set write the native requirement and the
942 ``[[depends]]`` edge joins the package's contract, both at the
943 floor the graph carries. A reference the graph does not reach is
944 left for the judge that follows: it is a new dependency, and a
945 decision. Idempotent: a second call writes nothing.
946 """
947 packages = discover_packages(root)
948 written: list[str] = []
949 for package, dependency, kind, floor in undeclared_references(packages)[0]:
950 files = declare_edge(package, dependency, kind=kind, floor=floor)
951 written.append(
952 f" layering: {package.path} declares the {kind} edge on"
953 f" {dependency.path} at floor {floor} ({', '.join(files)})"
954 )
955 return written
956
957
958def _test_problems((empty)
959 package: Package,
960 edge: Edge,
961 by_path: Mapping[str, Package],
962 tested: Mapping[str, str],
963) -> list[str]:
964 """How *package*'s test *edge* disagrees with its test requirements *tested*."""
965 from livery.workshop._composition import extension_set
966
967 dependency = by_path[edge.path]
968 constraint = tested.get(dependency.name)
969 if constraint is None:
970 held = ", ".join(extension_set(dependency)) or "no extension"
971 return [
972 f"{package.path}: the test edge on {edge.path} is not declared in the"
973 f" package's test requirements ({dependency.name} missing;"
974 f" {edge.path} holds {held}); the gate's --fix writes it"
975 ]
976 if edge.floor and f">={edge.floor}" not in constraint:
977 return [
978 f"{package.path}: the test edge on {edge.path} floors at {edge.floor},"
979 " and the declared test requirement says"
980 f" {dependency.name}{constraint}; the gate's --fix writes the floor"
981 ]
982 return []
983
984
985def write_test_requirements(root: Path) -> list[str]:(empty)
986 """Write each test requirement a package's manifests lack; the lines written.
987
988 The fix of ``layering.graph`` for the test edges it judges: in each
989 package whose set answers ``test-requirements``, a test edge whose
990 requirement is missing, or carries another floor, is written at the
991 edge's floor by the writers of the set
992 (``_lifecycle.declare_requirement``). Idempotent: a second call
993 writes nothing.
994
995 Raises:
996 Failed: when no writer of a package's set takes a test edge's
997 sibling, naming both sets.
998 """
999 from livery.workshop import _lifecycle
1000
1001 packages = discover_packages(root)
1002 by_path = {package.path: package for package in packages}
1003 written: list[str] = []
1004 for package in packages:
1005 tested = _lifecycle.declared_test_requirements(package)
1006 if tested is None:
1007 continue
1008 for edge in package.depends:
1009 if edge.kind != "test" or edge.path not in by_path:
1010 continue
1011 if not _test_problems(package, edge, by_path, tested):
1012 continue
1013 dependency = by_path[edge.path]
1014 files = _lifecycle.declare_requirement(
1015 package, dependency, edge.floor, kind="test"
1016 )
1017 if files:1017 ↛ 1008line 1017 didn't jump to line 1008 because the condition on line 1017 was always true
1018 written.append(
1019 f" layering: {package.path} requires {dependency.name}"
1020 f" at floor {edge.floor or 'none'} for its tests"
1021 f" ({', '.join(files)})"
1022 )
1023 return written
1024
1025
1026def _cycles(packages: tuple[Package, ...]) -> list[str]:(empty)
1027 """A cycle report, empty when dependencies only point downward."""
1028 edges = {
1029 package.path: [edge.path for edge in package.depends] for package in packages
1030 }
1031 seen: set[str] = set()
1032 stack: list[str] = []
1033
1034 def walk(node: str) -> list[str]:
1035 if node in stack:
1036 loop = [*stack[stack.index(node) :], node]
1037 return [" -> ".join(loop)]
1038 if node in seen:
1039 return []
1040 seen.add(node)
1041 stack.append(node)
1042 found = [cycle for child in edges.get(node, []) for cycle in walk(child)]
1043 stack.pop()
1044 return found
1045
1046 return [
1047 f"dependency cycle: {cycle}"
1048 for package in packages
1049 for cycle in walk(package.path)
1050 ]
1051
1052
1053def _sibling_references(context: RuleContext) -> list[str]:(empty)
1054 """The undeclared sibling references, by what the graph reaches.
1055
1056 A package's references come from all of its sources, so a package
1057 holding a source in scope is judged whole, and one holding none
1058 keeps its verdict.
1059 """
1060 problems: list[str] = []
1061 judged = {package.path for package in context.packages_in_scope()}
1062 writable, refused = undeclared_references(context.packages, only=judged)
1063 for package, dependency, kind, floor in writable:
1064 problems.append(
1065 f"{package.path}: uses {dependency.name} through a sibling that"
1066 f" brings it in, with no [[depends]] edge on {dependency.path}."
1067 f" Declare the {kind} edge at floor {floor}, the one the graph"
1068 " already carries, and the matching requirement; the gate's"
1069 " --fix writes both"
1070 )
1071 for package, dependency in refused:
1072 problems.append(
1073 f"{package.path}: uses {dependency.name}, and nothing it"
1074 f" depends on brings that in. Declare the edge on"
1075 f" {dependency.path} and its requirement deliberately: this"
1076 " one is a new dependency, not a fact the graph already has"
1077 )
1078 return problems
1079
1080
1081#: The base's own import path, and the namespace extensions live under.
1082BASE_MODULE = "livery.workshop"(empty)
1083EXTENSIONS_NAMESPACE = "livery.extensions"(empty)
1084
1085
1086def extension_imports_in_the_base(sources: Iterable[SourceReferences]) -> list[str]:(empty)
1087 """Each base module that imports an extension, with the extension named.
1088
1089 The base (``livery.workshop``) imports no extension under
1090 ``livery.extensions``: what an extension needs of the base it takes through
1091 the base's seams, and the base reaches an extension only through the
1092 registries the extension fills at mount. *sources* are records of the
1093 ``references`` answers; a module that runs without the name it imports
1094 is left alone, and one importing it lazily or for a type checker is
1095 judged.
1096 """
1097 problems: list[str] = []
1098 for source in sources:
1099 if not source.module.startswith(BASE_MODULE + "."):
1100 continue
1101 for reference in source.references:
1102 imported = reference.name
1103 if reference.optional:
1104 continue
1105 if imported == EXTENSIONS_NAMESPACE or imported.startswith(
1106 EXTENSIONS_NAMESPACE + "."
1107 ):
1108 problems.append(
1109 f"{source.path}: the base imports the extension {imported}; the"
1110 " base reaches an extension through a registry it fills at mount,"
1111 " never by import"
1112 )
1113 return problems
1114
1115
1116def _base_imports_no_extension(context: RuleContext) -> list[str]:(empty)
1117 """The base-imports-no-extension rule, over the ``references`` answers in scope."""
1118 return extension_imports_in_the_base(context.sources())
1119
1120
1121#: The base's rules over the sources, each the layering step of its
1122#: name, which the base registers beside its other steps: the base
1123#: importing no extension and the sibling references, both over the
1124#: ``references`` answers. The sibling step's fix writes the edges
1125#: (``write_edges``).
1126RULES: dict[str, Judge] = {(empty)
1127 "base-imports-no-extension": _base_imports_no_extension,
1128 "sibling-references": _sibling_references,
1129}