1"""The quality verbs: the gate and its parts, over the packages the contracts declare.
3Each verb discovers the packages by their ``workshop.toml`` and runs
4its phase's registered steps over them, each step over the packages
5whose extensions it judges. ``check`` is the whole local gate; CI runs
6the same command.
7"""
19 from datetime import datetime
21 from livery.workshop._gate_record import Plan
22 from livery.workshop._influence import Changes
23 from livery.workshop._verified import Verified
33 ONE,
34 Shard,
35 checkout_time,
36 files_digest,
37 leave_shard,
38 shard_of,
39)
41# Re-exported by name: the drift step's body looks it up on this
42# module at run time, which is where the gate's characterisation tests
43# patch it.
48 """The workspace's packages, discovered before anything runs."""
49 root = workspace_root()
50 if root is None:50 ↛ 51line 50 didn't jump to line 51 because the condition on line 50 was never true
51 raise ValueError("no workspace: no workshop.toml above the working directory")
52 return discover_packages(root)
56 *,
57 subset: tuple[Package, ...] | None = None,
58 fix: bool = False,
59 files: tuple[str, ...] = (),
60 safe: bool = False,
61 point: str = "",
62 shard: Shard = ONE,
63 tests: Mapping[str, tuple[str, ...]] | None = None,
64 examples: tuple[str, ...] = (),
65 changes: Changes | None = None,
66 arguments: tuple[str, ...] = (),
67) -> PhaseContext:
68 """This workspace's gate context: the root, every package, and the run's scope."""
69 root = workspace_root()
70 if root is None:70 ↛ 71line 70 didn't jump to line 71 because the condition on line 70 was never true
71 raise ValueError("no workspace: no workshop.toml above the working directory")
72 return PhaseContext(
73 root=root,
74 packages=_packages(),
75 subset=subset,
76 tests=tests or {},
77 examples=examples,
78 fix=fix,
79 files=files,
80 safe=safe,
81 point=point,
82 shard=shard,
83 changes=changes,
84 arguments=arguments,
85 )
88#: What the gate gives its phases: the build phase's tree side, in the
89#: instrumented configuration.
91 "build": {"isolated": False, "configuration": "instrumented"}
92}
94#: What a phase's own verb gives its phases: the build phase's tree side,
95#: in the debug configuration, so a bare ``fm build`` builds what
96#: ``fm run`` starts, and the gate alone instruments.
98 "build": {"isolated": False, "configuration": "debug"}
99}
103 ctx: PhaseContext,
104 *,
105 between: Callable[[], None] | None = None,
106 judge: bool = True,
107 only: frozenset[str] | None = None,
108 inputs: Mapping[str, Mapping[str, object]] = GATE_INPUTS,
109) -> None:
110 """Walk the registry: the one place the gate's order lives.
112 Every gate comes here, the whole one, CI's narrowed legs and a
113 machine's narrowed step alike, and runs the registry's steps
114 through the one walk ([livery.workshop._phases.walk_steps][]). Each
115 step an extension registered is named first. Under ``--fix`` every
116 fixer that applies runs, one at a time in the rewriters' order,
117 before any judge reads the tree, and a step that rewrote is not
118 judged again in the run; then *between* runs, where a machine's
119 run measures the tree the judges read; then every judge runs in
120 one parallel block, the steps a judge runs after among them, and
121 one refusal is the verdict. A step whose claims reach no file in
122 scope is said and not started. On a shard other than the first, a
123 step that does not read the shard is left to the first shard and
124 said ([livery.workshop._steps.on_this_shard][]). Without *judge*
125 the walk stops after the fixers, the post-edit hook's run. *only*
126 keeps the named steps alone, a generated verb's run. *inputs* are
127 the keys the walk gives each phase, the gate's own
128 ([livery.workshop._quality.GATE_INPUTS][]) unless another engine
129 names its.
130 """
131 for line in _steps.narrowings():
132 print(line)
133 ctx = replace(ctx, catalogue=_steps.catalogue(ctx))
135 def kept(names: tuple[str, ...]) -> tuple[str, ...]:
136 if only is not None:
137 names = tuple(n for n in names if n in only)
138 return _steps.on_this_shard(_steps.with_files(names, ctx), ctx)
140 for name in kept(_steps.rewriters(ctx)):
141 walk_steps(ctx, (_steps.step_for(name),), inputs=inputs, fixing=True)
142 if ctx.fix and between is not None:
143 between()
144 if not judge:
145 return
146 walk_steps(ctx, _steps.with_earlier(kept(_steps.judges(ctx))), inputs=inputs)
150 if fix and safe_fix:
151 fail(
152 "--fix and --safe-fix are two answers to one question: --fix"
153 " applies every safe fix, --safe-fix withholds the"
154 " code-removing ones. Pass one."
155 )
158#: The contract key that lets CI's check legs run the scoped gate.
163 """The contract's ``[ci] affected-legs``; false when undeclared.
165 The contract's judge holds the value to a boolean: the legs either
166 narrow or they do not, and a stray string would read as true.
167 """
168 from livery.workshop._contract import load_contract
170 ci = load_contract(root / "workshop.toml").get("ci") or {}
171 return bool(ci.get(AFFECTED_LEGS_KEY, False))
175 """The base branch a pull request's check leg narrows against, or empty.
177 Empty outside CI, when the contract does not declare
178 ``[ci] affected-legs``, on any event but a pull request, and when
179 the payload names no base. A push's legs take their plan from
180 `ci_push_base` instead; the nightly and a dispatch pay the whole
181 gate, and say so, so a full leg is never a silent fallback.
182 """
183 if run is None or not affected_legs(root):
184 return ""
185 if run.event == "push":
186 return ""
187 if run.event != "pull_request":
188 print(
189 f" affected-legs: a {run.event or 'non pull request'} run pays"
190 " the full gate"
191 )
192 return ""
193 if not run.base_ref:
194 print(" affected-legs: the event payload names no base branch; full gate")
195 return ""
196 return run.base_ref
200 """The branch a push's check leg stands on, for its plan; empty off a push.
202 Empty outside CI, without ``[ci] affected-legs``, on any event but
203 a push, and on a push of a ref that is not a branch. A push's leg
204 measures from the nearest tree CI's record proves in HEAD's
205 history, the previous push's as a rule, and pays the whole gate
206 when the record proves none: on the pushed branch the merge base
207 is HEAD itself, so it is never the step's base (`_leg_plan`).
208 """
209 if run is None or not affected_legs(root) or run.event != "push":
210 return ""
211 prefix = "refs/heads/"
212 return run.ref[len(prefix) :] if run.ref.startswith(prefix) else ""
216 """What this CI run changed against the base it measures from; None for everything.
218 A pull request's run in a workspace that declares ``[ci]
219 affected-legs`` measures from its base branch: the paths changed
220 since the merge base with ``origin/<base>``, committed or not, with
221 that merge base, so a ``widen`` reference can read a file as it
222 was. None at a desk, on any other event, without
223 ``affected-legs``, and when git cannot answer; the run then judges
224 everything, and the line printed says why.
225 """
226 from livery.workshop._ci_context import run_context
227 from livery.workshop._influence import Changes
229 run = run_context()
230 base = ci_affected_base(root, run) if run is not None else ""
231 if not base:
232 return None
233 try:
234 git.fetch(root)
235 paths = tuple(git.changed_paths(root, base))
236 before = git.merge_base(root, base)
237 except git.GitError as error:
238 print(
239 f" affected-legs: no diff against origin/{base}; everything is"
240 f" judged ({error})"
241 )
242 return None
243 return Changes(root, paths, before)
247 root: Path, leg: str = "", *, before: datetime | None = None
248) -> Verified | None:
249 """The record's full row for this tree and *leg*, or ``None`` to run the gate.
251 Prints the run that proved it when it does, and the reason when
252 the record could not decide (an unreadable store, an entry of
253 another shape); an absent entry or a narrowed scope is the
254 ordinary case and stays quiet. A full entry that names other
255 legs and not *leg* is named, and the gate runs: a row proves its
256 tree for the platforms that ran it. With *leg* empty any full
257 entry counts. Never skips on anything but a full entry for this
258 exact tree. The row names the branch whose run proved it. With
259 *before*, an entry stamped at or after it reads as absent, so the
260 shards of a leg skip together or run together.
261 """
262 from livery.workshop import _verified
264 try:
265 tree = _verified.tree_id(root)
266 except git.GitError as error:
267 print(f" verified: this checkout has no tree id ({error}); running the gate")
268 return None
269 found, why = _verified.record(root, tree, before=before)
270 if why:
271 print(f" verified: {why}; running the gate")
272 return None
273 if found is None or found.scope != _verified.FULL:
274 return None
275 if not _verified.proves(found, leg):
276 print(
277 f" verified: tree {tree[:12]} proved green by run {found.run} on"
278 f" {', '.join(found.legs)}, not on {leg}; running the gate"
279 )
280 return None
281 basis = f" on top of tree {found.base_tree[:12]}" if found.base_tree else ""
282 print(
283 f" verified: tree {tree[:12]} proved green by run {found.run}"
284 f" at {found.sha[:12]}{basis}; skipping the gate"
285 )
286 return found
290 """The bound every shard of this leg reads CI's record under; ``None`` unsharded.
292 The committer time of the commit the leg checked out, which every
293 shard of the run checks out alike, and a rerun too: a row another
294 run writes while the shards start counts for all of them or for
295 none, so they measure from one tree and skip together. An unsharded
296 leg reads the whole record, as one leg cannot disagree with itself.
297 """
298 if run.shard.count <= 1:
299 return None
300 return checkout_time(root)
304 """Where this CI leg measures its change from, said in one line.
306 The reflex's rule over CI's record ([livery.workshop._gate_record.leg_plan][]):
307 the proved tree nearest HEAD's, an earlier push's merge included,
308 or the merge base with *base* when the record proves none. A merge
309 base git cannot compute (a shallow checkout, a base the fetch did
310 not bring) falls open to everything, with git's words.
311 """
312 from livery.workshop import _gate_record
313 from livery.workshop._gate_record import Plan
315 git.fetch(root)
316 step = _gate_record.leg_plan(
317 root,
318 base=base,
319 branch=run.head_ref,
320 leg=run.leg,
321 before=_shared_bound(root, run),
322 )
323 if run.event == "push" and step.mode == _gate_record.MERGE_BASE:
324 # On the pushed branch the merge base is HEAD itself, and a step
325 # from it would judge nothing: a push with no proved tree in
326 # reach pays the whole gate.
327 step = Plan("full", step.tree, why=f"{step.why}; a push pays the whole gate")
328 count = f"{len(step.paths)} path(s) changed"
329 if step.mode == _gate_record.MERGE_BASE:
330 print(f" from the merge base, tree {step.base_tree[:12]}: {step.why}; {count}")
331 elif step.mode == "step":
332 print(f" since tree {step.base_tree[:12]} ({step.why}): {count}")
333 elif run.event == "push":
334 print(f" affected: {step.why}; everything runs")
335 else:
336 print(f" affected: {step.why}; failing open to everything")
337 return step
341 """The packages *step*'s paths reach; None means everything."""
342 from livery.workshop._graph import affected_by
344 if step.mode == "full":344 ↛ 346line 344 didn't jump to line 346 because the condition on line 344 was always true
345 return None
346 scope = affected_by(root, step.paths, before=step.base_tree)
347 return None if scope is None else scope.packages
352 *paths: str,
353 full: Annotated[bool, doc("run everything, whatever the record proves")] = False,
354 fix: Forward[bool] = False,
355 safe_fix: Annotated[
356 bool, doc("fix, removing no code: safe for an edit in flight")
357 ] = False,
358 base: Annotated[str, doc("the branch the chain's root is taken from")] = "main",
359 point: Annotated[str, doc("run the tests of this CI point, nightly say")] = "",
360 shard: Annotated[
361 str,
362 doc("run this shard's share of a sharded check leg: <i>of<n>, such as 2of4"),
363 ] = "",
364) -> None:
365 """Run the gate: every registered step, the rewriters first under --fix.
367 With *paths*, exactly those files are checked, or the files under
368 those directories: every step whose claims reach one of them runs
369 over them and no other, a step without claims does not run, and
370 nothing is recorded as proved. ``--safe-fix`` runs the fixers in
371 their in-flight mode, which removes no code, and refuses beside
372 ``--fix``. ``--point`` hands a CI point to the test phase, which
373 selects that point's tests instead of the gate's.
375 ``--shard`` names the shard of a sharded check leg this run is,
376 ``2of4``: a step that reads the shard runs its share, every other
377 step runs on the first shard alone, and the walk names each step
378 it leaves there. Inside CI the leg's label names the shard and the
379 flag is not needed. A sharded run records no tree as proved, since
380 a share of the gate ran. A shard outside the form, ``0of2``,
381 refuses naming it.
383 On a machine the gate is the reflex: it runs what the working
384 tree changed since the nearest tree this checkout's own green
385 gates proved, the packages that delta can influence (their
386 dependents' closure), and records the working tree as proved on
387 the local gate record ([livery.workshop._gate_record][]). A tree
388 the record already proves runs nothing. The chain of records
389 rests on a full gate here or on CI's record of the merge base
390 with ``--base``, so a fresh branch off main starts proved. A
391 change outside the packages configures every gate, so it runs
392 everything and roots a new chain; ``--full`` runs everything
393 whatever the record says. ty and pyrefly always check their
394 configured whole either way.
396 Inside CI, when the contract declares ``[ci] affected-legs``, a
397 pull request's legs measure by the same rule from CI's own record,
398 read for the leg's own platform: from the proved tree nearest the
399 checkout's, an earlier push's merge among them, or from the merge
400 base with the pull request's base when the record proves none.
401 Without the key they run the whole workspace. The local record is
402 never read or written there.
404 ``--fix`` runs format and lint in their fix modes: each prints
405 what it found, rewrites what is mechanical, and still fails on
406 what is not. The two rewrite the same files, so under ``--fix``
407 they run one after the other before the rest of the gate.
409 ``--fix`` refuses inside CI: a runner's checkout is judged,
410 never rewritten, because a fix there mutates a copy nobody
411 keeps and hides the finding from the verdict. Run the fix
412 locally and push the result.
414 On a machine the state store is read from what the last ``sync``
415 or ``start`` fetched ([livery.git.fetched_snapshot][]):
416 nothing the gate runs reaches origin, and a checkout the store was
417 never fetched into roots its chain on a full gate and says so.
418 Inside CI the legs read the store as the run's own snapshot.
419 """
420 from contextlib import nullcontext
422 from livery.git import fetched_snapshot
423 from livery.workshop._ci_context import run_context
424 from livery.workshop._steps import arguments_refusal, split_arguments
426 _refuse_both(fix, safe_fix)
427 chosen = _current_shard(shard)
428 paths, arguments = split_arguments(paths)
429 if arguments:
430 verb = f"{footman.prog()} check"
431 fail(arguments_refusal(verb, _steps.steps_by_name().values()))
432 if paths:
433 _check_files(
434 paths, fix=fix or safe_fix, safe=safe_fix, point=point, shard=chosen
435 )
436 return
437 root = workspace_root()
438 scope = (
439 fetched_snapshot(state_store(root))
440 if root is not None and run_context() is None
441 else nullcontext()
442 )
443 with scope:
444 _run_check(
445 full=full,
446 fix=fix or safe_fix,
447 base=base,
448 point=point,
449 safe=safe_fix,
450 shard=chosen,
451 )
455 """*paths* as the files they name, root-relative: a file, or a directory's files.
457 A directory stands for the files git holds under it, tracked or
458 untracked and not ignored, or every file under it outside a git
459 checkout. A path outside the root, or naming nothing, is left out.
460 """
461 found: set[str] = set()
462 for path in paths:
463 target = Path(path).resolve()
464 try:
465 relative = target.relative_to(root.resolve()).as_posix()
466 except ValueError:
467 continue
468 if target.is_file():
469 found.add(relative)
470 elif target.is_dir():
471 try:
472 found.update(git.ls_files(root, relative, others=True))
473 except git.GitError:
474 found.update(
475 p.relative_to(root.resolve()).as_posix()
476 for p in target.rglob("*")
477 if p.is_file()
478 )
479 return tuple(sorted(name for name in found if (root / name).is_file()))
483 """Whether *path* is a file or a directory under *root*."""
484 target = Path(path).resolve()
485 return target.is_relative_to(root.resolve()) and target.exists()
489 paths: tuple[str, ...],
490 *,
491 fix: bool,
492 safe: bool,
493 point: str,
494 shard: Shard = ONE,
495 judge: bool = True,
496 only: frozenset[str] | None = None,
497 arguments: tuple[str, ...] = (),
498 inputs: Mapping[str, Mapping[str, object]] = GATE_INPUTS,
499) -> None:
500 """The gate over the named files: the walk narrowed to them, nothing recorded.
502 A person's path that names nothing in the workspace refuses, since
503 running nothing there would pass: a typo, or a tool's own argument
504 after ``--``, which the steps never pass through. The post-edit
505 hook, which judges nothing, may name a file already deleted.
506 """
507 import os
509 root = workspace_root()
510 if root is None:510 ↛ 511line 510 didn't jump to line 511 because the condition on line 510 was never true
511 fail("no workspace: no workshop.toml above the working directory")
512 if fix and os.environ.get("CI"):512 ↛ 513line 512 didn't jump to line 513 because the condition on line 512 was never true
513 fail(
514 "check --fix inside CI: the runner's checkout is judged, never rewritten."
515 f" Run `{footman.prog()} check --fix` locally and push the result."
516 )
517 if judge:
518 unknown = [path for path in paths if not _in_workspace(root, path)]
519 if unknown:
520 fail(
521 "not a file or directory in the workspace:"
522 f" {', '.join(unknown)}. Name files or directories; a step's"
523 " own verb hands its tool the words after --:"
524 f" `{footman.prog()} <phase>.<step> <paths> -- <words>`."
525 )
526 files = named_files(root, paths)
527 if not files:
528 print(" nothing to check: no file under the named paths")
529 return
530 from livery.workshop._packages import workspace_suite
531 from livery.workshop._provenance import unit_of
533 packages = _packages()
534 holders = {unit_of(root, packages, name)[0] for name in files}
535 # The packages holding a named file, and the workspace's tests unit
536 # when a root file is named; the unit of a root without tests is no
537 # package, and joins no subset.
538 subset = [package for package in packages if package in holders]
539 suite = workspace_suite(root)
540 if suite is not None and suite in holders:540 ↛ 541line 540 didn't jump to line 541 because the condition on line 540 was never true
541 subset.append(suite)
542 ctx = _context(
543 subset=tuple(subset),
544 fix=fix,
545 files=files,
546 safe=safe,
547 point=point,
548 shard=shard,
549 arguments=arguments,
550 )
551 walk(ctx, judge=judge, only=only, inputs=inputs)
555 names: tuple[str, ...],
556 paths: tuple[str, ...] = (),
557 *,
558 fix: bool = False,
559 safe_fix: bool = False,
560 point: str = "",
561 shard: str = "",
562 arguments: tuple[str, ...] = (),
563) -> None:
564 """Run the steps *names* through the walk: a generated verb's body.
566 Over the named paths, or the whole workspace; nothing is recorded
567 as proved, since a part of the gate ran. *arguments*, the words
568 after ``--`` on a step's own verb, reach that step's tool. *shard*
569 is the ``--shard`` flag's text, read as `check` reads it. The
570 phases take the verb's inputs
571 ([livery.workshop._quality.VERB_INPUTS][]), not the gate's.
572 """
573 import os
575 _refuse_both(fix, safe_fix)
576 if (fix or safe_fix) and os.environ.get("CI"):
577 fail(
578 "a fix inside CI: the runner's checkout is judged, never rewritten."
579 f" Run `{footman.prog()} check --fix` locally and push the result."
580 )
581 chosen = _current_shard(shard)
582 only = frozenset(names)
583 if paths:
584 _check_files(
585 paths,
586 fix=fix or safe_fix,
587 safe=safe_fix,
588 point=point,
589 shard=chosen,
590 only=only,
591 arguments=arguments,
592 inputs=VERB_INPUTS,
593 )
594 return
595 context = _context(
596 fix=fix or safe_fix,
597 safe=safe_fix,
598 point=point,
599 shard=chosen,
600 arguments=arguments,
601 )
602 walk(context, only=only, inputs=VERB_INPUTS)
606 """Run the steps of *phase* over *packages* whole; nothing recorded as proved.
608 The gate's walk ([livery.workshop._quality.walk][]) narrowed to the
609 steps the extensions register for *phase*, and the steps they run
610 after, over the named packages alone, with the gate's inputs. A
611 package no step of the phase judges is skipped by the walk, and a
612 phase with no step runs nothing. An extension runs a phase this
613 way over packages the gate did not run it on. Inside CI the leg's
614 label names the shard the run is, as `check` reads it without the
615 flag.
616 """
617 names = tuple(
618 record.name
619 for record in _steps.steps_by_name().values()
620 if record.phase == phase
621 )
622 if not names:622 ↛ 623line 622 didn't jump to line 623 because the condition on line 622 was never true
623 return
624 walk(_context(subset=packages, shard=_current_shard()), only=frozenset(names))
628 """Run the gate's fixers over *paths*, judging nothing.
630 Every step whose claims reach a file fixes it, and a file no claim
631 reaches is left alone. *safe* keeps to the fixes a step marks
632 safe, which never remove code an edit in flight still needs; an
633 agent's post-edit hook runs it after each edit.
634 """
635 _check_files(paths, fix=True, safe=safe, point="", judge=False)
639 full: bool,
640 fix: bool,
641 base: str,
642 point: str = "",
643 safe: bool = False,
644 shard: Shard = ONE,
645) -> None:
646 """The gate itself; `check` opens the state store's snapshot around it."""
647 import os
649 if fix and os.environ.get("CI"):
650 fail(
651 "check --fix inside CI: the runner's checkout is judged,"
652 " never rewritten. A fix here would mutate a copy nobody"
653 " keeps and hide the finding from the verdict. Run"
654 f" `{footman.prog()} check --fix` locally and push the result."
655 )
656 from livery.workshop import _verified
657 from livery.workshop._ci_context import run_context
659 root_for_ci = workspace_root()
660 run = run_context()
661 if root_for_ci is not None and run is not None:
662 _leave_empty_share(root_for_ci, shard, attempt=run.attempt)
663 # The nightly point pays the whole gate: the record it would skip on
664 # was stamped by a run that selected the gate's tests, not its own,
665 # and a narrowed nightly would be no nightly. A dispatched run sets
666 # the record aside too: a person asked for this tree to be proved
667 # now, and a skip would answer with what an earlier run said. Its
668 # narrowing is the affected-legs decision's, which pays the full
669 # gate on every event but a pull request and says so.
670 nightly = _current_point() == "nightly"
671 dispatched = run is not None and run.event == "workflow_dispatch"
672 if nightly:672 ↛ 673line 672 didn't jump to line 673 because the condition on line 672 was never true
673 print(
674 " nightly: the whole gate, the verified record and the narrowing set aside"
675 )
676 elif dispatched:
677 print(" dispatched: the whole gate, the verified record set aside")
678 if not (nightly or dispatched) and root_for_ci is not None and run is not None:
679 from livery.git import remote_snapshot
681 with remote_snapshot(state_store(root_for_ci), fetch=("verified",)):
682 proved = verified_already(
683 root_for_ci, leg=run.leg, before=_shared_bound(root_for_ci, run)
684 )
685 if proved is not None:
686 _verified.write_marker(root_for_ci, _verified.VERIFIED, leg=run.leg)
687 return
688 ci_base = push_base = ""
689 if not nightly and root_for_ci is not None and run is not None:
690 ci_base = ci_affected_base(root_for_ci, run)
691 push_base = ci_push_base(root_for_ci, run)
692 if (ci_base or push_base) and root_for_ci is not None and run is not None:
693 from livery.workshop._influence import Changes
695 if ci_base:
696 print(f" affected-legs: the scoped gate against origin/{ci_base}")
697 else:
698 print(
699 " affected-legs: the scoped gate from the record's nearest proved tree"
700 )
701 step = _leg_plan(root_for_ci, ci_base or push_base, run)
702 subset = _affected(root_for_ci, step)
703 if subset is not None:703 ↛ 740line 703 didn't jump to line 740 because the condition on line 703 was always true
704 packages = _packages()
705 changes = Changes(root_for_ci, step.paths, step.base_tree)
706 if not subset:
707 # The same walk as a local run: the workspace steps whose
708 # inputs changed judge, and no package's steps run.
709 if _steps.workspace_selected(_context(subset=(), changes=changes)):709 ↛ 710line 709 didn't jump to line 710 because the condition on line 709 was never true
710 print(" no package affected: the workspace steps run")
711 _scoped_check(
712 (), fix=fix, point=point, shard=shard, changes=changes
713 )
714 else:
715 say_skipped(f"nothing affected: {_nothing_reason(step.paths)}")
716 _verified.write_marker(
717 root_for_ci,
718 _verified.NOTHING,
719 leg=run.leg,
720 base_tree=step.base_tree,
721 )
722 return
723 from livery.workshop._packages import WORKSPACE_TESTS
725 members = [p for p in subset if p.path != WORKSPACE_TESTS]
726 if len(members) < len(packages):726 ↛ 740line 726 didn't jump to line 740 because the condition on line 726 was always true
727 names = ", ".join(package.path for package in subset)
728 print(f" affected: {names}")
729 _verified.write_marker(
730 root_for_ci,
731 _verified.AFFECTED,
732 tuple(package.path for package in subset),
733 leg=run.leg,
734 base_tree=step.base_tree,
735 )
736 _scoped_check(
737 subset, fix=fix, point=point, shard=shard, changes=changes
738 )
739 return
740 proved_tree = ""
741 if run is None and root_for_ci is not None:
742 from livery.workshop import _gate_record
743 from livery.workshop._graph import affected_from_paths
745 if full:
746 proved_tree = git.working_tree_id(root_for_ci)
747 print(" full: everything runs, whatever the record proves")
748 else:
749 reflex = _gate_record.plan(root_for_ci, base=base)
750 proved_tree = reflex.tree
751 if reflex.mode == "proved":
752 say_skipped(
753 f"proved: tree {reflex.tree[:12]} is green already"
754 f" ({reflex.why}); nothing to run"
755 )
756 return
757 if reflex.mode == "step":
758 packages = _packages()
759 print(
760 f" since tree {reflex.base_tree[:12]}: {len(reflex.paths)}"
761 " path(s) changed"
762 )
763 scope = affected_from_paths(
764 root_for_ci,
765 packages,
766 reflex.paths,
767 before=reflex.base_tree,
768 )
769 if scope is not None:769 ↛ 843line 769 didn't jump to line 843 because the condition on line 769 was always true
770 from livery.workshop._influence import Changes
771 from livery.workshop._packages import WORKSPACE_TESTS
773 subset = scope.packages
774 members = [p for p in subset if p.path != WORKSPACE_TESTS]
775 changes = Changes(
776 root_for_ci, tuple(reflex.paths), reflex.base_tree
777 )
778 if not subset:
779 # No package's steps: the workspace steps whose
780 # inputs changed still judge what changed.
781 if not _steps.workspace_selected(781 ↛ 789line 781 didn't jump to line 789 because the condition on line 781 was always true
782 _context(subset=(), changes=changes)
783 ):
784 say_skipped(
785 "nothing affected: no file a step reads changed"
786 " since the proved tree"
787 )
788 else:
789 print(" no package affected: the workspace steps run")
790 _scoped_check(
791 (), fix=fix, safe=safe, shard=shard, changes=changes
792 )
793 _remember_local(
794 root_for_ci,
795 run,
796 tree=reflex.tree,
797 packages=(),
798 base_tree=reflex.base_tree,
799 shard=shard,
800 )
801 return
802 if len(members) < len(packages) or scope.tests:
803 names = ", ".join(package.path for package in subset)
804 print(f" affected: {names}")
805 for path, files in sorted(scope.tests.items()):805 ↛ 806line 805 didn't jump to line 806 because the loop on line 805 never started
806 print(
807 f" {path}: {len(files)} test file(s) changed and"
808 " nothing else; they run alone"
809 )
810 for path in scope.examples:810 ↛ 811line 810 didn't jump to line 811 because the loop on line 810 never started
811 print(
812 f" {path}: its examples changed and nothing else;"
813 " they run and no suite"
814 )
815 tree = reflex.tree
817 def measure_step() -> None:
818 nonlocal tree
819 tree = _rewritten_tree(root_for_ci, run, tree)
821 _scoped_check(
822 subset,
823 fix=fix,
824 tests=scope.tests,
825 examples=scope.examples,
826 between=measure_step,
827 point=point,
828 safe=safe,
829 shard=shard,
830 changes=changes,
831 )
832 _remember_local(
833 root_for_ci,
834 run,
835 tree=tree,
836 packages=tuple(package.path for package in subset),
837 base_tree=reflex.base_tree,
838 shard=shard,
839 )
840 return
841 print(" every package is affected: everything runs")
842 else:
843 print(" everything runs, and roots a new chain")
844 else:
845 print(f" full: {reflex.why}")
846 # The marker is a CI leg's fact for its metrics row and the stamp;
847 # a local run leaves none, since an untracked root file would read
848 # as a root change on the next affected gate.
849 if root_for_ci is not None and run is not None:
850 _verified.write_marker(root_for_ci, _verified.FULL, leg=run.leg)
852 # The whole gate is the registry's walk, the tree measured between
853 # the fixers and the judges so the row names what the judges read.
854 def measure_whole() -> None:
855 nonlocal proved_tree
856 proved_tree = _rewritten_tree(root_for_ci, run, proved_tree)
858 walk(_context(fix=fix, safe=safe, point=point, shard=shard), between=measure_whole)
859 _remember_local(root_for_ci, run, tree=proved_tree, packages=None, shard=shard)
863 """The working tree's id after the rewriters ran: the tree the judges read.
865 The plan measures the tree before a fix run rewrites files, and a
866 row naming that tree would leave the proved tree one rewrite
867 behind the commit that follows. Measured between the rewriters and
868 the judges, so an edit made while the judges run stays unproved.
869 Outside a local run there is no row, and *tree* stands as given.
870 """
871 if root is None or run is not None or not tree:871 ↛ 872line 871 didn't jump to line 872 because the condition on line 871 was never true
872 return tree
874 return git.working_tree_id(root)
878 root: Path | None,
879 run: RunContext | None,
880 *,
881 tree: str,
882 packages: tuple[str, ...] | None,
883 base_tree: str = "",
884 shard: Shard = ONE,
885) -> None:
886 """Record a green local gate on this machine's gate record; CI never writes it.
888 A sharded run ran a share of the gate, so it records nothing and
889 says so.
890 """
891 if root is None or run is not None or not tree:
892 return
893 if shard != ONE:
894 print(
895 f" shard {shard}: a share of the gate ran; the tree is not recorded"
896 " as proved"
897 )
898 return
899 from livery.workshop import _gate_record
901 print(
902 _gate_record.remember(root, tree=tree, packages=packages, base_tree=base_tree)
903 )
907 """The point this process runs at, as the job runner named it; gate outside CI."""
908 import os
910 from livery.workshop._ci_context import POINT_VARIABLE
912 return os.environ.get(POINT_VARIABLE, "gate")
916 """Leave the shard's record of an empty set, before the gate decides.
918 The gate job's fold proves a platform's shards from the record each
919 one leaves of what it partitioned, and the test step leaves that
920 record only when it runs. A shard whose gate skips on the verified
921 record, finds nothing affected, or reaches no suite leaves this one
922 instead: no item, no durations row, the checkout's time as the
923 bound, the same on every shard of the platform, so the fold folds
924 the platform's skipped shards into one skipped leg. The test step's
925 own record replaces it when the step runs. One shard of one leaves
926 none. *attempt* is the run's attempt, recorded as the test step
927 records it.
928 """
929 if shard == ONE:
930 return
931 leave_shard(
932 root,
933 shard=shard,
934 digest=files_digest(()),
935 items=(),
936 rows=(),
937 before=checkout_time(root),
938 attempt=attempt,
939 )
943 """The shard this run is: *given* when there is one, else the CI leg's.
945 *given* is the ``--shard`` flag's text, ``2of4``. Without it,
946 inside CI, the leg's label ends in the shard
947 ([livery.workshop.shard_of][]), and a label without one is one
948 shard of one; outside CI every run is one shard of one.
950 Raises:
951 Failed: When *given*, or the label's tail, spells no shard,
952 naming it.
953 """
954 from livery.workshop._ci_context import LEG_VARIABLE, run_context
956 if given:
957 try:
958 return Shard.parse(given)
959 except ValueError as error:
960 fail(str(error))
961 run = run_context()
962 if run is None:
963 return ONE
964 try:
965 return shard_of(run.leg)
966 except ValueError as error:
967 fail(f"{LEG_VARIABLE}={run.leg}: {error}")
971 """Print a skip, and put it on the timeline as an event.
973 Work left undone because something already proves it is the one thing
974 an account of a run must not show as merely fast: a gate that skipped
975 and a gate that flew look identical from outside. The printed line is
976 unchanged, so a log reads as it always did, and the mark is what makes
977 the picture honest about why a leg was quick.
979 Marks only inside a task, since that is where a timeline exists; a
980 plain call outside a run prints and nothing more.
981 """
982 print(f" {text}")
983 if footman.current().in_task:
984 footman.mark(f"skipped: {text}")
988 """Why nothing is affected: only prose and site files changed, or nothing."""
989 from livery.workshop._graph import is_prose, is_site
991 quiet = [path for path in changed if is_prose(path) or is_site(path)]
992 if changed and len(quiet) == len(changed):
993 return (
994 f"only prose and site files changed ({len(quiet)} file(s) under"
995 " notes/, markdown, the root docs/ tree, or zensical.toml); the gate"
996 " skips, the site build judges them"
997 )
998 return "the branch changes no files"
1002 subset: tuple[Package, ...],
1003 *,
1004 fix: bool = False,
1005 tests: Mapping[str, tuple[str, ...]] | None = None,
1006 examples: tuple[str, ...] = (),
1007 between: Callable[[], None] | None = None,
1008 point: str = "",
1009 safe: bool = False,
1010 shard: Shard = ONE,
1011 changes: Changes | None = None,
1012) -> None:
1013 """The gate over *subset* only: the registry's walk, narrowed.
1015 A workspace step with declared inputs judges what *changes*
1016 touched of them, and nothing when they touched none
1017 ([livery.workshop._steps.selected][]). *tests* names, per package
1018 path, the test files that stand for the package's suite in this
1019 run; *examples* the packages whose examples alone changed;
1020 *between* runs after the fixers under ``--fix``, as
1021 [livery.workshop._quality.walk][] says.
1022 """
1023 walk(
1024 _context(
1025 subset=subset,
1026 fix=fix,
1027 tests=tests,
1028 examples=examples,
1029 point=point,
1030 safe=safe,
1031 shard=shard,
1032 changes=changes,
1033 ),
1034 between=between,
1035 )
1039 """Who is accepting: the git identity, or the user name the shell has."""
1040 import os
1042 return git.config_get(root, "user.name") or os.environ.get("USER", "unknown")
1050 """Remove build artifacts and checker caches.
1052 A step's own cache directory, ``.workshop/.cache/<step>/``, goes
1053 whole; the build artifacts are named.
1054 """
1055 import shutil
1057 root = workspace_root()
1058 if root is None:
1059 return
1060 for name in ("dist", ".workshop/.cache"):
1061 shutil.rmtree(root / name, ignore_errors=True)