Repository navigation
Split pr_review.py's Check and Round Readers Into Leaf Modules - #3462
Conversation
The gate held its own readers beside its plumbing and writes, so every fix grew one file. The pure readers now live in two leaf modules that take a fetched payload and make no call of their own: - pr_review_checks.py reads the head's CI rollup, and renders the digest's check lines from a table keyed by stuck shape. - pr_review_rounds.py reads the review rounds: coverage, refusals, quota history, threads, and the local attestation. The code moved verbatim apart from check_lines, whose output is byte-identical to the chain it replaces. Every name a test patches stays defined in pr_review.py. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The parse-once spies counted only calls from the gate, so a second parse inside the checks module would have passed. They now count both bindings. The whole-source write and suppression guards read the two reader modules too, and a new case holds their imports to the standard library and the reviewer adapter. The size ceilings sit just above each module's current length, so growth reaches a redesign prompt sooner. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The import guard read each reader's own import statements and asserted no floor, so a collector matching nothing passed, and the adapter's imports went unchecked. It now asserts one known import per module and asks a fresh interpreter, through import_delta, whether importing the module loads the gate, the transport, or subprocess. The node-id literal scan reads the reader modules as well, since the thread readers moved there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
A recorded local strict-review pass covers head |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
There was a problem hiding this comment.
🟡 Changes recommended
The import-boundary test can pass vacuously unless it asserts that the probe starts with no watched modules already loaded.
1 open issue
What changed in this PR
This pull request splits pr_review.py’s check and review-round readers into dedicated leaf modules while preserving the gate’s network, write, and command-line responsibilities.
Changes:
- Adds
pr_review_checks.pyfor check normalization, stuck-state evaluation, and digest check rendering. - Adds
pr_review_rounds.pyfor review-round, coverage, thread, quota, request, and attestation readers. - Updates tests, size ceilings, import-boundary checks, import probing, and documentation.
- Leaves one unresolved test issue: the import-boundary test does not assert that the probe starts with an empty set of watched modules.
| File | Summary |
|---|---|
tests/test_pr_review.py |
Retargets reader tests and adds parsing and import-boundary coverage; its import probe should reject a non-empty initial module set. |
tests/test_pr_review_size.py |
Adds independent size ceilings for the gate and reader modules. |
tests/import_probe.py |
Generalizes fresh-interpreter import probing to configurable watched modules. |
scripts/README.md |
Documents the separation between the gate and reader modules. |
scripts/pr_review.py |
Retains gate-level orchestration and delegates check and review-round processing to the new readers. |
scripts/pr_review_rounds.py |
Provides pure readers for review rounds, coverage, threads, quotas, requests, and attestations. |
scripts/pr_review_checks.py |
Provides pure check readers, state evaluation, constants, and digest check rendering. |
Review effort: Lite
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## develop #3462 +/- ##
==========================================
Coverage ? 80.90%
==========================================
Files ? 25
Lines ? 8850
Branches ? 0
==========================================
Hits ? 7160
Misses ? 1690
Partials ? 0
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
A watched module loaded at interpreter start sat in both lists, so the before-and-after comparison passed without testing that module. Both lists are now asserted empty. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
A recorded local strict-review pass covers head |
## Summary
A pull request into a non-default branch is "held": an attested local
pass covers its head, and `pr_review.py wait` polls the head's checks
instead of a Copilot round. Run right after a push, that poll exited `0`
while CI was still running. A job behind `needs:` enters the rollup only
once its dependencies finish, so the merge read `CLEAN` and every
registered check was green while most of a run's jobs had not been
created yet. A caller trusting the exit judged the pull request ready.
The held poll now holds while any workflow run on the head has not
completed:
- `runs_open(pr)` in `scripts/pr_review_checks.py` names every workflow
run whose suite is not `COMPLETED`. It reads the head commit's own
suites and each rollup check run's suite, so a fresh head's run counts
before most of its jobs exist. A suite with no workflow run, such as
another app's that never reports, holds nothing.
- `held_checks_open` reads its conditions in this order:
- a pull request no longer open releases
- a merge reading `UNKNOWN` holds
- a `BLOCKED` merge with a required check stuck in a shape waiting does
not clear ends the poll at `44`
- an open run holds
- only then does a `CLEAN`, `UNSTABLE`, or `HAS_HOOKS` merge release
- A check run `WAITING` past `--check-grace` is its own `GATED` shape.
It gets a `CHECK WAITING ON ITS ENVIRONMENT` line saying to approve the
job or let its timer pass, since a re-run meets the same rule. `WAITING`
leaves `NOT_STARTED`.
- Where `workflowRun` is unreadable, an Actions suite stands in, named
`suite <id>`, through `unkeyed_actions_suite`, which `check_nodes`
shares. The head's suites query now selects `app{ slug }` for this.
- The `status=CHECKS_PENDING` line names the open runs. The `wait` help
and the `scripts/README.md` held-wait and exit-44 paragraphs describe
the new reading, in the code's order.
Closes on promotion: #3451
## Decisions
- **Every open run holds, with no exception.** Earlier revisions
released a run waiting on an environment, then one with a starved job.
Review showed each release reopened the early exit `0`: a job pending
behind a concurrency group, a busy runner pool, or a dependent not yet
registered. The cost is that a run waiting on an approval that never
comes, or on a job no runner takes, polls to the timeout. It then exits
`30`, with the digest's `GATED` or `CHECK NOT PICKED UP` line naming
what holds it.
- **A gated or long-running required check does not end a `BLOCKED` poll
at `44`.** A timer clears by itself and an approval may land, so on a
held head these hold to `30`. On the Copilot path a required gated check
still exits `44`, as a long-running one already did.
- **A required starved check under `BLOCKED` still exits `44` at once,**
as before.
- **No shared walker with `check_nodes`.** Its suite walk is threaded
through per-node normalization, so `runs_open` reads the suites itself.
The one condition the two share, whether a suite is an Actions suite
left unkeyed, is one predicate.
- **A job-less Actions suite may hold in degraded mode.** With
`workflowRun` unreadable, an unfinished Actions suite holds even when it
has no job yet, since right after a push it looks the same as one that
never gets a job. I measured the check suites on the 8 most recent pull
request heads here: every Actions suite carried jobs, and none sat
unfinished. The suites left queued with no jobs belonged to other apps
(`azure-pipelines`, `claude`, `coderabbitai`), which the predicate
excludes and a test pins.
## Remaining Local-Review Findings
Each push had recorded frontier-tier passes, and every `introduced`
finding they raised is fixed in the commits above, apart from these:
- `introduced`, fixed in `8acf0511`: the `wait` help's exit-30 line read
as a complete list of holds. It now points to the holds
`status=CHECKS_PENDING` names.
- `introduced`, deferred to #3471: the exit-0 help's completed-runs
clause now names coverage, the condition the code reads (`3545ba46`).
One path still falls outside it: when the rollup's commit is not the
head, `wait` deliberately exits `0` with `CHECKS UNREADABLE`, and no run
is read. That predates this change and a test pins it, but the help's
new clause now overclaims there. It joins #3471, which tracks exit `0`
where the required checks were never read.
- `pre-existing`: the help's claim that exit `0` means the head's
required checks settled is false under a `DIRTY` or `BEHIND` merge whose
required checks never ran. GitHub runs no `pull_request` workflow on a
conflicted pull request, and `held_checks_open` holds an unregistered
required context only under `BLOCKED`. These paths predate this change,
so they are left to an issue of their own.
- `introduced`, conditional: the degraded-mode decision above. If GitHub
ever leaves a job-less Actions suite queued on a head, the held wait
would poll to `30` in that mode alone. The measurement above found none.
- `style`: one help string and two help-text lines are wrapped short.
Declined, since no gate reads them and the file already carries longer
lines.
- `pre-existing`: a head read before any check suite exists, on a base
requiring no check, can still exit `0` under `CLEAN`. Nothing on the
head exists yet for any reader to see. Every develop ruleset in this
fleet requires the aggregator, so there the merge reads `BLOCKED` and
`required_unmet` holds.
- `pre-existing`: sentences over 25 words that this change only
rewrapped or left in place: three at `scripts/README.md` line 233,
`scripts/pr_review.py` lines 120 and 123, and the `49 =` help sentence.
## Verification
- `python -m unittest discover -s tests` (under `uvx --with-requirements
tests/requirements.txt`): 2,940 tests OK, 7 skipped, at `e4295145`. The
commits after it change only the `wait` help text, and the
`test_pr_review` and `test_cli_usage` suites pass on each.
- Each rule was mutation-tested, and dropping it fails a named test:
- the run hold, and its place ahead of `CLEAN`
- the closed-PR release
- the stuck-required release ahead of the hold
- the gated exemption from `44`
- the `COMPLETED` skip
- the no-workflow-run exclusion
- the rollup-suite read
- the Actions fallback for a rollup suite, for a job-less head suite,
and its other-app exclusion
- the `GATED` shape
- On a live pull request, #3462, a wait using an earlier revision of
this change (`f6837bd9`) held for 781 seconds until every run on the
head completed, then exited `0`. The same wait without it had returned
while two checks were still running.
- The extended suites query was read live with `status` against this
repository.
- `ruff check`, `ruff format --check`, `mypy .`, and `prose_lint.py
--diff`: clean.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…nd Nine Fixes to Main (#3472) ## Summary Promotes the pull requests merged into develop since release 2.0.1166. - [#3444](#3444): keeps untracked files out of the pre-commit snippet's prose gate. - [#3446](#3446): exempts the BuildKit `check=` parser directive in the prose gate. - [#3448](#3448): compares intent staleness against the hub's own copy and names the moved canonical. - [#3450](#3450): says only the prose gate is diff-scoped in the commit hook. - [#3453](#3453): reclassifies HolidayLights as an operational config repository in the registry. - [#3455](#3455): classifies the remaining subprocess failures by status rather than by prose. - [#3464](#3464): splits the semicolon series in WORKFLOW.md's filesystem output-seam bullet. - [#3466](#3466): audits a caller's `workflow-model` input against the registry. - [#3469](#3469): emits one snapshot shape from the skills report's cannot-read paths. - [#3462](#3462): splits `pr_review.py`'s pure check and round readers into the leaf modules `pr_review_checks.py` and `pr_review_rounds.py`. - [#3470](#3470): holds a covered held `wait` while any workflow run on the head has not completed. - [#3473](#3473): answers this promotion's review. The `wait` help and `scripts/README.md` now say what a held head's exit `0` does not prove: a `CHECKS UNREADABLE` payload, the conditions the unregistered-required-check hold reads, and the reach of the completed-run read. The exit code itself stays for #3471. Closes #3370 Closes #3372 Closes #3371 Closes #3369 Closes #3378 Closes #3454 Closes #3332 Closes #1759 Closes #3451 ## Constituent coverage Each change this promotion carries had coverage on its own pull request into develop, at its merged head: | Pull request | Merged head | Coverage | | --- | --- | --- | | [#3444](#3444) | `a61d1e2a` | attested local pass at the merged head, base `develop` | | [#3446](#3446) | `0a0efea1` | attested local pass at the merged head, base `develop` | | [#3448](#3448) | `c2c71ea7` | attested local pass at the merged head, base `develop` | | [#3450](#3450) | `4ec37c34` | attested local pass at the merged head, base `develop` | | [#3453](#3453) | `f20a543c` | a Copilot round on the merged head, its one changed file, no open findings | | [#3455](#3455) | `85f0ce60` | attested local pass at the merged head, base `develop` | | [#3464](#3464) | `fcd48e2d` | attested local pass at the merged head, base `develop` | | [#3466](#3466) | `3426a19c` | attested local pass at the merged head, base `develop` | | [#3469](#3469) | `ea4b0bb7` | attested local pass at the merged head, base `develop` | | [#3462](#3462) | `236eceab` | attested local pass at the merged head, base `develop` | | [#3470](#3470) | `3545ba46` | attested local pass at the merged head, base `develop` | | [#3473](#3473) | `46010530` | attested local pass at the merged head, base `develop`, and a Copilot table on an earlier head naming exactly the changed files | 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Summary
scripts/pr_review.pysat at 2,999 lines against its 3,000-line ceiling, so the #3451 fix had no room. The concern isn't the number. Each fix added a few lines to one file until it needed a full refactor. This change splits the file along the two kinds of reading the gate does, rather than trimming it to fit:scripts/pr_review_checks.pyreads the head's CI rollup. It holdscheck_nodes,check_shape, the stuck and settling readers,held_checks_open,required_unmet, the check constants (CHECK_GRACE,CHECK_STALL,CHECKS_WINDOW), and the digest's check lines.scripts/pr_review_rounds.pyreads the review rounds. It holds coverage and the file table, refusals and quota history, request state, threads and finding matching, the local attestation and its hold, and the reviewer-login vocabulary.scripts/pr_review.pykeeps the GitHub calls,digest, the verdict, the writes, andmain. It is now 2,105 lines.Design
The cut follows purity. Both new modules are leaves. Each reads a payload the gate already fetched, makes no network or subprocess call, and never imports
pr_review. Importing the gate from a module it imports would load a second copy whenever the gate runs as__main__. A leaf can also be tested without a mock. The rule that picks what moved: every function that does not, even indirectly, call the network, a subprocess,print, ortime.livenessis the one exception, since a test spies on it through the gate.Patched names stay in the gate. Every name a test patches (
gh_graphql,gh_rest,gql,_git,digest, and the rest) stays defined inpr_review.py. A patch on a name the moved code calls through its own module would silently stop applying, and a test meant to block a realghcall would let one through. The tests now call each reader in the module that defines it. The parse-once spies count both bindings ofcheck_nodes.Data instead of a branch chain.
digest's if/elif chain over stuck shapes is now theSTUCK_LINEStable besidecheck_shape, rendered bycheck_lines. A new shape is one entry in the module that defines shapes. Its output is byte-identical to the chain it replaces. I compared both versions over constructed payloads covering every shape, a superseded failure, an unreadable rollup, missing workflow keys, a truncated window, and an age-unknown stamp.What did not move, and why. A survey of the rest found where the gate keeps growing, and each is filed as its own issue rather than mixed into a move:
digestis about 300 lines of string concatenation. It can become a pure renderer behind a thin shell, with its header built from an ordered field list.mainholds the wholewaitbody and about seven hand-written flag-ownership checks, which a table can carry.pr_review.py cleanupalready loads a second copy of the gate throughpr_cleanup.py, the hazard the leaf rule guards against.These all edit
pr_review.py, so they land one at a time.Ceilings as tripwires, not targets. The size test now lists each module with modest headroom over its current length: 2,200 for the gate, 450 for checks, and 700 for rounds. Its docstring says a ceiling reached is a prompt to redesign along the module's boundaries, never to raise it. New guards keep the boundary true:
import_delta, whether importing the module loads the gate, the transport, orsubprocess.The
commentslabel. Most comment lines in the two new files moved verbatim. These are newly written:STUCK_LINEScommentcheck_linesdocstringThis unblocks #3451, whose fix lands on top in its own pull request.
Remaining Local-Review Findings
pre-existing: eight sentences over 25 words, all moved verbatim or older text on a changed line:scripts/README.mdlines 9 and 190,scripts/pr_review.pyline 16,scripts/pr_review_checks.pylines 88 and 94, andscripts/pr_review_rounds.pylines 367, 553, and 615.introduced, raised by the third pass after the edit budget ran out:tests/test_pr_review.pytest_the_readers_import_nothing_that_reaches_outcomparesbeforewithafterand never asserts thatbeforeis empty. A watched module already loaded at interpreter start would therefore pass vacuously. Onlysubprocesscould be, and neither CI leg loads it today. The fix isself.assertEqual([], before), which this pull request's review loop will dispose of.Verification
python -m unittest discover -s tests(underuvx --with-requirements tests/requirements.txt): 2,901 tests OK, 7 skipped, on the head.digestoutput was compared byte for byte, old against new, over the constructed payloads above.check_nodesparse inside the checks moduleimport subprocessin the rounds moduleimport gh_graphqlin the Copilot adapter, caught through the rounds moduleruff check,ruff format --check,mypy .,repo_gate.py --check eol, andprose_lint.py --diffwith--allow-comments: clean.local-strict-review: three recorded frontier-tier passes. The first raised five findings and the second three, all fixed. The edit budget then ran out, and anything the third raised is listed above.🤖 Generated with Claude Code