[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #735 (comment)

Closes #735.

Lands after the v1.1.0 tag. The issue's own "Lands after: #705" is met: #705 landed as 3ceabef0.

What changed, and why

make siblings ended in a traceback on three slots at ../<Project>, exit 1, and never placed the members after them. #705's doctor calls each of these slots not-a-clone. Measured with this PR's tests against main e3137010's siblings.py: all 7 new cases fail.

• A FILE: any(target.iterdir()) at siblings.py:558 raised NotADirectoryError.
• A folder with mode 0311 (it can be entered but not listed; 711 is common for another user's directory): the same line raised PermissionError.
• A folder with mode 000: the traceback comes one line earlier on Python 3.12. (target / ".git").exists() at :557 raises PermissionError, because Path.exists ignores only ENOENT, ENOTDIR, EBADF and ELOOP. The issue puts all three at :558; for mode 000 it is :557.

templates/family-root/scripts/siblings.py:

• holds_git (:460) asks whether a path holds a .git, and reads an OSError as "no". Two places use it:

  • place's .git question (:596);
  • dispatch's .git question (:768), the --make path that make park and make resume run. Python 3.12 raised there in a folder that cannot be entered, so make park ended in the same traceback. That member is now SKIPPED no clone, as any member with no working clone is.

• not_a_clone (:471) gives the NOT A CLONE finding's words for each slot nothing is cloned into:

  • a folder with something in it keeps its existing finding, byte for byte;
  • a file: "is a file, not a folder" (:491);
  • a folder it cannot list or enter: "is a folder that cannot be listed" (:496).

  These are the words the doctor's members row uses for the same slots. git clone refuses a folder it cannot read (measured: destination path ... is not an empty directory, exit 128), so nothing could be cloned there.

• place (:596-605) reports each such slot as NOT A CLONE, in the finding sentence the folder of files already had: "<who>: <at> <what>, so this command will not write into it. Move it aside or name the <file|directory> something else; nothing here overwrites a <file|directory> somebody made." The slot is left exactly as it is, and the members after it are placed.

shape-doctor.py: comments only, at :8012, :8163 and :8182. Its output is unchanged. For these slots, the row says what stands there and nothing of what make siblings does with it. That stays true of every holder, because a holder whose pinned siblings.py predates this change still ends in the traceback. The comments now say so, where they said make siblings "ends in a traceback ... today".

What is tested

• tests/test_shape_doctor.py: the agreement test test_make_siblings_dry_run_gives_the_rows_word_for_each_slot (:4152) loses its strict xfail on a-file.
  • It now runs over UNREADABLE_SLOTS (:4063): a file, and the 0o311 and 0o000 folders, which are skipped on Windows and as root.
  • The holder's own siblings.py --dry-run prints NOT A CLONE for each, the word the doctor's not-a-clone maps to.
  • The row test (:4119) shares the same list.
• tests/test_family.py:
  • test_siblings_reports_a_slot_it_cannot_read_as_not_a_clone (:1948) runs over the same three slots, on a real run in a correct layout. It asserts:
    • no traceback, and exit 1;
    • the layout row sibling IRRS NOT A CLONE -;
    • the finding, word for word;
    • IRSS, the member after it, still placed;
    • the slot's file unchanged, and no .git written into the slot.
  • test_a_make_verb_skips_a_folder_it_cannot_enter (:1981) runs --make park --dry-run over a mode-000 folder: no traceback, and sibling IRRS SKIPPED no clone -.
• Red first: against main's siblings.py, all 7 new cases fail (7 failed, 12 passed). They pass on this branch.

Commands, at 1d149933 on main e3137010, with a stub gh (exit 97) first on PATH, GH_TOKEN=bogus and an empty GH_CONFIG_DIR:

/usr/bin/python3 -m pytest -q -rsx -p no:cacheprovider --basetemp=<scratch>/bt-a -o tmp_path_retention_policy=failed tests/test_family.py tests/test_family_siblings_placement.py tests/test_siblings_family_name.py tests/test_family_makefile_siblings.py tests/test_park_resume_targets.py tests/test_windows_paths.py tests/test_family_printed_quoting.py tests/test_update_shape_add.py tests/test_update_shape_kept_helper.py tests/test_repo_hygiene.py tests/test_cli_reference.py
721 passed in 161.89s (0:02:41)

/usr/bin/python3 -m pytest -q -rsx -p no:cacheprovider --basetemp=<scratch>/bt-b -o tmp_path_retention_policy=failed tests/test_shape_doctor.py tests/test_doctor_members_spelled.py tests/test_doctor_gitmodules_not_utf8.py
471 passed, 3 skipped in 405.86s (0:06:45)   (skips: tests/test_shape_doctor.py:10424, the PowerShell line, Windows host only)

Pinned shape copies

templates/family-root/scripts/siblings.py is a family-root copy carried by digest. A holder pinned before this change shows an upstream-changed row for it until update-shape.py brings it forward. No other pinned copy is touched.

Coordination

#690 changes the same file. Its branch fix/690-siblings-inputs is a WIP checkpoint with no PR yet.

• It inserts argument_fault and _bytes_for between run_member_bootstrap and place, a block before if target == root:, and a line after the clone.
• This branch puts its two helpers after project_id, and edits only place's .git and NOT A CLONE lines and dispatch's .git line. So the two branches change different lines. A merge may still need a small context fix where siblings.py (make siblings): the printed mv goes astray over an existing .holder/.folder or a dangling link, a lone surrogate or NUL in project: is a traceback, a url with NEL or U+2028 is cut, two warnings print paths raw #690's block sits above place's .git line.

No docs change: no doc quotes the NOT A CLONE finding or describes these slots, and siblings.py's --help is unchanged, so docs/cli.md is too.

🤖 Generated with Claude Code

Summary by Sourcery

Make sibling and make operations safely handle files and unreadable directories by reporting them as non-clones and continuing without overwriting them.

Bug Fixes:

• Handle files and unreadable directories as non-clone sibling slots without traceback, preserving them and continuing to place later members.
• Prevent make park and resume operations from failing when a sibling path cannot be inspected for a working clone.

Enhancements:

• Align sibling placement and doctor reporting for unreadable or non-directory slots with consistent NOT A CLONE findings.

Tests:

• Add coverage for files and unreadable directories during sibling placement and make operations.
• Expand doctor agreement tests to cover all unreadable sibling slot types.

[sourcery-ai]

Reviewer's Guide

The PR makes make siblings and related --make verbs resilient to files and directories that cannot be listed or entered by safely handling filesystem errors, reporting such slots as NOT A CLONE or SKIPPED no clone, preserving their contents, and continuing processing; comprehensive tests and doctor commentary are updated accordingly.

Sequence diagram for resilient sibling placement

sequenceDiagram
    participant Make as make siblings
    participant Place as place
    participant FS as Filesystem
    participant Next as Later members

    Make->>Place: place(root, row, urls, prefix)
    Place->>FS: holds_git(target)
    FS-->>Place: false or OSError
    Place->>FS: not_a_clone(target)
    alt file or unreadable directory
        FS-->>Place: occupied slot
        Place-->>Make: NOT A CLONE
        Place->>FS: preserve existing target
    else empty or absent target
        FS-->>Place: cloneable target
        Place->>FS: git clone
    end
    Place->>Next: continue placing later members

Loading

Sequence diagram for safe park or resume dispatch

sequenceDiagram
    participant Make as make park or resume
    participant Dispatch as dispatch
    participant FS as Filesystem

    Make->>Dispatch: dispatch(root, row, urls, target)
    Dispatch->>FS: holds_git(path)
    alt path cannot be entered or has no .git
        FS-->>Dispatch: false after OSError handling
        Dispatch-->>Make: SKIPPED no clone
    else working clone
        FS-->>Dispatch: true
        Dispatch->>FS: run requested make action
    end

Loading

Flow diagram for unreadable sibling slot handling

flowchart TD
    A[Inspect sibling target] --> B{"holds_git(target)?"}
    B -->|yes| C[Use existing clone]
    B -->|no or filesystem error| D{"not_a_clone(target)"}
    D -->|file or unreadable directory| E[Report NOT A CLONE]
    E --> F[Leave target unchanged]
    F --> G[Continue with later members]
    D -->|absent or empty directory| H[Clone member]

Loading

File-Level Changes

Change	Details	Files
Harden sibling placement and make-verb dispatch against files and unreadable directories, treating them as non-clones without aborting processing.	Added guarded .git detection that converts filesystem access errors into “no clone.” Added classification for files, non-empty directories, and directories that cannot be inspected. Updated placement to emit the appropriate NOT A CLONE finding, preserve the existing occupant, and continue placing later members. Updated --make dispatch to skip inaccessible non-clones instead of raising. Kept existing behavior and wording for ordinary non-empty directories.	templates/family-root/scripts/siblings.py
Expanded regression coverage for unreadable sibling slots and verified continued placement and make-verb behavior.	Tested file, unlistable directory, and unenterable directory cases with platform/root skips. Verified no traceback, exit status, exact findings, unchanged occupants, no unwanted .git, and placement of subsequent members. Verified make park --dry-run reports an inaccessible slot as SKIPPED no clone.	tests/test_family.py
Aligned shape-doctor agreement tests and explanatory comments with the new runtime handling while preserving doctor output.	Removed the strict file-case xfail and included unreadable directory cases in agreement tests. Confirmed doctor rows and holder dry-run output use matching not-a-clone wording. Clarified comments for holders with pre-siblings.py (make siblings): a FILE, or a directory it cannot list, at ../<Project> ends in a traceback (NotADirectoryError or PermissionError at siblings.py:558), exit 1, where the doctor calls the slot NOT A CLONE #735 pinned copies, whose behavior remains traceback-prone.	shape-doctor.py tests/test_shape_doctor.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#735	Handle a file or a directory that cannot be listed at a sibling slot without a traceback, report it as NOT A CLONE, and leave it untouched while continuing to place later members.	✅
#735	Ensure inaccessible sibling paths do not cause make operations such as make park to traceback when checking for a working clone.	✅
#735	Remove the strict xfail for the doctor/siblings agreement test and cover file, mode-0311, and mode-000 slots, with permission-mode cases skipped on Windows and as root.	✅

Possibly linked issues

• siblings.py (make siblings): a FILE, or a directory it cannot list, at ../<Project> ends in a traceback (NotADirectoryError or PermissionError at siblings.py:558), exit 1, where the doctor calls the slot NOT A CLONE #735: The PR implements the issue: it safely handles files and unlistable folders, reports NOT A CLONE, and adds regression tests.

---

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-3, 2026-10-17T01:10:10Z) Independent review of #772 by RV-d (opus), on head 1d149933: READY. No MUST and no SHOULD; three NITs. It lands only after the v1.1.0 tag, once its Linux tests is green.

Each slot on a real two-member holder (IRRS, then IRSS), measured with make siblings, make park and make resume. The slot is byte-identical before and after every verb.

slot at ../IRRS	main: make siblings	head: make siblings	head: park / resume	doctor
a file	traceback, IRSS never placed	NOT A CLONE, "is a file, not a folder", IRSS cloned	SKIPPED no clone	not-a-clone
a symlink to a file	traceback	NOT A CLONE, file wording	SKIPPED no clone	not-a-clone
a dangling symlink	CLONE FAILED	same	SKIPPED no clone	absent (N2)
a symlink to a folder with files	NOT A CLONE	same	SKIPPED no clone	not-a-clone
folder, mode 0311	traceback	NOT A CLONE, "cannot be listed"	SKIPPED no clone	not-a-clone
folder, mode 000	traceback, park/resume too	NOT A CLONE, "cannot be listed"	SKIPPED no clone	not-a-clone
a clone whose .git is mode 000	WRONG ORIGIN	same	WRONG ORIGIN	wrong-origin
a folder with files (control)	NOT A CLONE	same, byte-identical	SKIPPED no clone	not-a-clone

Answers:

• The issue's claims hold on main, and so does the writer's correction. Mode 000 tracebacks at :557 (.git.exists() raises); mode 0311 at :558 (iterdir).
• The doctor agrees with make siblings in every slot.
• The doctor should keep its neutral wording. A holder pinned before this change still tracebacks.
• dispatch's new SKIPPED is right for every --make verb. It fires before any make and reuses the existing "no working clone" skip.
• Pinned copy, docs, Windows:
  • the body names the family-root copy (scripts/shape_materialize.py:533, :558 list it);
  • no doc quotes the finding;
  • the code is pathlib only, and the mode tests skip on Windows and as root;
  • SonarCloud passes.

NITs:

• N1 siblings.py:768-771 (optional): for a mode-000 folder, make park says "no working clone at ; run make siblings first". If that folder is a clone, it is there. Use not_a_clone's "cannot be listed" words in the skip when they apply.
• N2 siblings.py:488 (follow-up): a dangling symlink still reads as an empty slot. The dry run says "would clone" and the doctor says absent, while the real run ends CLONE FAILED. This is not a traceback and main behaves the same. Fix: treat is_symlink() and not exists() as NOT A CLONE, "is a link to nothing".
• N3 tests/test_shape_doctor.py:4063 (optional): add a symlink to a file to UNREADABLE_SLOTS. The doctor and make siblings agree on it today.

Mutants: RV-d tried seven mutants of siblings.py and all seven are killed:

• holds_git raises;
• either wrong wording for a file;
• place stops after the first bad slot;
• only FileNotFoundError is caught;
• dispatch's unguarded check;
• an unlistable folder read as empty.

Tests:

• 7 family and siblings files: 487 passed in 134.64s;
• tests/test_shape_doctor.py -k (siblings rows): 41 passed;
• the slot probe: 10 passed on the head and on main.

Merges. All clean:

• e3137010;
• validate-pins.py: the <repository>: N workflow @<sha> reference(s) agree with the gitlink note counts only the references at the gitlink, says N of M where some are not, and is not printed where none is, so no reference is both a pin-workflow-ref-mismatch and one that agrees (#739) #769;
• tests/test_update_shape_merged_away.py: the pins row's merged-away check is tested where check refuses the standard, and beside a both, an upstream-removed and an unmapped row, so a refusals_ahead that answers a refusal with nothing ahead, or counts copy-is-link alone, fails a test (#755) #770;
• shape-doctor.py: in a root that lost scripts/repo_shape.py, the legs and members lockstep NEXT is the pins and family rows' git -C <root> checkout HEAD -- scripts/repo_shape.py (none where HEAD no longer holds it), where it named the root's own gate, which dies on the import (#750) #771;
• lane 4's siblings.py (make siblings): the printed mv goes astray over an existing .holder/.folder or a dangling link, a lone surrogate or NUL in project: is a traceback, a url with NEL or U+2028 is cut, two warnings print paths raw #690 WIP tip fix/690-siblings-inputs (38a40abf), where the merged siblings.py parses with argument_fault ahead of this PR's checks. Re-check this merge when siblings.py (make siblings): the printed mv goes astray over an existing .holder/.folder or a dangling link, a lone surrogate or NUL in project: is a traceback, a url with NEL or U+2028 is cut, two warnings print paths raw #690 opens.

Lane: openreposhape-3 (openRepoShape-3)

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