[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #437 (comment)
Claim: #431 (comment)
Claim: #535 (comment)

Three S issues in disjoint functions of one file, in one pull request so that update-shape.py takes one landing and one three-OS run for all three. One commit per issue, in this order: 6c6e8208 (#437), a647bab8 (#431), 369fede9 (#535); then 8eed2d7f and fabdd7e5, the fix round after the independent review (below). Nothing in README.md, docs/handbook.html or any --help text changes, so docs/cli.md is as it was.

What changed and why

#437: a files: or shape: header that carries a trailing comment

rewrite_shape_pin found files: as line.rstrip() == "files:" and wrote it back bare, and _shape_block_bounds found shape: the same way. A header followed by a comment, which the reader and both validators accept, was refused as update-pin-unrecognised ("0 files line(s)") or update-manifest-no-shape (false: the block exists; its remedy, "add it", would give the manifest a second shape: key), after check had sent the person to apply.

Both headers are now found with repo_shape._strip_comment at column 0, the reader's own rule for where a comment starts (imported by its private name, as shape_materialize does since #380). That is the whole claim: a quoted key ("files":) or a space before the colon (files :) is read as the key by the reader and is not found here, as before. The files: header is written back as the line it was; the manifest's header is never rewritten. Kept: the missing-header count refusal, update-manifest-no-shape for a manifest with no shape:, #380's byte-identical rewrite of a scaffold-shaped pin and manifest, and rewrite_fault's read-back. A family holder's family.yaml shape: goes through the same function and is tested.

A shape: key written twice (fix round): the reader keeps the last block. On main a plain doubled key was refused by the read-back, and one whose first header carries a comment was ACCEPTED, because the exact match skipped the commented header and rewrote the last block, which the reader reads. With the comment-aware finder that second form would have been refused in the read-back's words, "the fault is this tool's line rewrite", which are false of a doubled key. _shape_block_bounds now refuses any manifest holding the header twice, by name, under update-manifest-unrecognised: "holds the shape: key twice, at lines N and M ... the reader keeps the last block", with the remedy to delete the extra block. It is a deliberate refusal of the form main accepted by accident, and the header finder is otherwise unchanged.

#431: --branch judged the same from any directory

checked_branch ran git check-ref-format --branch in the operator's directory, so from a .git file naming a missing gitdir, a .git/config with a syntax error, or a removed working directory a good name was refused as update-branch-invalid, git's failure read as the name's fault.

It now asks shape_materialize._ask_git_branch (no repository in play, #355), imported with BRANCH_CONTROL and BRANCH_UNCHECKED_REMEDIATION; shape_materialize.py is not edited. The alphabet check, the code, the --branch '<name>' prefix and this tool's own BRANCH_REMEDIATION for a name git refused or expanded are unchanged (the two tests that pin them pass as they were). A git that refuses main too, or cannot be run, is worded "could not be checked" with BRANCH_UNCHECKED_REMEDIATION, never the name's fault. @{-1} is outside the alphabet, so it is refused before git is asked; the expansion arm is covered in-process.

#535: four messages

• N1. A branchless apply whose written paths are all HEAD's bytes again prints one NEXT saying there is nothing to commit, not a commit line. An --add file is not in HEAD, so a run that added one still gets its line; a root with no commit gets the line it always got. Fix round: the test is by bytes AND by mode, git diff --quiet HEAD over the written paths (--literal-pathspecs), because a chmod leaves the blob alone and git commits it; that diff is answered only where HEAD names a commit, so it carries the no-commit case too.
• N3. The both row's detail names the upstream's file; update-conflict's remedy spells git show <full target>:<source> for each both row (merge_by_hand replaces the MERGE_BY_HAND constant). <target> is filled too: Row gains target, set where source is, so cmd_apply passes nothing new. unmapped and upstream-removed rows are named no command (none reads). rewrite_link_refusal keeps its <source path> placeholder (the issue marks it optional, and it holds neither value).
• N4. The commit message and --pr's body claim "not hand-edited" only of the copies re-copied from the upstream, and name the paths --accept-local kept. They reach commit_on_branch and pull_request_line through _land as the new keyword accepted, the only line of cmd_apply this PR changes. Fix round: a --pr re-run (_finish_landing) has no rows, so _accepted_in_the_pin reads the accepted paths back out of the committed pin: the rows whose recorded digest is not the digest of the upstream's file at the target AND is not the digest the tracking branch's pin (origin/<tracking>) held. The second condition keeps an in-place adoption's Makefile row, which has always recorded bytes with the adoption's block appended, from being reported as kept by a flag nobody passed; where origin/<tracking> cannot be read the answer is none (a body that names too few paths is incomplete, one that names a path nobody accepted is false). The re-run opens the very command the first run tried, as test_update_shape_landing.py holds it to.
• N7. The gh pr create that apply --branch prints without --pr carries --title and --body, shlex-quoted, with --pr's words (pull_request_words is the one place they are written). Not --fill, which reads the commits of wherever the line is pasted. The bare form pull_request_line builds for a failed --push's NEXT is the same line's twin and carries them too. next_line is not passed the upstream or the accepted paths, so _land keeps the words on args. Fix round: pull_request_words takes the root's manifest name, so a holder's body says family.yaml re-pinned, not project.yaml (it said project.yaml in the plain NEXT, the failed---push NEXT and --pr's own body), and its opening clause "the copied shape files were re-copied from the upstream", false for a run whose only change is an accepted both row, is gone: the body says what was re-pinned and that no copy re-copied from the upstream was hand-edited, which is true of none, one or many. A count, as the commit message gives, is not added: a re-run does not know it and must open the same command.

gh's behaviour without a terminal was not run, and no test or probe here runs a real gh pr create: the change is printed text, tested as text (round trip through shlex.split, compared with what --pr opens).

Tests

New files, one per issue: tests/test_update_shape_header_comments.py (54), tests/test_update_shape_branch_any_directory.py (28), tests/test_update_shape_messages.py (26). The assertions that pinned the old texts moved in place: test_update_shape_next_quoting.py, test_update_shape_pr_base.py, test_update_shape_landing.py, test_update_shape.py (:1229). The fix round adds, in those files: the holder's words read whole (the printed line, --pr's body and the failed-push line); a run that re-copied nothing; the re-run's body equal to the first run's, with and without an adopted Makefile row, and with nothing accepted; a chmod of a written path (POSIX only, WINDOWS_SKIP); and a doubled shape: key with a comment on neither, the first, the last and both headers, for both kinds.

pytest tests/test_update_shape_header_comments.py tests/test_update_shape_branch_any_directory.py tests/test_update_shape_messages.py tests/test_update_shape.py tests/test_update_shape_landing.py tests/test_update_shape_add_ignored.py tests/test_update_shape_next_quoting.py tests/test_update_shape_pr_base.py tests/test_update_shape_merged_away.py tests/test_pin_rewrite_layout.py tests/test_repo_hygiene.py tests/test_cli_reference.py tests/test_agents_md_codes.py
621 passed in 279.97s (Linux; git-filter-repo from CI's pin venv on PATH, so the adoption tests do not skip)
pytest tests/test_family.py -k "update_shape or shape_block or manifest_no_shape"
4 passed
pytest tests/test_update_shape_add.py tests/test_update_shape_add_symlink.py tests/test_update_shape_add_not_a_directory.py tests/test_update_shape_rewrite_symlink.py tests/test_commit_trailers.py tests/test_refusal_default_remediation.py tests/test_shape_pin_files_not_a_list.py tests/test_doctor_next_is_a_command.py tests/test_load_yaml_refusals.py
359 passed, 3 skipped (NTFS junctions, Linux)
pytest tests/test_shape_doctor.py -k "currency or conflict or update_shape or accept_local"
24 passed

Mutants, each run against the new test file(s) for its issue on the final head and reverted (update-shape.py restored byte-identical, checked by sha256). Every one is killed:

mutant	result
#437: the exact-header match (line.rstrip() == "<key>:") restored	40 of 54 fail
#431: checked_branch asks bare git check-ref-format --branch in the operator's directory, not the helper	9 of 28 fail
#535 N1: the whole nothing-to-commit branch removed	2 of 26 fail (in-process and end to end)
#535 N1: the HEAD requirement removed (no _same_as_head)	2 of 26 fail (a root with no commit, and the chmod)
#535 N1: the mode check ignored (blobs only, HEAD still required)	1 of 26 fails (the chmod)
#535 N7: the words _land keeps drop the accepted paths	1 of 26 fails
MUST: the words name project.yaml whatever the root is	1 of 26 fails (the holder)
SHOULD: the re-run's body names no accepted path	2 of 26 fail
SHOULD: the re-run names every row that is not the upstream's bytes (no base comparison)	2 of 26 fail (the adopted Makefile is named)
NIT: a doubled shape: is not refused by name	8 of 54 fail
NIT: the body opens with the old "were re-copied" clause	2 of 26 fail

The N1 "HEAD check" mutant of the first round became equivalent when the mode check was added (a root with no commit makes git diff HEAD fail, which is "not the same"), so the explicit _has_head beside it was removed rather than left as a guard no input could tell from its absence (fabdd7e5, no output changes). The docstring-only narrowing of what the header finder claims has no mutant.

CI is the Windows gate: fixtures for #437 are bytes (write_bytes, a CR-keeping regex), and the removed-directory cases of #431 and the chmod case are WINDOWS_SKIP.

Shared files

update-shape.py is also edited by three other lane-4 PRs, on other lines: P3 (#422, #428) the module docstring, Rollback.write and undo, one line in cmd_check, a new function after _refuse_linked_copies and one line in cmd_apply after _refuse_linked_copies(rows); P4 (#536) a new function between _nothing_to_do and _write_copies and one line in cmd_apply before confirm(...); P9 (#532, later) cmd_check, the update-branch-exists remedy, _refuse_local_drift, _note_untaken_additions, accept_local_exit and keep_local_exits. The two import blocks are this PR's alone. In cmd_apply this PR changes the _land(...) call and nothing else.

v1.1.0: lands only after the v1.0.0 tag

Closes #437
Closes #431
Closes #535

🤖 Generated with Claude Code

Summary by Sourcery

Make update-shape.py preserve valid header comments, validate branches consistently, and report apply and pull-request actions accurately.

Bug Fixes:

• Preserve and correctly process trailing comments on top-level files: and shape: headers, while refusing manifests with duplicate shape: keys.
• Make branch validation independent of the operator’s current directory and distinguish invalid names from Git environments that cannot be checked.
• Correct apply, conflict, commit, and pull-request messages so they accurately describe changed files, accepted local files, upstream sources, and no-op commits.
• Include complete title and body arguments in generated gh pr create commands.

Enhancements:

• Improve conflict remediation by identifying the exact upstream file and target commit for each mergeable conflict.
• Detect content and file-mode changes relative to HEAD before printing commit instructions.
• Keep pull-request wording consistent between direct creation, rerun flows, and printed next commands, including family manifests.

Tests:

• Add comprehensive coverage for commented headers, duplicate shape keys, branch validation from unavailable directories, corrected apply messages, no-op commits, mode changes, rerun behavior, family holders, and pull-request command quoting.

[sourcery-ai]

Reviewer's Guide

Updates update-shape.py to preserve commented shape headers, perform directory-independent branch validation, and produce accurate, actionable apply/conflict/commit/pull-request messages, with extensive regression coverage across project and family-holder workflows.

Sequence diagram for directory-independent branch validation

sequenceDiagram
    participant Operator
    participant UpdateShape
    participant BranchHelper
    participant Git

    Operator->>UpdateShape: checked_branch(value)
    UpdateShape->>BranchHelper: _ask_git_branch(value)
    BranchHelper->>Git: check-ref-format --branch value
    Git-->>BranchHelper: branch verdict
    BranchHelper-->>UpdateShape: answer
    alt answer matches value
        UpdateShape-->>Operator: accept branch
    else Git refuses value
        UpdateShape->>BranchHelper: _ask_git_branch(BRANCH_CONTROL)
        BranchHelper->>Git: check-ref-format --branch BRANCH_CONTROL
        Git-->>BranchHelper: control verdict
        alt Git can answer
            UpdateShape-->>Operator: update-branch-invalid
        else Git cannot answer
            UpdateShape-->>Operator: could not be checked
        end
    end

Loading

Sequence diagram for accurate apply landing messages

sequenceDiagram
    participant Apply as cmd_apply
    participant Land as _land
    participant PR as pull_request_words
    participant Commit as commit_on_branch
    participant Next as next_line

    Apply->>Apply: _accepted_local(rows)
    Apply->>Land: _land(..., accepted)
    Land->>PR: pull_request_words(repository, target, accepted)
    PR-->>Land: title and body
    Land->>Commit: commit_on_branch(..., accepted)
    Commit-->>Land: commit message names kept paths
    Land-->>Apply: landing result
    Apply->>Next: next_line(...)
    Next-->>Apply: quoted gh pr create with --title and --body

Loading

Flow diagram for preserving commented shape headers

flowchart LR
    Input["Pin or manifest with files: or shape: and trailing comment"] --> Strip[_strip_comment]
    Strip --> Match[_is_block_header]
    Match --> RewritePin["rewrite_shape_pin preserves original files: line"]
    Match --> Bounds["_shape_block_bounds finds shape: block"]
    RewritePin --> ReadBack["rewrite_fault read-back validation"]
    Bounds --> Manifest["Manifest header remains unchanged"]

Loading

Flow diagram for apply no-change and conflict messaging

flowchart TD
    Apply["apply writes selected paths"] --> Head{"HEAD exists?"}
    Head -->|no| CommitHint["existing commit guidance"]
    Head -->|yes| Compare["_not_what_head_commits"]
    Compare -->|paths match HEAD| Nothing["NEXT: nothing to commit"]
    Compare -->|paths differ| Commit["commit guidance"]
    Conflict["Conflict rows"] --> Merge["merge_by_hand(rows)"]
    Merge --> Both["both rows name git show target:source"]
    Merge --> Other["unmapped/upstream-removed rows name no command"]

Loading

File-Level Changes

Change	Details	Files
Make shape-pin and manifest rewrites recognize top-level headers with trailing comments while preserving the original header text.	Match files: and shape: through the shared comment-stripping rule. Preserve comments and spacing on rewritten files: headers while retaining missing-header and read-back safeguards. Cover project, family-holder, byte-preserving, end-to-end, and duplicate-header behavior.	update-shape.py tests/test_update_shape_header_comments.py tests/test_update_shape.py
Validate --branch independently of the operator’s current directory or repository state.	Reuse shape_materialize’s repository-independent git branch checker and shared control/remediation constants. Distinguish a branch name rejected by git from git being unable to answer, while preserving alphabet and expansion checks. Test ordinary, malformed, missing, and removed working-directory scenarios plus in-process error paths.	update-shape.py tests/test_update_shape_branch_any_directory.py
Correct apply, conflict, commit, and pull-request guidance so generated messages reflect actual outcomes and are executable.	Suppress commit commands when all written tracked paths already match HEAD, while retaining commands for additions and roots without commits. Name upstream source paths and full git show <target>:<source> commands for resolvable conflicts, omitting commands for rows without upstream bytes. Track --accept-local paths through landing and describe them separately from files re-copied from upstream. Centralize pull-request title/body generation and include shell-quoted --title and --body in printed gh pr create commands instead of --fill.	update-shape.py tests/test_update_shape_messages.py tests/test_update_shape_landing.py tests/test_update_shape_next_quoting.py tests/test_update_shape_pr_base.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#431	Validate apply --branch names independently of the operator’s working directory or surrounding repository, and distinguish a name Git rejects from a failure that prevents Git from answering.	✅
#431	Preserve rejection of invalid branch names and names Git would expand, without allowing a repository’s reflog to affect validation.	✅
#437	Recognize top-level files: headers in shape pins and shape: headers in manifests even when they have accepted trailing comments, preserve those comments during rewrites, and retain the existing refusal behavior for missing or doubled headers and byte-identical scaffold rewrites.	✅
#535	Avoid printing a commit command when a branchless apply leaves all written paths identical to HEAD, while retaining the command when there is no HEAD or an added file creates a change.	✅
#535	Make conflict details and remedies identify the upstream source path, and provide a usable git show command with the target commit and source path for each applicable conflict.	✅
#535	Make apply's commit message and pull-request body accurately describe re-copied files and identify paths kept with --accept-local; include title and body in printed gh pr create commands.	✅

Possibly linked issues

• update-shape.py: four messages (a commit line when there is nothing to commit, a source path nothing names, the commit message's hand-edit claim, a bare gh pr create) #535: The PR fixes update-shape.py: four messages (a commit line when there is nothing to commit, a source path nothing names, the commit message's hand-edit claim, a bare gh pr create) #535’s N3, N4, and N7 defects by naming upstream paths, qualifying accepted-local claims, and completing PR commands.
• update-shape.py: four messages (a commit line when there is nothing to commit, a source path nothing names, the commit message's hand-edit claim, a bare gh pr create) #535: The PR fixes all four specified messages: suppresses no-op commit hints, names conflict source paths, qualifies accepted-local claims, and adds PR title/body.

---

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