Coverage for packages/workshop/src/livery/workshop/_verified.py: 94%

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 verified-tree record: which trees a green gate already proved, per platform.
2
3A push to main reruns the gate on a squash that, for a branch that
4sat on main's tip, is byte for byte the tree its pull request just
5verified. The gate job stamps the tree id it proved green on the
6`workshop/verified` series after its verdict, with the run, the
7commit, the scope its check legs ran, and the legs' labels
8(``check-ubuntu-latest-3.14``); every check leg reads the record
9first and skips the gate when a full entry names its own tree for
10its own platform leg. Tree identity, not merge shape, is the test,
11so the skip reaches reverts and manual re-runs, and a squash of a
12stale branch pays in full.
13
14A row proves its tree for the legs it names and for no other
15platform. After a pull request's run on one platform, the merge's
16run on that platform ends its check at once, the other platforms run
17the whole gate, and the stamp names every leg of the run, the
18skipped one included, so the tree's row then names them all. The
19machine's reflex ([livery.workshop._gate_record.plan][]) is not a
20leg: it roots on any row (`held`), since a machine is its own
21platform and its gate is the reflex, not the verdict.
22
23The record is advisory in the safe direction only: a missing entry,
24an unreachable store, another tree, or a narrowed scope runs the
25gate, and a stamp that cannot be written prints why. A leg leaves
26its scope in a marker file beside its trace, with the tree its
27narrowed gate measured from. The stamp says ``full`` when every
28check leg ran the whole gate, and also when the legs ran narrowed
29on top of a tree the record already names as full: every package a
30narrowed leg skipped is byte for byte the base tree's, and so is
31every root file the gate reads, so their verdicts carry over from
32the base's run, and the row names that base. Without a full row for
33the base, a narrowed run stamps nothing.
34
35A pull request's run on GitHub tests the merge the forge made of the
36pull request's head onto its base branch, a commit no later clone
37holds. Its row names the two commits it merged, so the next run can
38rebuild that merge and measure from it
39([livery.workshop._gate_record.leg_plan][]).
40"""
41
42from __future__ import annotations(empty)
43
44import json(empty)
45from collections.abc import Iterable(empty)
46from dataclasses import dataclass(empty)
47from datetime import UTC, datetime(empty)
48from pathlib import Path(empty)
49from typing import Any(empty)
50
51from livery import git(empty)
52from livery.workshop._ci_context import RunContext, state_store(empty)
53from livery.workshop._shard import platform_leg(empty)
54from livery.workshop._speed import forge_shard_row, leg_label, leg_of(empty)
55
56#: The series: one row per tree id, the newest kept.
57SERIES = git.Series("verified", window=200)(empty)
58
59#: The marker a check leg leaves beside its trace, naming the scope
60#: its gate ran, for the leg's metrics row and the gate job's stamp.
61MARKER = "fm-gate.json"(empty)
62
63#: The scope names a leg records: the whole gate; the gate narrowed
64#: to the affected packages; nothing, for a prose-only diff; the tree
65#: already proved, so nothing to stamp, whatever the entries after the
66#: gate ran.
67FULL = "full"(empty)
68AFFECTED = "affected"(empty)
69NOTHING = "nothing"(empty)
70VERIFIED = "verified"(empty)
71
72#: The scopes a leg can leave; anything else means the leg said nothing.
73KNOWN = (FULL, AFFECTED, NOTHING, VERIFIED)(empty)
74
75
76@dataclass(frozen=True)(empty)
77class Verified:(empty)
78 """One tree's entry: the run that proved it and what the legs ran.
79
80 Attributes:
81 tree: The git tree id the gate proved.
82 run: The forge's run id.
83 sha: The commit the run checked out.
84 scope: ``full`` when every check leg ran the whole gate, or
85 when narrowed legs composed with a full base.
86 legs: The check legs' labels (``check-ubuntu-latest-3.14``),
87 one per check leg of the run. A row written with the
88 legs' display names, as the forge lists them, reads
89 through [livery.workshop._speed.leg_label][].
90 base_tree: The tree a composed row rests on; empty otherwise.
91 base_run: The run that proved that base; empty otherwise.
92 branch: The pull request branch whose run proved the tree, whose
93 records main's run reads at the merge; empty for main's own
94 run and for a row that never said.
95 head_sha: On a run that tested a merge, the pull request's head
96 it merged; empty otherwise.
97 base_sha: On a run that tested a merge, the base branch's
98 commit it merged onto; empty otherwise.
99 """
100
101 tree: str(empty)
102 run: str(empty)
103 sha: str(empty)
104 scope: str(empty)
105 legs: tuple[str, ...](empty)
106 base_tree: str = ""(empty)
107 base_run: str = ""(empty)
108 branch: str = ""(empty)
109 head_sha: str = ""(empty)
110 base_sha: str = ""(empty)
111
112
113def tree_id(root: Path, ref: str = "HEAD") -> str:(empty)
114 """The tree id *ref* points at."""
115 # `<ref>:` names the root tree, as `^{tree}` does without a caret,
116 # which cmd.exe drops on its way to a git run through a `.cmd` launcher.
117 return git.run(root, "rev-parse", f"{ref}:").strip()
118
119
120def write_marker((empty)
121 root: Path,
122 scope: str,
123 packages: tuple[str, ...] = (),
124 *,
125 leg: str = "",
126 base_tree: str = "",
127) -> None:
128 """Leave the leg's scope, the suites it ran, and its label beside its trace.
129
130 The metrics row, the stamp, and the entries after the gate read it
131 back: *packages* are the suites the leg ran under a narrowed scope,
132 *leg* the label the leg's rows are keyed by, and *base_tree* the
133 tree a narrowed gate measured from, which the stamp composes with.
134 """
135 (root / MARKER).write_text(
136 json.dumps(
137 {
138 "scope": scope,
139 "packages": list(packages),
140 "leg": leg,
141 "base_tree": base_tree,
142 },
143 sort_keys=True,
144 ),
145 encoding="utf-8",
146 )
147
148
149@dataclass(frozen=True)(empty)
150class LegScope:(empty)
151 """What the gate ran on one check leg, as the marker the leg left says.
152
153 Attributes:
154 scope: What the gate ran. ``full``: the whole gate.
155 ``affected``: the gate narrowed to the packages a change
156 affects. ``nothing``: no package's steps, for a change that
157 affects no package, such as prose alone; the workspace
158 steps whose inputs it changed still run. ``verified``: no
159 step, since the verified record already proves the tree.
160 ``unknown``: the leg left no marker, or one that does not
161 parse.
162 packages: The paths of the suites a narrowed gate ran; empty
163 for every other scope.
164 leg: The label the leg's rows are keyed by
165 (``check-ubuntu-latest-3.14``); empty when the marker names
166 none.
167 base_tree: The tree a narrowed gate measured from; empty for
168 every other scope.
169 """
170
171 scope: str(empty)
172 packages: tuple[str, ...] = ()(empty)
173 leg: str = ""(empty)
174 base_tree: str = ""(empty)
175
176
177def leg_scope(root: Path) -> LegScope:(empty)
178 """Read what the gate ran on this leg from the marker it left at *root*.
179
180 The gate leaves the marker on a CI run's check leg, so the leg's
181 entries after the gate read it there. A gate outside CI leaves
182 none.
183
184 Returns:
185 The leg's scope; ``unknown`` when there is no marker, or the
186 marker is not a JSON object.
187 """
188 unknown = LegScope("unknown")
189 path = root / MARKER
190 if not path.is_file():
191 return unknown
192 try:
193 loaded = json.loads(path.read_text("utf-8"))
194 except (OSError, ValueError):
195 return unknown
196 if not isinstance(loaded, dict):
197 return unknown
198 return LegScope(
199 scope=str(loaded.get("scope", "unknown")),
200 packages=tuple(str(p) for p in loaded.get("packages", []) or []),
201 leg=str(loaded.get("leg", "") or ""),
202 base_tree=str(loaded.get("base_tree", "") or ""),
203 )
204
205
206@dataclass(frozen=True)(empty)
207class VerifiedBranch:(empty)
208 """The branch whose run proved a tree, or why the record could not say.
209
210 Attributes:
211 branch: The pull request branch whose run proved the tree;
212 empty when no row names the tree, when the row names no
213 branch, as main's own run's does, and when the row could
214 not be read.
215 reason: Why the record decided nothing: the tree has no id, or
216 its row could not be read; empty when the record was read.
217 """
218
219 branch: str(empty)
220 reason: str = ""(empty)
221
222
223def verified_branch(root: Path) -> VerifiedBranch:(empty)
224 """Read which branch's run proved the tree checked out at *root*.
225
226 Main's run after a squash merge reads it to find the branch whose
227 records the tree carries. A row the store cannot read, and a tree
228 git cannot name, decide nothing: the branch is empty and the
229 reason says why, so the caller reads main's records alone.
230 """
231 try:
232 tree = tree_id(root)
233 except git.GitError as error:
234 return VerifiedBranch("", f"the tree has no id ({error})")
235 row, why = record(root, tree)
236 if why:
237 return VerifiedBranch("", why)
238 return VerifiedBranch(row.branch if row is not None else "")
239
240
241def record((empty)
242 root: Path, tree: str, *, before: datetime | None = None
243) -> tuple[Verified | None, str]:
244 """The entry for *tree*, or ``(None, reason)``; an absent entry has no reason.
245
246 A read the transport could not answer falls open with its words,
247 and so does an entry that is not a row of the record's schema:
248 the gate runs, and the line says why the record did not decide.
249 With *before*, an entry the store stamped at or after it, or never
250 stamped, reads as absent (`written_before`).
251 """
252 row, why = SERIES.row(state_store(root), tree)
253 if row is None:
254 return None, why
255 if not written_before(row.when, before):
256 return None, ""
257 return _entry(tree, row.data), ""
258
259
260def written_before(when: str, before: datetime | None) -> bool:(empty)
261 """Whether a row stamped *when* counts under the bound *before*.
262
263 Every row counts without a bound. With one, a row counts when the
264 store stamped it before the bound; an unstamped row or a stamp
265 that does not parse never does. The shards of a check leg read the
266 record under one bound, the committer time of the commit they all
267 checked out, so a row another run writes while they start counts
268 for all of them or for none.
269 """
270 if before is None:
271 return True
272 try:
273 moment = datetime.fromisoformat(when) if when else None
274 except ValueError:
275 moment = None
276 if moment is None:
277 return False
278 if moment.tzinfo is None:
279 moment = moment.replace(tzinfo=UTC)
280 bound = before if before.tzinfo is not None else before.replace(tzinfo=UTC)
281 return moment < bound
282
283
284def _entry(tree: str, entry: dict[str, Any]) -> Verified:(empty)
285 """The row of *tree* as the record's own type."""
286 return Verified(
287 tree=tree,
288 run=str(entry.get("run", "")),
289 sha=str(entry.get("sha", "")),
290 scope=str(entry.get("scope", "")),
291 legs=tuple(str(leg) for leg in entry.get("legs", [])),
292 base_tree=str(entry.get("base_tree", "")),
293 base_run=str(entry.get("base_run", "")),
294 branch=str(entry.get("branch", "") or ""),
295 head_sha=str(entry.get("head_sha", "") or ""),
296 base_sha=str(entry.get("base_sha", "") or ""),
297 )
298
299
300def proves(row: Verified, leg: str = "") -> bool:(empty)
301 """Whether *row* proves its tree for *leg*: a full row naming the leg's platform.
302
303 With *leg* empty, any full row does. Each stored name is read
304 through [livery.workshop._speed.leg_label][], so a row written
305 with the forge's display names counts for the leg it names, and
306 the names and *leg* are compared as platform legs
307 ([livery.workshop.platform_leg][]), so a shard of a platform reads
308 the row the fold stamped under the platform leg as its own.
309 """
310 if row.scope != FULL:310 ↛ 311line 310 didn't jump to line 311 because the condition on line 310 was never true
311 return False
312 platform = platform_leg(leg)
313 return not leg or platform in {platform_leg(leg_label(name)) for name in row.legs}
314
315
316def proved((empty)
317 root: Path, leg: str = "", *, before: datetime | None = None
318) -> tuple[dict[str, Verified], str]:
319 """The rows that prove their trees for *leg*, by tree, newest first, in one read.
320
321 ``({}, reason)`` when the record could not be read. With a leg,
322 the full rows that name it (`proves`); without one, every full
323 row. A row of a narrowed scope proves nothing and is left out, as
324 a file that is not a row of the record's schema is. With *before*,
325 only the rows the store stamped before it (`written_before`).
326 """
327 found = SERIES.rows(state_store(root))
328 if found.failed:
329 return {}, found.reason
330 rows = (
331 _entry(row.name, row.data)
332 for row in found.rows
333 if written_before(row.when, before)
334 )
335 return {entry.tree: entry for entry in rows if proves(entry, leg)}, ""
336
337
338def held(root: Path, trees: Iterable[str]) -> tuple[set[str], str]:(empty)
339 """The trees among *trees* the record holds, in one read, whatever legs they name.
340
341 The machine's reflex roots its chain here and asks for no leg: a
342 machine is its own platform, and its gate is the reflex, not the
343 verdict, so any tree CI's record holds is a root.
344
345 ``(set(), reason)`` when the record could not be read. A file that
346 is not a row of the record's schema is skipped the way every read
347 skips it, so its tree reads as not held; an absent record holds
348 nothing, without a reason.
349 """
350 found = SERIES.rows(state_store(root))
351 if found.failed:
352 return set(), found.reason
353 names = {row.name for row in found.rows}
354 return {tree for tree in trees if tree in names}, ""
355
356
357def stamp((empty)
358 root: Path,
359 run: RunContext,
360 *,
361 tree: str,
362 sha: str,
363 legs: tuple[str, ...],
364 base: Verified | None = None,
365 branch: str = "",
366 merged: tuple[str, str] | None = None,
367) -> str:
368 """Record *tree* as proved green by *run*; ``""`` or the reason.
369
370 Only a CI run writes. *legs* are the labels of the run's check
371 legs: each ran the full gate, skipped on a full row that named
372 it, or ran narrowed on top of *base*, a full row the caller read
373 from the record; a composed row names that base and its run. *branch*
374 is the pull request branch the run came from, so main's run after
375 the squash knows whose records the tree carries. *merged*
376 are the base branch's commit and the head a merge checkout joined,
377 so the branch's next run can rebuild the merge.
378 """
379 entry: dict[str, object] = {
380 "tree": tree,
381 "run": run.run_id,
382 "sha": sha,
383 "forge": run.forge,
384 "scope": FULL,
385 "legs": list(legs),
386 }
387 if branch:
388 entry["branch"] = branch
389 if merged is not None:
390 entry["base_sha"], entry["head_sha"] = merged
391 basis = ""
392 if base is not None:
393 entry["base_tree"] = base.tree
394 entry["base_run"] = base.run
395 basis = f" on top of {base.tree[:12]}"
396 return SERIES.put(
397 state_store(root),
398 {tree: entry},
399 message=f"verified: tree {tree[:12]} by run {run.run_id}{basis}",
400 )
401
402
403def stamp_from_metrics(root: Path, run: RunContext, *, sha: str) -> str:(empty)
404 """Stamp the run's tree from what its check legs' rows say they ran.
405
406 Reads the run's file on the metrics series, which the collect
407 step put before the verdict; each check leg's row carries the
408 scope its marker named and the leg's label, which the stamp
409 names ([livery.workshop._speed.leg_of][]), so GitLab's bare job
410 name records its platform too. A platform that ran as shards has
411 one row, folded under its own name before the collect, and the
412 forge's rows of its shards beside it, which carry no scope and are
413 skipped ([livery.workshop._speed.forge_shard_row][]). Every leg
414 full, or skipped on the record: the tree is stamped naming every
415 leg, so after a pull
416 request's run on one platform the merge's run leaves a row naming
417 every platform. Legs narrowed (``affected``, or ``nothing`` for a prose-only
418 diff): the tree is stamped when every narrowed leg measured from
419 one tree and the record names that tree as full, and the row
420 names that base; otherwise nothing is written and the line says
421 which proof is missing. On a merge checkout the row also names
422 the two commits merged. Returns the line to print.
423 """
424 from livery.workshop._metrics import SERIES as METRICS
425 from livery.workshop._metrics import run_file
426
427 row, why = METRICS.row(state_store(root), run_file(run.run_id))
428 if why:428 ↛ 429line 428 didn't jump to line 429 because the condition on line 428 was never true
429 return f" verified: no stamp, {why}"
430 if row is None:
431 return f" verified: no stamp, run {run.run_id} left no row"
432 jobs = row.data.get("jobs", {})
433 if not isinstance(jobs, dict):433 ↛ 434line 433 didn't jump to line 434 because the condition on line 433 was never true
434 jobs = {}
435 # The forge's own rows of a platform's shards carry no scope; the
436 # folded row under the platform's name carries what the stamp reads.
437 names = sorted(
438 name
439 for name in jobs
440 if name.startswith("check") and not forge_shard_row(name, jobs[name])
441 )
442 if not names:442 ↛ 443line 442 didn't jump to line 443 because the condition on line 442 was never true
443 return " verified: no stamp, the run had no check leg"
444 scopes = {
445 name: str((jobs[name].get("scope") or {}).get("scope", "unknown"))
446 for name in names
447 }
448 legs = tuple(sorted(leg_of(name, jobs[name]) for name in names))
449 unknown = [name for name, scope in scopes.items() if scope not in KNOWN]
450 if unknown:
451 return f" verified: no stamp, {', '.join(unknown)} left no scope"
452 tree = tree_id(root)
453 if all(scope == VERIFIED for scope in scopes.values()):
454 return f" verified: tree {tree[:12]} is already recorded; nothing to stamp"
455 try:
456 merged = git.merge_parents(root)
457 except git.GitError as error:
458 return f" verified: no stamp, HEAD's parents could not be read ({error})"
459 if all(scope in (FULL, VERIFIED) for scope in scopes.values()):
460 why = stamp(
461 root,
462 run,
463 tree=tree,
464 sha=sha,
465 legs=legs,
466 branch=run.head_ref,
467 merged=merged,
468 )
469 if why:469 ↛ 470line 469 didn't jump to line 470 because the condition on line 469 was never true
470 return f" verified: no stamp, {why}"
471 return (
472 f" verified: tree {tree[:12]} recorded as proved green by run {run.run_id}"
473 )
474 # Narrowed legs prove the packages they ran; the base tree's row
475 # proves the rest, since those packages and every root file the
476 # gate reads are the base's bytes, or the legs would have widened.
477 narrowed = {
478 name: scope for name, scope in scopes.items() if scope not in (FULL, VERIFIED)
479 }
480 bases = {
481 name: str((jobs[name].get("scope") or {}).get("base_tree", "") or "")
482 for name in narrowed
483 }
484 unnamed = sorted(name for name, base in bases.items() if not base)
485 if unnamed:
486 return (
487 f" verified: no stamp, {', '.join(unnamed)} named no tree its"
488 " narrowed gate measured from"
489 )
490 if len(set(bases.values())) > 1:
491 named = ", ".join(f"{name} from {base[:12]}" for name, base in bases.items())
492 return f" verified: no stamp, the legs measured from different trees ({named})"
493 base = next(iter(bases.values()))
494 base_row, why = record(root, base)
495 if why:
496 return (
497 f" verified: no stamp, the base tree {base[:12]} could not be read ({why})"
498 )
499 if base_row is None or base_row.scope != FULL:
500 return (
501 f" verified: no stamp, {', '.join(narrowed)} ran narrowed on base tree"
502 f" {base[:12]}, which the record has not proved in full"
503 )
504 why = stamp(
505 root,
506 run,
507 tree=tree,
508 sha=sha,
509 legs=legs,
510 base=base_row,
511 branch=run.head_ref,
512 merged=merged,
513 )
514 if why:514 ↛ 515line 514 didn't jump to line 515 because the condition on line 514 was never true
515 return f" verified: no stamp, {why}"
516 return (
517 f" verified: tree {tree[:12]} recorded as proved green by run {run.run_id}"
518 f" on top of tree {base[:12]} (run {base_row.run})"
519 )