livery.workshop._quality¶
livery.workshop._quality ¶
The quality verbs: the gate and its parts, over the packages the contracts declare.
Each verb discovers the packages by their workshop.toml and runs
its phase's registered steps over them, each step over the packages
whose extensions it judges. check is the whole local gate; CI runs
the same command.
Functions:
| Name | Description |
|---|---|
walk |
Walk the registry: the one place the gate's order lives. |
affected_legs |
The contract's |
ci_affected_base |
The base branch a pull request's check leg narrows against, or empty. |
ci_push_base |
The branch a push's check leg stands on, for its plan; empty off a push. |
ci_changes |
What this CI run changed against the base it measures from; None for everything. |
verified_already |
The record's full row for this tree and leg, or |
check |
Run the gate: every registered step, the rewriters first under --fix. |
named_files |
paths as the files they name, root-relative: a file, or a directory's files. |
run_steps |
Run the steps names through the walk: a generated verb's body. |
run_phase_over |
Run the steps of phase over packages whole; nothing recorded as proved. |
fix_files |
Run the gate's fixers over paths, judging nothing. |
say_skipped |
Print a skip, and put it on the timeline as an event. |
caches_clear |
Remove build artifacts and checker caches. |
Attributes:
| Name | Type | Description |
|---|---|---|
GATE_INPUTS |
Mapping[str, Mapping[str, object]]
|
|
VERB_INPUTS |
Mapping[str, Mapping[str, object]]
|
|
AFFECTED_LEGS_KEY |
|
|
caches |
|
GATE_INPUTS
module-attribute
¶
GATE_INPUTS: Mapping[str, Mapping[str, object]] = {'build': {'isolated': False, 'configuration': 'instrumented'}}
VERB_INPUTS
module-attribute
¶
VERB_INPUTS: Mapping[str, Mapping[str, object]] = {'build': {'isolated': False, 'configuration': 'debug'}}
walk ¶
walk(ctx: PhaseContext, *, between: Callable[[], None] | None = None, judge: bool = True, only: frozenset[str] | None = None, inputs: Mapping[str, Mapping[str, object]] = GATE_INPUTS) -> None
Walk the registry: the one place the gate's order lives.
Every gate comes here, the whole one, CI's narrowed legs and a
machine's narrowed step alike, and runs the registry's steps
through the one walk (livery.workshop._phases.walk_steps). Each
step an extension registered is named first. Under --fix every
fixer that applies runs, one at a time in the rewriters' order,
before any judge reads the tree, and a step that rewrote is not
judged again in the run; then between runs, where a machine's
run measures the tree the judges read; then every judge runs in
one parallel block, the steps a judge runs after among them, and
one refusal is the verdict. A step whose claims reach no file in
scope is said and not started. On a shard other than the first, a
step that does not read the shard is left to the first shard and
said (livery.workshop._steps.on_this_shard). Without judge
the walk stops after the fixers, the post-edit hook's run. only
keeps the named steps alone, a generated verb's run. inputs are
the keys the walk gives each phase, the gate's own
(livery.workshop._quality.GATE_INPUTS) unless another engine
names its.
Source code in packages/workshop/src/livery/workshop/_quality.py
affected_legs ¶
The contract's [ci] affected-legs; false when undeclared.
The contract's judge holds the value to a boolean: the legs either narrow or they do not, and a stray string would read as true.
Source code in packages/workshop/src/livery/workshop/_quality.py
ci_affected_base ¶
ci_affected_base(root: Path, run: RunContext | None) -> str
The base branch a pull request's check leg narrows against, or empty.
Empty outside CI, when the contract does not declare
[ci] affected-legs, on any event but a pull request, and when
the payload names no base. A push's legs take their plan from
ci_push_base instead; the nightly and a dispatch pay the whole
gate, and say so, so a full leg is never a silent fallback.
Source code in packages/workshop/src/livery/workshop/_quality.py
ci_push_base ¶
ci_push_base(root: Path, run: RunContext | None) -> str
The branch a push's check leg stands on, for its plan; empty off a push.
Empty outside CI, without [ci] affected-legs, on any event but
a push, and on a push of a ref that is not a branch. A push's leg
measures from the nearest tree CI's record proves in HEAD's
history, the previous push's as a rule, and pays the whole gate
when the record proves none: on the pushed branch the merge base
is HEAD itself, so it is never the step's base (_leg_plan).
Source code in packages/workshop/src/livery/workshop/_quality.py
ci_changes ¶
What this CI run changed against the base it measures from; None for everything.
A pull request's run in a workspace that declares [ci]
affected-legs measures from its base branch: the paths changed
since the merge base with origin/<base>, committed or not, with
that merge base, so a widen reference can read a file as it
was. None at a desk, on any other event, without
affected-legs, and when git cannot answer; the run then judges
everything, and the line printed says why.
Source code in packages/workshop/src/livery/workshop/_quality.py
verified_already ¶
The record's full row for this tree and leg, or None to run the gate.
Prints the run that proved it when it does, and the reason when the record could not decide (an unreadable store, an entry of another shape); an absent entry or a narrowed scope is the ordinary case and stays quiet. A full entry that names other legs and not leg is named, and the gate runs: a row proves its tree for the platforms that ran it. With leg empty any full entry counts. Never skips on anything but a full entry for this exact tree. The row names the branch whose run proved it. With before, an entry stamped at or after it reads as absent, so the shards of a leg skip together or run together.
Source code in packages/workshop/src/livery/workshop/_quality.py
check ¶
check(*paths: str, full: Annotated[bool, doc('run everything, whatever the record proves')] = False, fix: Forward[bool] = False, safe_fix: Annotated[bool, doc('fix, removing no code: safe for an edit in flight')] = False, base: Annotated[str, doc("the branch the chain's root is taken from")] = 'main', point: Annotated[str, doc('run the tests of this CI point, nightly say')] = '', shard: Annotated[str, doc("run this shard's share of a sharded check leg: <i>of<n>, such as 2of4")] = '') -> None
Run the gate: every registered step, the rewriters first under --fix.
With paths, exactly those files are checked, or the files under
those directories: every step whose claims reach one of them runs
over them and no other, a step without claims does not run, and
nothing is recorded as proved. --safe-fix runs the fixers in
their in-flight mode, which removes no code, and refuses beside
--fix. --point hands a CI point to the test phase, which
selects that point's tests instead of the gate's.
--shard names the shard of a sharded check leg this run is,
2of4: a step that reads the shard runs its share, every other
step runs on the first shard alone, and the walk names each step
it leaves there. Inside CI the leg's label names the shard and the
flag is not needed. A sharded run records no tree as proved, since
a share of the gate ran. A shard outside the form, 0of2,
refuses naming it.
On a machine the gate is the reflex: it runs what the working
tree changed since the nearest tree this checkout's own green
gates proved, the packages that delta can influence (their
dependents' closure), and records the working tree as proved on
the local gate record (livery.workshop._gate_record). A tree
the record already proves runs nothing. The chain of records
rests on a full gate here or on CI's record of the merge base
with --base, so a fresh branch off main starts proved. A
change outside the packages configures every gate, so it runs
everything and roots a new chain; --full runs everything
whatever the record says. ty and pyrefly always check their
configured whole either way.
Inside CI, when the contract declares [ci] affected-legs, a
pull request's legs measure by the same rule from CI's own record,
read for the leg's own platform: from the proved tree nearest the
checkout's, an earlier push's merge among them, or from the merge
base with the pull request's base when the record proves none.
Without the key they run the whole workspace. The local record is
never read or written there.
--fix runs format and lint in their fix modes: each prints
what it found, rewrites what is mechanical, and still fails on
what is not. The two rewrite the same files, so under --fix
they run one after the other before the rest of the gate.
--fix refuses inside CI: a runner's checkout is judged,
never rewritten, because a fix there mutates a copy nobody
keeps and hides the finding from the verdict. Run the fix
locally and push the result.
On a machine the state store is read from what the last sync
or start fetched (livery.git.fetched_snapshot):
nothing the gate runs reaches origin, and a checkout the store was
never fetched into roots its chain on a full gate and says so.
Inside CI the legs read the store as the run's own snapshot.
Source code in packages/workshop/src/livery/workshop/_quality.py
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 | |
named_files ¶
paths as the files they name, root-relative: a file, or a directory's files.
A directory stands for the files git holds under it, tracked or untracked and not ignored, or every file under it outside a git checkout. A path outside the root, or naming nothing, is left out.
Source code in packages/workshop/src/livery/workshop/_quality.py
run_steps ¶
run_steps(names: tuple[str, ...], paths: tuple[str, ...] = (), *, fix: bool = False, safe_fix: bool = False, point: str = '', shard: str = '', arguments: tuple[str, ...] = ()) -> None
Run the steps names through the walk: a generated verb's body.
Over the named paths, or the whole workspace; nothing is recorded
as proved, since a part of the gate ran. arguments, the words
after -- on a step's own verb, reach that step's tool. shard
is the --shard flag's text, read as check reads it. The
phases take the verb's inputs
(livery.workshop._quality.VERB_INPUTS), not the gate's.
Source code in packages/workshop/src/livery/workshop/_quality.py
run_phase_over ¶
Run the steps of phase over packages whole; nothing recorded as proved.
The gate's walk (livery.workshop._quality.walk) narrowed to the
steps the extensions register for phase, and the steps they run
after, over the named packages alone, with the gate's inputs. A
package no step of the phase judges is skipped by the walk, and a
phase with no step runs nothing. An extension runs a phase this
way over packages the gate did not run it on. Inside CI the leg's
label names the shard the run is, as check reads it without the
flag.
Source code in packages/workshop/src/livery/workshop/_quality.py
fix_files ¶
Run the gate's fixers over paths, judging nothing.
Every step whose claims reach a file fixes it, and a file no claim reaches is left alone. safe keeps to the fixes a step marks safe, which never remove code an edit in flight still needs; an agent's post-edit hook runs it after each edit.
Source code in packages/workshop/src/livery/workshop/_quality.py
say_skipped ¶
say_skipped(text: str) -> None
Print a skip, and put it on the timeline as an event.
Work left undone because something already proves it is the one thing an account of a run must not show as merely fast: a gate that skipped and a gate that flew look identical from outside. The printed line is unchanged, so a log reads as it always did, and the mark is what makes the picture honest about why a leg was quick.
Marks only inside a task, since that is where a timeline exists; a plain call outside a run prints and nothing more.
Source code in packages/workshop/src/livery/workshop/_quality.py
caches_clear ¶
Remove build artifacts and checker caches.
A step's own cache directory, .workshop/.cache/<step>/, goes
whole; the build artifacts are named.