Skip to content

livery.workshop._root_attribution

livery.workshop._root_attribution

Which packages a change to a file outside every package is about.

The affected engine (livery.workshop._graph.affected_from_paths) reads a changed root file as affecting everything, since the root files configure every gate. Adding or removing a package changes root files too: the composed pyproject.toml names the member, CODEOWNERS its directory, uv.lock its entry. This module attributes such a change to the packages it is about, so the package's own gate runs and the others' do not.

A root file's change is explained by the package set when removing every entry that names an added or removed package, from both versions, leaves the same text. uv.lock's change is attributed per member: each workspace member whose resolved closure differs is affected, and the root project's own change must lie inside the closures of affected members. Anything else is unexplained, and the caller runs everything, as before.

Classes:

Name Description
Delta

The packages that exist on one side of a change and not the other.

Functions:

Name Description
package_delta

The packages added and removed between before and the working tree.

explained

Whether a root file's change names only delta's packages.

lock_affected

The package paths whose resolution the lock's change moves; None for everything.

Attributes:

Name Type Description
LOCK
Node

LOCK module-attribute

LOCK = 'uv.lock'

Node module-attribute

Node = tuple[str, str, str]

Delta dataclass

Delta(added: tuple[Package, ...], removed: tuple[tuple[str, str], ...])

The packages that exist on one side of a change and not the other.

Attributes:

Name Type Description
added tuple[Package, ...]

The packages the change adds, as discovery sees them now.

removed tuple[tuple[str, str], ...]

The removed packages' paths and distribution names, as their contracts said before the change.

Methods:

Name Description
holds

Whether path lies under a removed package's directory.

added instance-attribute

added: tuple[Package, ...]

removed instance-attribute

removed: tuple[tuple[str, str], ...]

tokens property

tokens: tuple[str, ...]

Every path and distribution name that names a package of the delta.

holds

holds(path: str) -> bool

Whether path lies under a removed package's directory.

Source code in packages/workshop/src/livery/workshop/_root_attribution.py
def holds(self, path: str) -> bool:
    """Whether *path* lies under a removed package's directory."""
    return any(path.startswith(f"{removed}/") for removed, _ in self.removed)

package_delta

package_delta(root: Path, before: str, packages: Iterable[Package]) -> Delta

The packages added and removed between before and the working tree.

One listing of before's tree answers which contracts existed then; a package's contract is packages/<name>/workshop.toml or, in a group directory, packages/<group>/<name>/workshop.toml.

Source code in packages/workshop/src/livery/workshop/_root_attribution.py
def package_delta(root: Path, before: str, packages: Iterable[Package]) -> Delta:
    """The packages added and removed between *before* and the working tree.

    One listing of *before*'s tree answers which contracts existed
    then; a package's contract is ``packages/<name>/workshop.toml`` or,
    in a group directory, ``packages/<group>/<name>/workshop.toml``.
    """
    listed = git.run(root, "ls-tree", "-r", "--name-only", before, "--", PACKAGES_DIR)
    contracts = {
        line.removesuffix("/workshop.toml")
        for line in listed.splitlines()
        if line.endswith("/workshop.toml") and len(line.split("/")) in (3, 4)
    }
    now = list(packages)
    present = {package.path for package in now}
    added = tuple(package for package in now if package.path not in contracts)
    removed: list[tuple[str, str]] = []
    for path in sorted(contracts - present):
        try:
            contract = tomllib.loads(git.file_at(root, before, f"{path}/workshop.toml"))
        except tomllib.TOMLDecodeError:
            contract = {}
        removed.append((path, str(contract.get("name") or "")))
    return Delta(added, tuple(removed))

explained

explained(before: str, now: str, delta: Delta) -> bool

Whether a root file's change names only delta's packages.

Source code in packages/workshop/src/livery/workshop/_root_attribution.py
def explained(before: str, now: str, delta: Delta) -> bool:
    """Whether a root file's change names only *delta*'s packages."""
    tokens = delta.tokens
    if not tokens:
        return False
    return _without(before, tokens) == _without(now, tokens)

lock_affected

lock_affected(before: str, now: str, delta: Delta) -> set[str] | None

The package paths whose resolution the lock's change moves; None for everything.

Everything when either side does not parse, when anything beside the member list and the entries changed (the resolution's settings), or when the root project's closure changed outside the closures of the affected members: a tool only the root resolves configures every gate.

Source code in packages/workshop/src/livery/workshop/_root_attribution.py
def lock_affected(before: str, now: str, delta: Delta) -> set[str] | None:
    """The package paths whose resolution the lock's change moves; None for everything.

    Everything when either side does not parse, when anything beside
    the member list and the entries changed (the resolution's
    settings), or when the root project's closure changed outside the
    closures of the affected members: a tool only the root resolves
    configures every gate.
    """
    old, new = _lock(before), _lock(now)
    if old is None or new is None:
        return None
    settings = {key for key in (*old, *new) if key not in ("package", "manifest")}
    if any(old.get(key) != new.get(key) for key in settings):
        return None
    tokens = delta.tokens
    old_manifest = json.dumps(old.get("manifest") or {}, sort_keys=True)
    new_manifest = json.dumps(new.get("manifest") or {}, sort_keys=True)
    if old_manifest != new_manifest and (
        not tokens or _without(old_manifest, tokens) != _without(new_manifest, tokens)
    ):
        return None
    old_members, old_root = _closures(old)
    new_members, new_root = _closures(new)
    affected = {
        path
        for path in new_members
        if new_members[path] != old_members.get(path, frozenset())
    }
    covered: set[Node] = set()
    for path in affected | {path for path, _ in delta.removed}:
        covered |= new_members.get(path, frozenset())
        covered |= old_members.get(path, frozenset())
    moved = (old_root ^ new_root) - covered
    if moved:
        return None
    return affected