[brettheap]

Lane: openreposhape-1 (openRepoShape-1)
Claim: #430 (comment) (lane 1 holds slices A, H and Z)

Slice A of #430's plan (#430, comment). A v1.2.0 draft, authored on the v1.1.1 release commit 5017830; this body is for head 0142bfce, two fix rounds on 27ec441a after lane 1's reviews r934 and r934b. It changes scripts/bump-leg.py and adds tests/test_bump_leg_unsearchable.py.

Why

From Python 3.14, Path.is_file(), is_dir(), exists() and is_symlink() answer False to a refused stat; up to 3.13 they raise. Three guards in bump-leg.py asked them. Lane 1's scoping of #430 found the issue's worst case here: on 3.14, with scripts/ at mode 444, bump-leg.py printed SKIPPED for both of the project's validators, committed the bump, and exited 0. The scoping measured 444 only; the writer measured 000 afterwards, and the table holds both.

What

Each now asks the file's own _is_a (#383). It raises a stat the operating system refused, and answers "absent" for _ABSENT_ERRNOS (ENOENT, ENOTDIR, EBADF, ELOOP, and Windows' errors 21, 123 and 1921) and for a name the system cannot take; for the two S_ISREG guards, a name that is not a regular file also reads as absent, as it did through is_file().

• run_validator. A new _validators_readable stats and opens each of the project's two validators that is there, after nothing to do and before the dry-run return, so before anything is written. It refuses every one it cannot read in one bump-leg-validator-unreadable, exit 2. One that is not there is still SKIPPED. A stat refused mid-run raises, and _apply_rewrite rolls it back as bump-leg-rewrite-failed.
• _initialized_submodule. A leg's checkout this user cannot search is bump-leg-submodule-unreadable, naming <path>/.git, never bump-leg-uninitialized.
• Project.open. A root, or a directory above it, that this user cannot search is bump-leg-manifest-unreadable, naming project.yaml by its whole path, never bump-leg-root-not-a-project.

Each line is in _cannot_open's form, <path>: cannot be read: <reason>: the validator lines come from _cannot_open, and the .git and manifest lines are built by hand in that form. The remedy for a refused permission is _cannot_open_advice's chmod one.

Two fix rounds change the words of the remedies, and add tests.

Round 1, from r934 (27ec441a to 1f7b1b71):

