[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #276 (comment)

What and why

shape-doctor.py's legs row and its members row (a family holder) printed python3 <root>/scripts/bootstrap.py --root <root> as their NEXT without asking whether the root has the file, and without asking whether running it changes the row.

• A root that lost the file (the shape currency row names the same file copy-missing) pasted can't open file, exit 2.
• A root that kept it fared no better for the row's first problem: bootstrap never initialises a mount (it prints NOT INITIALIZED and stops) and never moves an existing branch whose tip is not the pin. For an empty mount, and for a leg committed past its pin on its tracking branch, the re-run doctor reported the same finding.

AGENTS.md tells an agent to run the NEXT a row names and not to improvise, so an agent holding such a row had no sanctioned move.

Now the NEXT is chosen by what is wrong, and the first kind wins:

• A leg or member a checkout cures (an empty mount, or a HEAD that is not the pin where the gitlink the root or holder records IS the pin): git -C <root> submodule update --init --recursive --checkout -- <those paths>, from one new helper, submodule_update_next. It needs no script and no PYTHONPATH.
• What no checkout cures (no gitlink recorded for the leg or member, a gitlink that is not the pin, no 40-hex pin, a mount git cannot read a HEAD in): the lockstep gate, validate-pins.py for a project and validate-family.py for a holder, built with validator_for and validator_command exactly as the pins and family rows build theirs, from the same two constants (PINS_GATE, FAMILY_GATE). When neither copy is readable the row prints no command.
• A holder's own scripts/bootstrap.py stays the members NEXT when it can run (it and the repo_shape.py it imports are both there), because it carries the credential rewrite a private member needs. Without them the members row gets the git line.
• The check_legs docstring said both problems were ones make bootstrap answers. It now says what is true.

Rulings (plan R276-1 to R276-5, as adopted and amended)

• R276-1, with the coordinator's amendment. The git line moves HEAD, so a commit made on a detached HEAD is left only in the leg's reflog (bootstrap's own checkout <branch> does the same). The explanation says so in plain words, names git -C <leg> branch NAME as the way to keep it first, and says it only for a leg whose HEAD is detached off its pin. A commit on a branch stays on that branch and is not mentioned.
• R276-2, the case the plan left unprobed (populated, but git cannot read a HEAD). Probed: git submodule update exits 128 for a missing gitdir, a corrupt HEAD, an unborn HEAD and an orphan branch with no commit, and the row does not change. So it is the lockstep gate (b), with the reason in a comment. A populated mount with no .git of its own is read the same way, because head_of walks up and answers with the root's HEAD.
• R276-3. As the plan says, and a member routes on the holder's gitlink the way a leg does. A member whose gitlink is absent or is not its pin.commit gets the family gate.
• R276-4. New tail text has none of ;, ', a backtick or a parenthesis, and check_legs's docstring is corrected.
• R276-5. validator_for's arity is untouched.

Decisions the brief left open: the "own bootstrap can run" test needs repo_shape.py as well as bootstrap.py; neither validator readable means no NEXT; the members row applies the legs row's unreadable-HEAD rule.

Fix round (review of c30bfb2)

• SHOULD-1, members and the holder's gitlink. members_verdict now asks recorded_gitlink as check_legs does. A member the holder records no gitlink for (family row member-gitlink-absent), or whose gitlink is not its pin.commit (member-gitlink-mismatch), gets the family gate, with or without the holder's own bootstrap. Before, the git line exited 0 and changed nothing for a mismatch, and died on pathspec did not match for an absent gitlink. The "where the gitlink is" claim above is now true for members too.
• SHOULD-2, --checkout. git submodule update obeys a configured submodule.<name>.update: under merge or rebase the line wrote a merge or a rebased commit into the leg, and under none it skipped the mount, each with exit 0 and the row still red. The line now carries --checkout, which overrides the setting for the one command.
• N11, --init. A pasted test on a plain git clone (no submodule.active), where dropping --init leaves the row red. The recursive fixture clone sets submodule.active, so no other paste could see --init.
• N2, the make bootstrap sentence. It is printed only where the root has the script, the repo_shape.py it imports and a Makefile bootstrap target, and it now says what bootstrap does: it puts each leg on its tracking branch and leaves alone one whose branch is already ahead of the pin.
• N5, one definition. own_bootstrap (the two-file check, plus the Makefile target when asked), lockstep_next (the gate line and its sentence, for a leg and for a member) and PINS_GATE / FAMILY_GATE (the validator paths, also used by check_pins and check_family). The "run the doctor again" sentence is written once, in submodule_update_next.
• N10, wording. "Every line is asserted as text on every OS, in both quoting dialects" was too broad: that holds for the git line (test_the_line_is_spelled_for_the_readers_shell). The lockstep lines' PowerShell form is validator_command's own and is asserted in tests/test_shape_doctor.py.

Follow-ups, left as the review names them:

• N1: the reflog note is not printed when the holder's own bootstrap is the NEXT, for an empty mount whose kept gitdir has a detached commit, or for a commit stranded in a member's own leg by --recursive.
• N3: the lockstep sentence says a mount git cannot read a HEAD in is not cured by an update, which is false for a populated mount with no .git whose gitdir is kept.
• N4: for an unborn HEAD the gate prints pins ok and the row stays red.
• N6: nothing runs the PowerShell form of the git line (the three Windows-only skips are the existing precedent).
• N7: the no-' test holds only because the test roots need no quoting.
• N8: an empty mount whose .gitmodules entry is gone gets a line that exits 128.
• N9: "run the doctor again" is said only when another leg is lockstep, not when the same leg hides a second fact.

Tests and mutants

New tests/test_doctor_legs_members_next.py (62 tests), importing the fixtures from test_shape_doctor and reading the explanation through one helper. Each NEXT is pasted through sh -c from another directory exactly as printed, and the row is asked again: an empty mount, a plain clone, a commit on the tracking branch, a detached leg (with and without the keep line), a diverged leg under update = merge, rebase and none, scripts/bootstrap.py absent, repo_shape.py absent, a holder with and without its bootstrap, and the lockstep gate for the root's own copy and for the template. The reflog note is asserted present for a detached leg and member and absent everywhere else. The sh pastes are WINDOWS_SKIP; the git line is also asserted as text on every OS in both quoting dialects. tests/test_shape_doctor.py is edited at the three claims this makes false.

/usr/bin/python3 -m pytest tests/test_doctor_legs_members_next.py tests/test_shape_doctor.py -q at 4497def: 304 passed, 3 skipped (the three Windows-only PowerShell tests).

Mutants of c30bfb2, each caught by the new file:

Mutant	Failing tests
the old bootstrap NEXT restored	42 of 53
the reflog note dropped	6
the checkout and lockstep kinds swapped	39
the .git test dropped	2
repo_shape.py dropped from the bootstrap test	2
the note printed for every off-pin leg	3
the lockstep line retyped, not built by validator_command	2

Mutants of the fix round, each caught by the new file:

Mutant	Failing tests
--init dropped	15, the plain-clone paste and the members paste among them
--checkout dropped	16, the three update-mode pastes among them
the members row not asking the holder's gitlink	5, the four gitlink-state tests among them
the Makefile target not asked	1, the make bootstrap sentence test

Closes #276

🤖 Generated with Claude Code

Summary by Sourcery

Make shape-doctor provide reliable, condition-aware repair commands for leg and member findings instead of unconditionally suggesting bootstrap.

New Features:

• Choose actionable NEXT commands for leg and member findings based on whether submodule checkout can resolve the problem.
• Provide script-free recursive submodule checkout guidance with safeguards for detached commits and configured update modes.
• Route lockstep inconsistencies to the existing pin or family validators, including template fallbacks and no-command handling when validators are unavailable.

Bug Fixes:

• Prevent missing or incomplete bootstrap scripts from producing unusable NEXT commands.
• Ensure empty, drifted, mismatched, uninitialized, and unreadable submodules receive guidance that can either resolve the finding or identify the required lockstep repair.
• Correct member handling to account for the holder's recorded gitlink before selecting a repair command.

Enhancements:

• Centralize bootstrap capability checks, validator gate definitions, lockstep command construction, and submodule update command generation.
• Preserve the holder bootstrap path when it is available for member credential handling, while documenting when the plain Git path lacks that behavior.

Tests:

• Add comprehensive coverage for leg and member NEXT selection, shell quoting, detached-commit preservation, configured submodule update modes, validator fallbacks, and pasted-command behavior.
• Update existing shape-doctor tests to validate submodule update guidance instead of bootstrap commands.

[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 6 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Reworks the legs and members NEXT guidance to select a runnable, issue-specific repair: recursive submodule update for checkout-fixable states, validator gates for lockstep problems, and holder bootstrap only when it is executable and needed for credential handling. The change also documents detached-HEAD data-loss implications and adds comprehensive command-execution and regression tests.

Sequence diagram for checkout and lockstep repair selection

sequenceDiagram
    participant Doctor
    participant Git
    participant Validator
    participant Bootstrap
    Doctor->>Doctor: classify leg or member findings
    alt empty mount or HEAD differs while gitlink matches pin
        Doctor->>Git: submodule update --init --recursive -- paths
        Git-->>Doctor: mount initialized or reset to recorded pin
    else holder checkout finding and bootstrap.py plus repo_shape.py exist
        Doctor->>Bootstrap: bootstrap.py --root root
        Bootstrap-->>Doctor: members fetched with credential handling
    else missing pin, mismatched gitlink, or unreadable HEAD
        Doctor->>Validator: validate-pins.py or validate-family.py --root root
        Validator-->>Doctor: lockstep findings and repair guidance
    else validator copy is unreadable
        Doctor-->>Doctor: no NEXT command
    end

Loading

Flow diagram for legs NEXT command selection

flowchart TD
    A[Legs row has findings] --> B{Checkout can cure the first problem}
    B -->|Yes| C[git submodule update --init --recursive]
    C --> D{Detached HEAD off pin}
    D -->|Yes| E[Explain reflog loss and suggest git -C leg branch NAME]
    D -->|No| F[Optional bootstrap follow-up]
    B -->|No| G[Build validate-pins.py gate]
    G --> H{Validator copy readable}
    H -->|Yes| I[Print lockstep validator command]
    H -->|No| J[Print no NEXT command]
    F --> K[Re-run doctor if lockstep findings remain]

Loading

Flow diagram for members NEXT command selection

flowchart TD
    A[Members row has findings] --> B{Checkout-fixable member exists}
    B -->|Yes| C{Holder bootstrap.py and repo_shape.py exist}
    C -->|Yes| D[Use holder bootstrap.py]
    C -->|No| E[Use recursive submodule update]
    E --> F[Explain missing credential rewrite]
    B -->|No| G[Build validate-family.py gate]
    G --> H{Validator copy readable}
    H -->|Yes| I[Print lockstep validator command]
    H -->|No| J[Print no NEXT command]
    D --> K[Re-run doctor for remaining findings]
    E --> K

Loading

File-Level Changes

Change	Details	Files
Routes leg and member remediation to the command that matches whether the issue is checkout-fixable or requires pin validation.	Adds a shared script-free recursive submodule update command for empty mounts and checkout drift. Classifies missing or mismatched gitlinks, invalid pins, and unreadable HEADs as lockstep validation failures. Preserves checkout-first precedence and explains that a subsequent doctor run may expose remaining lockstep issues.	shape-doctor.py
Adds context-aware handling for holder bootstrap availability and detached-work preservation.	Keeps a holder's own bootstrap as the member NEXT when both bootstrap.py and repo_shape.py are available. Falls back to the git command when holder scripts are unavailable, noting the lack of credential rewriting. Adds conditional reflog warnings and branch-creation guidance only for detached off-pin mounts.	shape-doctor.py
Expands regression coverage for generated NEXT commands and their effects.	Adds 53 tests covering command selection, shell quoting, pasted-command behavior, validator fallback, missing scripts, unreadable repositories, precedence, and detached commits. Verifies validator commands are constructed through the shared validator helpers and disappear when neither validator copy is readable. Updates existing expectations from bootstrap commands to submodule updates.	tests/test_doctor_legs_members_next.py tests/test_shape_doctor.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#276	Ensure the legs and members rows do not print a scripts/bootstrap.py command when the required script or its repo_shape.py dependency is missing, avoiding a pasted can't open file or import failure.	✅
#276	Make each row's NEXT command appropriate to the reported problem and capable of curing problems that a checkout can fix, especially empty submodule mounts and legs or members checked out away from their recorded pin.	✅
#276	Use the appropriate validator/lockstep command, or no command when no readable validator exists, for problems that a submodule checkout cannot cure, while preserving a holder's usable bootstrap where it provides required credential handling.	✅

Possibly linked issues

• shape-doctor.py: the legs row's NEXT (and the members row's) runs <root>/scripts/bootstrap.py without asking whether the root has it, so a root that lost it pastes python3: can't open file, exit 2, and for an empty leg mount the legs NEXT would not cure the row even with the file there (bootstrap.py only prints Run git submodule update --init spec) #276: PR directly fixes issue shape-doctor.py: the legs row's NEXT (and the members row's) runs <root>/scripts/bootstrap.py without asking whether the root has it, so a root that lost it pastes python3: can't open file, exit 2, and for an empty leg mount the legs NEXT would not cure the row even with the file there (bootstrap.py only prints Run git submodule update --init spec) #276 by selecting script-free submodule updates or validation gates based on each reported problem.

---

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.

[sonarqubecloud]

Quality Gate passed

Issues
3 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