Coverage for packages/workshop/src/livery/workshop/_runs.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"""Which run replaced a cancelled one, so a watcher can say so and follow.
2
3A forge cancels a run when a newer one supersedes it: a twin for the
4same head (the pull request opened and its branch pushed in the same
5breath), or the run for a head that moved under a watch. Read alone,
6the cancelled run says "cancelled" and sends its reader to the forge
7to learn nothing went wrong. [livery.workshop._runs.successor][] names
8the run that took over, and the watchers speak it.
9"""
10
11from __future__ import annotations
12
13from dataclasses import dataclass
14
15from livery.forge import ForgeError, Repository, Run, Unsupported
16
17
18@dataclass(frozen=True)
19class Succession:
20 """A cancelled run's successor and how it relates.
21
22 Attributes:
23 run: The run that took over.
24 same_head: Whether it runs the same head (a twin), or the
25 pull request's newer head.
26 """
27
28 run: Run
29 same_head: bool
30
31
32def successor(repo: Repository, run: Run, *, branch: str = "") -> Succession | None:
33 """The run that superseded *run*, or ``None`` when none is known.
34
35 A twin is a newer run of the same workflow for the same head that
36 was not itself cancelled. Failing that, *branch*, when the caller
37 knows which branch it watched, names the pull request whose head
38 moved past *run*'s and its newest run for the new head; a forge
39 files a pull request under its current head only, so the old
40 head cannot find it. A forge that cannot answer answers ``None``:
41 the caller then reports the cancellation as it stands.
42 """
43 try:
44 twins = [
45 other
46 for other in repo.checks.runs(head_sha=run.head_sha)
47 if other.id > run.id
48 and other.workflow == run.workflow
49 and other.conclusion != "cancelled"
50 ]
51 if twins:
52 return Succession(max(twins, key=lambda other: other.id), same_head=True)
53 if not branch:
54 return None
55 pr = repo.pr.find_by_head(branch)
56 if pr is None or not pr.head_sha or pr.head_sha == run.head_sha:
57 return None
58 moved = [
59 other
60 for other in repo.checks.runs(head_sha=pr.head_sha)
61 if other.workflow == run.workflow and other.conclusion != "cancelled"
62 ]
63 except (ForgeError, Unsupported, OSError):
64 return None
65 if not moved:65 ↛ 66line 65 didn't jump to line 66 because the condition on line 65 was never true
66 return None
67 return Succession(max(moved, key=lambda other: other.id), same_head=False)
68
69
70def supersession_note(repo: Repository, run: Run, *, branch: str = "") -> str:
71 """The words for a cancelled *run*: who took over, or that no one did."""
72 if run.conclusion != "cancelled":
73 return ""
74 found = successor(repo, run, branch=branch)
75 if found is None:
76 return "cancelled; no newer run for its head or its pull request is known"
77 where = (
78 "for the same head"
79 if found.same_head
80 else f"for the moved head {found.run.head_sha[:12]}"
81 )
82 verdict = found.run.conclusion or found.run.status
83 return f"cancelled, superseded by run {found.run.id} {where} ({verdict})"