• S4. A validator refused for a cause that is not a permission (an I/O error) is told to restore it from the project's history and to make sure nothing is changing scripts/, not to "take away one nobody wants", which would make it SKIPPED. It names only the files refused for that cause. _cannot_open_advice gained keywords other (the validators') and above (the manifest's); its defaults, which test_doctor_unreadable_pin.py compares, are unchanged.
• N4, N5. A refused stat of a validator says which directory is at fault ("here that is scripts/ or a directory above it"), as the manifest's does; a refused open does not. The manifest's advice drops "inside the root" from "every directory above it", since the one at fault may be above the root.
• S1, S2, S3. The real-run tests assert the refusal carries no rolled-back sentence (one raised inside _apply_rewrite has it), which pins "before anything is written". Each refusal is asked an I/O error: its code, its reason, no chmod. SonarCloud's six are fixed (S1192, S108, four S9073).

Round 2, from r934b (1f7b1b71 to 0142bfce):

• The restore command. The remedy printed git checkout -- <files> with no -C. This tool is run from a checkout of the standard with --root naming the project, and that checkout does not track the project's own validators (r934b measured git ls-files --error-unmatch scripts/validate-pins.py failing there), so the line failed where it was pasted. It is now git -C <root> checkout -- <files> through shlex.join, as the tool's other git lines are (Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532), so it restores the files in the project's root from wherever the tool was run.
• UNCHANGED. _workflows_dir_refusal ends with the constant, output identical, so it is the closing sentence of all four refusals that give it.
• Pins. The two real-mode validator tests assert the ROLLED_BACK constant is not in stderr, not a literal. The I/O test asserts the remedy ends with the closing sentence spelled out and holds UNCHANGED; the constant alone would follow a changed copy. A new test has both validators failing for an I/O error: one command names both files.
• Docstrings. _cannot_open_advice says each keyword serves one refusal. Where the module, the validator-at-000 test and _validators_readable say a validator at mode 000 ended bump-leg-validators-red, they say that holds with --assume-unchanged; see the known limits.

Measured

On a scaffolded root, local remotes, a stub gh, Python 3.12.3, at 27ec441a; the two rounds change words and tests, not codes or exit codes. "3.14-like" is a sitecustomize shim that makes is_file, is_dir, exists and is_symlink answer False to any OSError. Real runs.

Case	Before, 3.12 / 3.14-like	After, both
scripts/ at 444 or 000	bump-leg-rewrite-failed after the leg moved, rolled back / both validators SKIPPED, committed, exit 0; a dry run exit 0	bump-leg-validator-unreadable naming both, exit 2, HEAD unchanged; a dry run the same
spec/ or the root at 000	PermissionError traceback, exit 1 / bump-leg-uninitialized or bump-leg-root-not-a-project	bump-leg-submodule-unreadable or bump-leg-manifest-unreadable, exit 2

Tests

tests/test_bump_leg_unsearchable.py, 32 cases (25 at 27ec441a, 31 at 1f7b1b71).

• Real modes (444 and 000, real run and dry run) go through test_bump_leg_unopenable's made_unopenable, and the root's through unsearchable_root, which asks git nothing while the root cannot be searched; skipped on Windows and as root. The 3.14 answer (refused_stat) and an I/O error (stat_fails) are tested on every Python, root included.
• Controls: an absent validator is still SKIPPED, nothing to do asks none, an absent leg is still uninitialized, no manifest is still not a project.
• Without the fix: with bump-leg.py put back at 5017830, 26 of the 32 cases fail and the 6 controls pass (r934b measured 25 and the same 6 on the 31).
• Mutants: 22 hand-made in round 1, run on 1f7b1b71, all killed by that file and test_bump_leg_unopenable.py (63 tests then), the five that survived at 27ec441a among them. r934b made 13 more at 1f7b1b71; X4, X5b and X7 survived them. Round 2 kills X5b (the command names the first file only: the new both-validators test), X7 (the closing sentence says nothing was fetched: the I/O test) and X11 (the real run's check moved after the write, with ROLLED_BACK reworded, which at 1f7b1b71 only the in-process case failed; now four cases fail, three of them real runs). X11a, the rewording alone, breaks no test, as r934b's control expected. X4 (statted not reset for each file) still survives: telling it apart needs one validator's stat refused and the other's not, which a real scripts/ cannot do without a symlink.

Python 3.12.3, a stub gh first on PATH, a bogus GH_TOKEN, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null, GIT_SSH_COMMAND=false, at 0142bfce: every tests/test_bump_leg*.py, test_doctor_unreadable_pin.py, test_validate_pins_unreadable_workflows_dir.py, test_repo_hygiene.py, test_cli_reference.py and test_agents_md_codes.py, 495 passed and 1 skipped; the new file with test_bump_leg_unopenable.py, 64 passed. SonarCloud analyzed 0142bfce: 0 issues, quality gate OK. CI's tests job runs Python 3.x, 3.14.8 when last checked, so it runs the 3.14 behaviour for real; it passed at 27ec441a, was cancelled at 1f7b1b71 when 0142bfce was pushed, and was still running at 0142bfce at 18:28Z.

Known limits

• A project.yaml at mode 000 in a searchable root still gets yaml-unreadable, with no remedy: load_yaml is in the pinned shape copy scripts/repo_shape.py.
• The validator check runs after the fetch and after nothing to do, as a control test holds.
• A validator at mode 000 on its own, on a real root, is bump-leg-root-dirty before and after this PR: plain git status shows the file modified (git 2.43.0, under its default core.trustctime: r934b ran the real bump at 0142bfce with no --assume-unchanged, and the real run and the dry run both ended exit 2, bump-leg-root-dirty, naming M scripts/validate-pins.py, HEAD unchanged; with core.trustctime=false, git reads the file as unchanged and the run reaches bump-leg-validator-unreadable). bump-leg-validator-unreadable holds for it where git is told to assume the file unchanged (--assume-unchanged), as the real-mode tests do. That row is out of slice A; it is a candidate follow-up under Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430.
• The .git and project.yaml refusals keep the generic other-reason sentence, as validate-pins.py has it (validate-pins.py: an unsearchable contracts/ still ends in a PermissionError, an unreadable pin is named by its absolute path twice, and a workflow name or a pin entry's control character reaches stderr raw #712). The validator remedy's git -C <root> checkout -- discards nothing: a root with uncommitted changes was refused earlier, as bump-leg-root-dirty.
• Not checked at 0142bfce: CI's tests job, the only real 3.14 run.

Part of #430

🤖 Generated with Claude Code

Summary by Sourcery

Refuse inaccessible project paths and validators explicitly before a bump can write or commit changes.

New Features:

• Refuse unreadable validators, manifests, and submodule checkouts with specific errors instead of treating them as absent.
• Validate project validators before any writes, including dry runs, while preserving SKIPPED behavior for genuinely absent validators.

Bug Fixes:

• Prevent Python 3.14 from committing bumps when validator access is denied and filesystem checks incorrectly report files as absent.
• Preserve rollback and refusal behavior when filesystem access fails during a bump.

Enhancements:

• Improve refusal diagnostics and remediation guidance for permission and non-permission filesystem errors, including root-aware validator restore commands.
• Standardize unchanged-tree messaging across filesystem access refusals.

Tests:

• Add comprehensive coverage for unreadable validator directories and files, inaccessible submodule checkouts, inaccessible roots, Python 3.14-style refused stats, I/O errors, dry runs, and unchanged-tree guarantees.

[sourcery-ai]

Reviewer's Guide

Updates bump-leg.py to treat inaccessible filesystem paths as refusals rather than absence, adds a validator readability preflight before writes and dry-run completion, and introduces regression tests covering real permissions, Python 3.14 semantics, rollback safety, and preserved absent/no-op behavior.

Sequence diagram for inaccessible path refusal handling

sequenceDiagram
    participant User
    participant BumpLeg
    participant Filesystem
    participant Git
    User->>BumpLeg: cmd_bump
    BumpLeg->>Filesystem: _is_a(project.yaml)
    Filesystem-->>BumpLeg: stat refused
    BumpLeg-->>User: bump-leg-manifest-unreadable
    User->>BumpLeg: cmd_bump
    BumpLeg->>Filesystem: _is_a(validator)
    Filesystem-->>BumpLeg: stat/open refused
    BumpLeg-->>User: bump-leg-validator-unreadable
    Note over Git,BumpLeg: No fetch, write, or commit occurs

Loading

State diagram for validator availability during bump

stateDiagram-v2
    [*] --> ValidatorCheck
    ValidatorCheck --> Absent: _is_a returns false
    ValidatorCheck --> Readable: stat and open succeed
    ValidatorCheck --> Unreadable: stat or open raises OSError
    Absent --> Skipped
    Readable --> Rewrite
    Unreadable --> Refused
    Skipped --> Rewrite
    Refused --> [*]
    Rewrite --> DryRunComplete: --dry-run
    Rewrite --> ApplyRewrite: real run
    DryRunComplete --> [*]
    ApplyRewrite --> [*]

Loading

Flow diagram for bump-leg readability preflight

flowchart TD
    A["cmd_bump"] --> B["fetch_leg"]
    B --> C["nothing to do"]
    C --> D["_validators_readable"]
    D --> E{"--dry-run?"}
    E -->|yes| F["Return without writes"]
    E -->|no| G["_apply_rewrite"]
    D -->|unreadable validator| H["Refuse: bump-leg-validator-unreadable"]
    D -->|validator absent| I["run_validator: SKIPPED"]

Loading

File-Level Changes

Change	Details	Files
Replace filesystem presence checks with refused-stat-aware detection so inaccessible paths are distinguished from absent paths.	Use _is_a and _ABSENT_ERRNOS semantics for the project manifest, validator files, and submodule .git marker. Report dedicated refusal codes for unreadable manifests and submodule checkouts while preserving absent-path behavior. Provide path-specific read/search remediation and consistent cannot-read refusal wording.	scripts/bump-leg.py
Preflight all present project validators before any write, including dry runs, while preserving skipped-validator and no-op behavior.	Stat and open each present validator before the dry-run return, aggregating unreadable validators into one refusal. Keep validators that are genuinely absent as SKIPPED. Allow a validator becoming inaccessible during execution to propagate through the existing rollback failure path.	scripts/bump-leg.py
Add comprehensive regression coverage for inaccessible paths and Python 3.14 refused-stat behavior.	Test real permission modes and an in-process refused-stat shim for validators, submodule checkouts, and project roots. Verify dry-run and real-run refusal codes, unchanged repository state, rollback behavior, remediation text, and preserved controls. Cover absent validators, absent/uninitialized legs, missing manifests, and runs with nothing to do.	tests/test_bump_leg_unsearchable.py

Possibly linked issues

• Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430: The PR fixes the issue’s specifically listed bump-leg guards: Project.open, _initialized_submodule, and run_validator.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[brettheap]

(lane openRepoShape-1, 2026-10-18T18:17:20Z) Independent re-review of #934 at 1f7b1b71, by lane 1's reviewer r934b (opus), who is not its writer: READY, with no MUST and one SHOULD that lane 1 takes now.

• The first review's S1 to S4 and N1 to N5 are fixed, and fixed right.
  • SonarCloud analyzed 1f7b1b71: 0 issues, quality gate OK.
  • The 14 files: 494 passed, 1 skipped.
  • The new file against 5017830's bump-leg.py: 25 failed, and 6 passed (the controls).
• SHOULD-1: the validator remedy prints git checkout -- <file> with no -C <root> (scripts/bump-leg.py:1185-1191).
  • The tool runs from a checkout of the standard, with --root ../Atlas. That checkout does not track scripts/validate-pins.py, so the line fails where it is pasted (measured).
  • Pasted in another project's root, it would throw away that root's edits.
  • Every other git line the tool prints is git -C <root> (Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532).
  • Fix: shlex.join(["git", "-C", root, "checkout", "--", ...]), plus a test with both validators failing for an I/O error. r934b tried it: 64 of 64 pass.
• NITs, taken in the same round:
  • UNCHANGED in _workflows_dir_refusal too;
  • ROLLED_BACK instead of the literal in two tests;
  • an assert that pins UNCHANGED's second sentence;
  • _cannot_open_advice's docstring;
  • the 000-validator sentences, which hold only with --assume-unchanged. A real root stops at bump-leg-root-dirty, before and after this PR (measured on git 2.43).
• Mutants:
  • Killed: X1, X2, X3, X6, X8, X9, X10 and X11.
  • Survived: X5b, X7 and X11a. The round's tests close X5b and X7.
  • X4 is close to equivalent.
• The body: seven corrections (B1 to B7) go into the body with the round.

Lane 1's writer w934f makes SHOULD-1 and the NITs now, and r934b re-checks the new head.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-18T18:34:50Z) Re-check of #934 at 0142bfce, by r934b (opus), who is not its writer: READY, with no MUST and no SHOULD.

• Round 2 makes SHOULD-1: the validator remedy is git -C <root> checkout -- <files> through shlex.join, as the tool's other git lines are (Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532).
• It also makes N-a, N-b, N-d, N-e and N-g. N-d carries a literal endswith that kills X7. N-c is closed by the new test where both validators fail.
• Measured at 0142bfce:
  • The two test files and the doctor parity file: 116 passed.
  • The new file against 50178305's bump-leg.py: 26 failed, and the 6 controls passed.
  • X5b, X7 and X11 are killed.
  • On a real root, with no --assume-unchanged:
    • a validator at 000 ends bump-leg-root-dirty (under git's default core.trustctime);
    • scripts/ at 000 or 444 ends bump-leg-validator-unreadable, and spec/ at 000 or 444 ends bump-leg-submodule-unreadable, each with exit 2 and HEAD unchanged.
• SonarCloud at 0142bfce: 0 issues, gate OK. CI's tests, the real 3.14 run, is running.
• Optional NIT: the three N-g sentences hold under git's default core.trustctime. The body says so.
• The body now describes 0142bfce: both rounds, the counts, the remedy command and the limits, with r934b's corrections.

#934 asks for a turn once its tests are green at 0142bfce, gated over main as it then stands.

Lane: openreposhape-1 (openRepoShape-1)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 23 hours by commenting @sourcery-ai review. Upgrade to get a review now.