[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #874 (comment)

A v1.1.1 DRAFT. Branch fix/874-ref-parts, from origin/main d6071c7d.

Stacked on

• install.sh and openRepoShape: a $OPENREPOSHAPE_BIN_DIR the bytes refuse is read again in the locale's own charset, so a GB18030, GBK or Shift_JIS name that holds no control character and nothing drawn as another is placed, and where nothing can read it the bytes decide as before #867 (install.sh and openRepoShape: the control-character check matches bytes, so a GBK or GB18030 name holding 0xC2 and a byte from 0x80 to 0x9F is refused as a control, and a lone 0x9B, which an 8-bit terminal acts on, is placed #858), lane 2's: head 8bb85cbf (fix/858-bin-dir-bytes), merged as 89be75bf. It edits install.sh and openRepoShape (the bin directory's byte check).
• openRepoShape: $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF are checked once, before --version answers and before any fetch, so a control character or a character a terminal draws as another in either is refused, never printed or sent #872 (openRepoShape: --version and two fetch refusals print $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF with no check, so an escape or a bidi override in either reaches the terminal as typed, and a scaffold run sends its fetch with them #866), lane 2's: head a2af74a0 (fix/866-launcher-repo-ref), merged as 145a5ee3. It edits openRepoShape (refuse_bad_values, ref_character_fault; ref_fault keeps the length and shape checks where a ref is used).

Both merges were clean, and both heads were unmoved when the branch was pushed. Review the commits after a1fa6768, the last merge: one, the fix round's 8d6c5bdb, on rv874's review (see the last section). 456589b3 (the change and its tests) and 17185b67 (the tests only, putting the network stubs under two of the table tests) are what rv874 reviewed at a1fa6768.

#867 has landed as 5c54af2. The branch then merged #867's final head 0ccda48b (8d9cd4d9), and main's squash 5c54af2 with -s ours (a1fa6768), because the squash's tree a4b0a79d is the final head's. So the diff from main is #872's and this PR's alone: git diff 5c54af2 a1fa6768 equals git diff 89be75bf 17185b67 byte for byte, apart from the index lines. #872 is still open; when it lands, this branch takes its final head and its squash the same way.

#872 has landed as c5d0bde. The branch merged #872's final head a1cad963 (5481abe7), and main's squash c5d0bde with -s ours (34d2645f), because the squash's tree 4156a29a is the final head's. Both parents have now landed, so the diff from main is this PR's alone. The head's tree 07b98c23 is main c5d0bde with the writer's two rounds applied (145a5ee3..17185b67 and a1fa6768..8d6c5bdb), measured with a scratch index.

This PR lands after #873 (lane 5's, fix/857-setup-dry-run-offers, which gives setup-project.py git's per-part rule as why_not_a_ref) and does not merge it: #873 edits setup-project.py only. #873's head is now ac570069, not the 79a33f11 the issue names: one commit on top, test-only, and setup-project.py is the same bytes. setup.sh's comment names why_not_a_ref, which exists once #873 lands.

Main 5c54af2 is merged, as above.

Decisions

1. What each copy gates, measured on the stacked base with stub gh and curl that log and fail, a local repository, and GH_TOKEN=bogus. On a.lock/b, a/.b, a//b, a/b/ and a.:

   • setup.sh printed (0) self-bootstrap, ran git clone, and ended error: pathspec '<ref>' did not match any file(s) known to git, exit 1. Its check runs only on the self-bootstrap path (is_shape_checkout execs setup-project.py before it), so it gates the clone.
   • install.sh asked curl for https://raw.githubusercontent.com/opensoft/openRepoShape/<ref>/openRepoShape (one request). The version is the URL's path, so the check gates the fetch.
   • openRepoShape --install with OPENREPOSHAPE_RECORD_REF=1 exited 0 and wrote the ref to openRepoShape.ref. ref_fault's shape line gates the record an install writes and every run reads (read_recorded_ref refuses a bad one before any request), and the doctor's git checkout.

2. Every copy holds the rule itself. None of the three only gates a later setup-project.py run: between each check and that run there is a clone, a fetch or a record, so the issue's second option ("say so and leave it to that run") fits none.

3. The rule, one pattern list in all three, plain case patterns that bash 3.2 reads, inside each copy's character set, which is neither widened nor narrowed:

   [!A-Za-z0-9]* | *..* | */.* | *.lock | *.lock/* | *//* | */ | *. | *[!A-Za-z0-9._/-]*
   

   The first, second, fourth and last are today's. New: */.* (a part after a / starts with .), *.lock/* (a part before a / ends in .lock), *//* (an empty part), */ (a / at the end), *. (the name ends in .). That is why_not_a_ref's five facts and no more. A leading / and a leading . stay the first pattern's. The line is written out in each file, not shared: install.sh and setup.sh arrive alone down a pipe.

4. Checked against git, not argued. Every name of up to five parts from a, 0, ., /, - and .lock that the character set takes is 3110 names. Each was fed to the pattern list, read out of each of the three files, and to git check-ref-format --branch (2.43.0). The old line disagrees with git on 1122 of them (setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's number for the Python rule) and the new one on none, in each file.

5. The words: one sentence per refusal, the same in all three, which states the whole rule. The lead is as it was; the first half says an ASCII letter or digit and ASCII letters, as setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's REF_RE words do (fix round 1, NIT 7); the end, has no '..' and does not end in '.lock'., becomes the rule in setup-project.py's phrases where they fit (an empty part between slashes, the name git gives the lock file it writes beside a ref, a revision range). A sentence per failed part, as why_not_a_ref has, was weighed and left: three more die lines in each file, and nothing asks the shell copies to say which part failed.

6. setup.sh's comment said it mirrors REF_RE; it now says it mirrors checked_ref, which asks REF_RE and then why_not_a_ref, lists the rule, and says the check gates the clone.

7. No test pinned the old words (git grep -n "does not end in\|starts with a letter or digit" -- tests found none), so no existing test was changed; REF_RULE_WORDS pins the new ones, in all three.

What changed

The refusal of each copy for a.lock/b, measured by a probe. Before (the topic.lock refusal, since the old line passed a.lock/b):

REFUSED: --shape-ref is 'topic.lock', which is not a branch, tag or commit this tool will pass to `git checkout`: a ref starts with a letter or digit, uses only letters, digits, '.', '_', '/', '-', has no '..' and does not end in '.lock'.
REFUSED: the version is 'topic.lock', which is not a release tag, branch or commit: a ref starts with a letter or digit, uses only letters, digits, '.', '_', '/', '-', has no '..' and does not end in '.lock'.
REFUSED: $OPENREPOSHAPE_REF is 'topic.lock', which is not a branch, tag or commit this tool will pass to `git checkout`: a ref starts with a letter or digit, uses only letters, digits, '.', '_', '/', '-', has no '..' and does not end in '.lock'.

After, setup.sh, install.sh and openRepoShape, for a.lock/b and for topic.lock alike:

REFUSED: --shape-ref is 'a.lock/b', which is not a branch, tag or commit this tool will pass to `git checkout`: a ref starts with an ASCII letter or digit, uses only ASCII letters, digits, '.', '_', '/', '-', has no '..' (git reads it as a revision range), no empty part between slashes ('//', or a '/' at the end), no part that starts with '.' or ends in '.lock' (the name git gives the lock file it writes beside a ref), and does not end in '.'.
REFUSED: the version is 'a.lock/b', which is not a release tag, branch or commit: a ref starts with an ASCII letter or digit, uses only ASCII letters, digits, '.', '_', '/', '-', has no '..' (git reads it as a revision range), no empty part between slashes ('//', or a '/' at the end), no part that starts with '.' or ends in '.lock' (the name git gives the lock file it writes beside a ref), and does not end in '.'.
REFUSED: $OPENREPOSHAPE_REF is 'a.lock/b', which is not a branch, tag or commit this tool will pass to `git checkout`: a ref starts with an ASCII letter or digit, uses only ASCII letters, digits, '.', '_', '/', '-', has no '..' (git reads it as a revision range), no empty part between slashes ('//', or a '/' at the end), no part that starts with '.' or ends in '.lock' (the name git gives the lock file it writes beside a ref), and does not end in '.'.

What each does with the five names, before and after (exit codes; git clone lines counted on stdout; requests counted in the stub's log):

copy	before	after
setup.sh --shape-ref <ref>	prints (0) self-bootstrap, 1 git clone, exit 1 (pathspec ... did not match)	exit 2, 0 git clone lines, nothing in $TMPDIR
install.sh <ref>	1 curl request, exit 2 (could not fetch)	exit 2, 0 requests
openRepoShape --install (opt-in)	exit 0, <ref> written to openRepoShape.ref	exit 2, nothing placed

topic.lock was refused by all three before and is after, and main is taken by all three.

Tests

One table, REF_PARTS in tests/conftest.py, read by three files (so Sonar's duplication gate sees one copy): 36 names, with whether git takes each.

• The issue's: a.lock/b, x/y.lock/z, release.lock/v1, a/.b, a/.b/c, a//b, a/b/, a.lock/, a., and topic.locked, v1.0.0.
• rv873's: a/b/.c/d, x/.y/z/w.
• Of the issue's kind, and taken by the old line too: a/b., a/..
• Still refused by the whole-name rules: topic.lock, a..b, a/.., a/b.lock, .lock, /a.
• Still passing: main, v1.1.0, feature/x-y_z, a 40-hex sha, workBenches' pinned-by-workBenches-no-fetch, and a.lockb, a.lock-x/b, a/b.lockb/c, a./b, a/lock/b, refs/tags/v1.0, v1.0.0-rc.1, and, with a part that starts upper-case, _ or -, Feature/ABC-123, fix/_tmp, fix/-wip (fix round 1).

git_takes_ref asks the git on PATH (git check-ref-format --branch) and never copies its answer. assert_a_copy_answers_as_git_does holds git to the table's row first, then the copy to git, so a stale row is named as the row. assert_the_refusal_states_the_ref_rule pins the shared sentence, REF_RULE_WORDS, in all three refusals.

file	test (36 rows each)	what it pins
tests/test_setup_sh.py	test_the_shim_takes_a_shape_ref_as_git_does_before_any_clone	a copy of setup.sh outside any checkout, OPENREPOSHAPE_REPO a path nothing is at: a ref it takes prints (0) self-bootstrap and fails at the clone, offline; a ref it refuses exits 2 with the rule, prints no git clone line, leaves $TMPDIR empty
tests/test_install_sh.py	test_the_installer_takes_a_version_as_git_does_before_any_request	through Net.run(<ref>) and its fakes: a version it takes is asked of curl (a call is logged); one it refuses logs no call, exits 2 with the rule, places nothing
tests/test_openreposhape_command.py	test_an_install_records_a_ref_as_git_takes_it_and_refuses_the_rest	through install_at with the opt-in (--version asks only the characters since #872): a ref taken is recorded, exit 0; one refused exits 2 with the rule and places nothing

Every run keeps the network out of reach, with a gh and a curl that log and fail, and local paths only. install.sh's test runs under that file's own fakes and asserts a refused version logs no call. The other two put fake_github(tmp_path, (), log=...) first on $PATH (17185b67): the setup.sh test asserts the log was never written; the launcher test asserts no curl ran and no gh but the gh auth status an install that placed the command asks (the machine report), and that a refused install asked for nothing. install_at takes an env_also for it.

Runs, /usr/bin/git 2.43.0, /usr/bin/python3, one pytest process at a time, in two batches. Batch 1: test_setup_sh, test_install_sh, test_install_sh_filter_repo, test_repo_hygiene, test_cli_reference, test_agents_md_codes. Batch 2: test_openreposhape_command, test_openreposhape_package, test_setup_project_py. Those are the issue's four files, every file that names a word changed (git grep -l), and the common three.

	batch 1	batch 2	total
stacked base 145a5ee3, before the change (batch 1 without test_install_sh_filter_repo)	471 passed	699 passed	1170 passed
17185b67, after (same batch 1)	537 passed	732 passed	1269 passed
a1fa6768, the restacked head rv874 reviewed, before the fix round	555 passed	732 passed	1287 passed
8d6c5bdb, after the fix round	561 passed	735 passed	1296 passed

The 99 more at 17185b67 are the three new tests at 33 rows each; the 9 more at 8d6c5bdb are the three rows the fix round adds to each. Nothing was red before. The whole suite is the coordinator's gate.

On the base: the three new tests against the base copies of the three files (145a5ee3): 57 failed, 51 passed (the 17 passing names, three times), measured again with the fix round's 36 rows. Per copy, 13 names the old line takes and git refuses fail, and the 6 refused names it already refused fail on the words.

Mutants, each applied to the case line, the copy's own table test run, the file put back at once (git status clean after). All 33 (11 per copy) are caught:

mutant	rows that fail, in each copy's test
the old line back, *.lock the only .lock check	13: a.lock/b, x/y.lock/z, release.lock/v1, a/.b, a/.b/c, a//b, a/b/, a.lock/, a., a/b/.c/d, x/.y/z/w, a/b., a/.
drop */.*	a/.b, a/.b/c, a/b/.c/d, x/.y/z/w
drop *.lock/*	a.lock/b, x/y.lock/z, release.lock/v1
drop *//*	a//b
drop */	a/b/
drop *.	a., a/b.
drop *.lock	topic.lock, a/b.lock
add *./* (refuses a part that ends in . but not the name)	a./b
the words no empty part between slashes cut to no empty part	the 19 refused rows (the words assertion)
the lead's an ASCII letter or digit cut back to a letter or digit	the 19 refused rows (the words assertion)
setup.sh: add */[-_]* (refuses a part that starts with - or _)	fix/_tmp, fix/-wip
install.sh: add */[A-Z]* (refuses a part that starts upper-case)	Feature/ABC-123
openRepoShape: [!A-Za-z0-9]* becomes [!a-z0-9]*	Feature/ABC-123

The last three mutants survive the table without the fix round's three rows (deselected: 33 passed in each copy, as rv874 measured) and are killed with them.

git: /usr/bin/git 2.43.0 only. The issue also names 2.47.1: it was not run here, and CI runs a newer git. The tests ask whichever git runs them, so CI holds the copies to that git's answer. No Windows or macOS run: CI is Linux only (#597).

Not changed

• The bin directory's byte check, misdrawn_characters, locale_reading, refuse_bad_values, checked_repo and ref_character_fault, and the length and control-character checks of all three.
• A fourth copy, in the Python package: src/openreposhape/standard.py:215 keeps the old rule (not REF_RE.fullmatch(ref) or ".." in ref or ref.endswith(".lock")) and the old sentence. target() checks a ref "before anything reaches git", so it gates the package's clone of the standard. rv874 confirmed it with a probe on a detached copy of the package: 1 git clone into the cache for each of the five names, then REFUSED: cloned ... but could not check out. The issue names three bash copies and this PR touches no Python, so it is left; it wants its own issue. Its docstring at :198-201 says it is "the launcher's ref_fault, in its order and its words", which is no longer true of the words once this lands.
• openRepoShape:829 shape_checkout (--doctor from a download) runs git clone (:834) before checked_ref (:839). test_a_ref_the_doctor_would_check_out_is_validated pins that order in its docstring ("clones this checkout first, then checks the ref, and refuses before git checkout"), the old rule had it for a..b too, and this PR changes the rule and its words only. Moving checked_ref above the clone is a one-line change for a later issue. rv874 confirmed it with a probe on an installed copy: --doctor with OPENREPOSHAPE_REF set to each of the five names shows 1 git clone and 0 checkouts, then the new refusal. Both go to Brett Heap as candidates; nothing is filed without his word.
• A scaffold run's $OPENREPOSHAPE_REF, only set for the run and not recorded, is asked its characters before the fetch (refuse_bad_values, openRepoShape: --version and two fetch refusals print $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF with no check, so an escape or a bidi override in either reaches the terminal as typed, and a scaffold run sends its fetch with them #866, by design). A ref this rule refuses never reaches setup.sh's check: the fetch of setup.sh at such a ref fails first (2 requests, gh api .../contents/setup.sh?ref=a.lock/b and then curl, at the base and at the head alike), and the run ends could not fetch setup.sh, with nothing cloned. That is openRepoShape: --version and two fetch refusals print $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF with no check, so an escape or a bidi override in either reaches the terminal as typed, and a scaffold run sends its fetch with them #866's design, and this PR does not move it.
• No documentation states the rule (docs/cli.md's --shape-ref help, the README, the handbook and the release notes were grepped for it), so none is touched, and no --help text changed.

Fix round 1, on rv874's review (READY, 2 SHOULDs, 6 NITs)

rv874's review of a1fa6768: #875 issuecomment-6246173536. No MUST. The fix round is 8d6c5bdb, on top of the restack; nothing was rebased, amended or force-pushed.

#	finding	what was done
SHOULD 1	REF_PARTS has no part that starts upper-case, _ or -, so three over-refusing mutants pass all 33 rows	Feature/ABC-123, fix/_tmp and fix/-wip join the "still pass" group (tests/conftest.py). With the three rows deselected the mutants pass 33 rows in each copy; with them: setup.sh + */[-_]* fails fix/_tmp and fix/-wip; install.sh + */[A-Z]* fails Feature/ABC-123; openRepoShape with [!a-z0-9]* fails Feature/ABC-123. All three tables pass: 108 rows
SHOULD 2	src/openreposhape/standard.py:198-219 keeps the old rule and sentence, and its docstring says it has the launcher's words	Not changed: a follow-up for Brett Heap. rv874's probe is in Not changed
NIT 3	a/b. and a/. sat under "Refused before #874 as well", but the old line took both	Both moved up with the issue's names (the 13 rows the old line takes now come first, as the docstring says). The body's lists are fixed above
NIT 4	setup.sh's comment: why_not_a_ref, #874 reads as #874's, and "one pattern for each" is not exact	Now "(#857's why_not_a_ref, held here since #874)" and "one or two patterns for each"
NIT 5	install.sh:161 says "before any request", untrue with no version named (releases/latest is asked first)	Now "before the launcher is fetched"
NIT 6	this body said setup.sh's check follows the fetch, which is untrue for a ref the rule refuses	The body only: the "Not changed" bullet now says the fetch fails first (2 requests, could not fetch setup.sh), and that it is #866's design
NIT 7	the sentence says "letters" where #873's REF_RE words say "ASCII letters"	The sentence is now a ref starts with an ASCII letter or digit, uses only ASCII letters, digits, ... in setup.sh, install.sh, openRepoShape and REF_RULE_WORDS, byte for byte the same (REF_RULE_WORDS is found once in each file). #873's phrase is "an ASCII letter or digit first, then ASCII letters, digits". setup.sh's comment says it too. Mutant: the lead cut back to a letter or digit fails the 19 refused rows in each copy. No other test pinned the words
NIT 8	openRepoShape:834 clones before :839 checked_ref	Not changed: a follow-up for Brett Heap. rv874's probe is in Not changed

Runs after the fix round, /usr/bin/git 2.43.0: batch 1 561 passed, batch 2 735 passed (1296; 1287 before, at a1fa6768). All 33 mutants are caught again (11 per copy, listed in Tests).

Closes #874

🤖 Generated with Claude Code

Summary by Sourcery

Reject Git-invalid ref parts consistently across the shell entry points before any clone, fetch, or record operation.

Bug Fixes:

• Align ref validation in setup.sh, install.sh, and openRepoShape with Git’s part-by-part branch-name rules, preventing invalid refs from reaching cloning, fetching, or recording.

Enhancements:

• Update rejection messages and setup comments to explain the complete Git-compatible ref rule.
• Add shared table-driven coverage that compares all three shell copies against the Git version available in the test environment, including checks for side effects and rejection wording.

Tests:

• Add comprehensive tests for valid and invalid ref parts across setup.sh, install.sh, and openRepoShape, including network, clone, and recording guards.

[sourcery-ai]

Reviewer's Guide

The PR updates setup.sh, install.sh, and openRepoShape to enforce Git's branch-ref rules part by part, with consistent explanatory refusals and pre-side-effect validation, and adds shared parameterized tests that compare all three copies against the Git executable.

Sequence diagram for Git-compatible ref validation before side effects

sequenceDiagram
    participant User
    participant Script as setup.sh_or_install.sh
    participant GitOrCurl as Git_clone_or_curl
    participant Record as openRepoShape_record

    User->>Script: provide ref
    Script->>Script: checked_ref_or_checked_version
    alt ref violates Git's part-by-part rules
        Script-->>User: refuse with Git rule
        Note over Script,GitOrCurl: No clone, fetch, or record
    else ref accepted
        alt setup.sh
            Script->>GitOrCurl: git clone
        else install.sh
            Script->>GitOrCurl: curl version URL
        else openRepoShape --install
            Script->>Record: write openRepoShape.ref
        end
    end

Loading

Flow diagram for the shared Git ref rule

flowchart TD
    A[Ref input] --> B{Matches any Git-invalid part pattern?}
    B -->|Yes| C[Refuse with explanatory rule]
    B -->|No| D[Continue to clone, fetch, or record]
    E[Invalid patterns] --> E1[Starts with . after /]
    E --> E2[Part ends in .lock]
    E --> E3[Empty part between slashes]
    E --> E4[Name ends in .]
    E --> E5[Contains ..]
    E1 --> B
    E2 --> B
    E3 --> B
    E4 --> B
    E5 --> B

Loading

File-Level Changes

Change	Details	Files
Align all three shell-side ref validators with Git's per-part branch-name rules and reject invalid refs before side effects.	Added matching Bash patterns for dot-prefixed parts, .lock-suffixed parts, empty or trailing slash parts, and names ending in .. Updated refusal messages and setup documentation to explain the complete Git-derived rule. Preserved existing character, length, control-character, repository, and opt-in recording behavior.	install.sh setup.sh openRepoShape
Added shared, Git-backed parameterized coverage for ref acceptance, refusal wording, and side-effect ordering.	Added a 33-entry ref table and helpers that compare each copy directly with git check-ref-format --branch. Verified setup rejects before cloning, install rejects before curl, and launcher install rejects before recording. Asserted the common rule sentence and retained coverage for repository/ref control-character handling and accepted fork names.	tests/conftest.py tests/test_setup_sh.py tests/test_install_sh.py tests/test_openreposhape_command.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#874	Make setup.sh, install.sh, and openRepoShape reject refs Git refuses part by part before their respective clone, fetch, or record side effects.	✅
#874	Update each refusal message and setup.sh’s comment to describe the per-part ref rule accurately.	✅
#874	Add table-driven checks comparing all three shell copies with Git’s ref-format decision, and verify them under Git 2.43 and 2.47.1 alongside the requested Linux tests.	❌	The PR adds table-driven tests that compare each copy with the Git on PATH and reports the requested Linux test suites passing, but it reports running only Git 2.43.0—not Git 2.47.1 as the issue’s verification checklist requests.

Possibly linked issues

• setup.sh, install.sh and the openRepoShape command: each keeps its own copy of the old ref rule (*..* | *.lock), so a ref git refuses part by part (a.lock/b, a/.b, a//b) clones the standard before it fails #874: The PR adds per-part ref checks and matching refusal messages to all three shell entry points named in the issue.

---

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-2, 2026-10-18T05:38:08Z) Independent review of #875 (#874) at a1fa6768, for lane openRepoShape-2: READY

No MUST. The change does what the issue asks. In each of the three copies it refuses exactly what git check-ref-format --branch refuses inside the character set, with one exception, HEAD, where the copies are right (see below). Nothing that git takes is now refused. The sentence is the same in all three copies, and every run is green.

Next: lane 2's writer takes SHOULD 1 and NITs 3 to 7 in a fix round. SHOULD 2 and NIT 8 go to Brett Heap as candidates; nothing is filed without his word.

SHOULD

1. tests/conftest.py:2359-2381 (REF_PARTS): three over-refusing mutants survive. No row has a part that starts with an upper-case letter, _ or -. Each of these mutants passed all 33 rows of its copy's table test:

   • setup.sh: add */[-_]*. It refuses fix/-wip and fix/_tmp, which git takes.
   • install.sh: add */[A-Z]*. It refuses feature/ABC-123.
   • openRepoShape: change [!A-Za-z0-9]* to [!a-z0-9]*. It refuses Feature/ABC-123.
   • Fix: add ("Feature/ABC-123", True), ("fix/_tmp", True), ("fix/-wip", True) to the "still pass" group. Measured with those three rows: the three tables pass at the head (108 passed), and all three mutants are killed (rows fix/_tmp and fix/-wip; Feature/ABC-123; Feature/ABC-123).

2. src/openreposhape/standard.py:198-219: a follow-up, not a change to this PR.

   • The package's ref_fault keeps the old rule (:215) and the old sentence (:219).
   • Its docstring (:200) says it is "the launcher's ref_fault, in its order and its words". That stops being true when this PR lands.
   • Probe: a detached copy of the head's package, with OPENREPOSHAPE_REPO a local clone, running --doctor .. For each of a.lock/b, a/.b, a//b, a/b/ and a., GIT_TRACE shows 1 git clone into the cache. The run then ends REFUSED: cloned ... but could not check out 'a.lock/b': fatal: invalid reference: a.lock/b. topic.lock is refused before any clone.
   • Fix: its own issue, as the PR body says.

NIT

3. tests/conftest.py:2366-2368: a comment contradicts its own docstring.

   • The comment "Refused before setup.sh, install.sh and the openRepoShape command: each keeps its own copy of the old ref rule (*..* | *.lock), so a ref git refuses part by part (a.lock/b, a/.b, a//b) clones the standard before it fails #874 as well, and refused still." heads the rows a/b. and a/.. The old line took both: the docstring at :2357-2358 says so, and they are 2 of the 13 rows that fail on the base.
   • The PR body's list "Still refused by the whole-name rules" repeats the error.
   • Fix: move the two rows up into the issue's group.

4. setup.sh:215 and :220: two loose phrases in the comment.

   • "(why_not_a_ref, setup.sh, install.sh and the openRepoShape command: each keeps its own copy of the old ref rule (*..* | *.lock), so a ref git refuses part by part (a.lock/b, a/.b, a//b) clones the standard before it fails #874)" reads as if why_not_a_ref came from setup.sh, install.sh and the openRepoShape command: each keeps its own copy of the old ref rule (*..* | *.lock), so a ref git refuses part by part (a.lock/b, a/.b, a//b) clones the standard before it fails #874. It is setup-project.py: a passed-through -- --dry-run still offers gh auth setup-git, which writes the person's global git config on a typed yes, and checked_ref passes a.lock/b, which git refuses #857's, landing with setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873.
   • "one pattern for each" is not exact. An empty part takes two patterns (*//*, */), and so does a .lock part (*.lock, *.lock/*).
   • Fix: write "(setup-project.py: a passed-through -- --dry-run still offers gh auth setup-git, which writes the person's global git config on a typed yes, and checked_ref passes a.lock/b, which git refuses #857's why_not_a_ref, held here since setup.sh, install.sh and the openRepoShape command: each keeps its own copy of the old ref rule (*..* | *.lock), so a ref git refuses part by part (a.lock/b, a/.b, a//b) clones the standard before it fails #874)" and "one or two patterns for each".

5. install.sh:161: "before any request" is not true when no version is named.

   • With no version, the releases/latest request (and the gh api fallback) runs before checked_version "$version" "the newest release's tag" (install.sh:589).
   • Fix: write "before the launcher is fetched".

6. PR body, "Not changed": one sentence is not true for any ref the rule refuses.

   • The sentence: "Its fetch of setup.sh is followed by setup.sh's own check, which now holds the rule."
   • A fetch of setup.sh at a ref git refuses cannot succeed, so setup.sh's check is never reached.
   • Probe: an installed copy running OPENREPOSHAPE_REF=a.lock/b openRepoShape --org demoorg Sample sends 2 requests at both the base and the head (gh api .../contents/setup.sh?ref=a.lock/b, then curl). It then refuses with could not fetch setup.sh. Nothing is cloned.
   • This is openRepoShape: --version and two fetch refusals print $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF with no check, so an escape or a bidi override in either reaches the terminal as typed, and a scaffold run sends its fetch with them #866's design.
   • Fix: say that in the body.

7. The first half of the shared sentence says "letters" where setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's REF_RE words say "ASCII letters" (setup-project.py: a refused project name gets one sentence that explains only a leading -, a trailing space passes where a leading one is refused and hides in step (4)'s report, and a name of 101 to 255 characters passes the prompt, to end at step (5) or at GitHub #777, rv811).

   • Under LC_ALL=C.utf8, --shape-ref Café is refused with "uses only letters, digits, ...", but é is a letter.
   • The words predate this PR, and Decision 5 keeps them.
   • Optional fix: "starts with an ASCII letter or digit, uses only ASCII letters, digits, ..." in all three copies and in REF_RULE_WORDS.

8. openRepoShape:834 clones before :839 checked_ref in shape_checkout: a follow-up candidate, unchanged here.

   • Probe at the head: an installed copy running --doctor with OPENREPOSHAPE_REF set to a.lock/b, a/.b, a//b, a/b/, a. or topic.lock. GIT_TRACE shows 1 git clone and 0 checkouts, and then the new refusal.
   • Fix: move checked_ref above the clone, in a later issue.

Checked and true

• The rule matches git's, with one exception (HEAD).

  • Each copy's case line was read out of its file at the head and run by /bin/bash, against /usr/bin/git check-ref-format --branch (2.43.0). The names tried:
    • 29,571 names of up to five atoms from a, Z, _, 0, ., /, -, .lock and HEAD;
    • 6,121 names of up to four atoms from the same set plus lock;
    • 50 named cases, among them v1.0.0-rc.1, release/1.2, a-/b, _x and x_ in each part, digit-only parts, names of 255 characters, a 40-hex sha in both cases, HEAD, refs/heads/HEAD and FETCH_HEAD.
  • Result: one disagreement in each copy, HEAD. The base line disagrees on 1,429 of the 6,121 names.
  • The writer's 3,110 names, re-run: 0 disagreements for the new line, 1,122 for the old.

• The copies agree with setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's rule on every name. setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's rule is REF_RE plus why_not_a_ref, imported from setup-project.py at ac570069. They agree on all 29,571 names, HEAD included.

• Where --branch is the wrong yardstick:

  • HEAD only. --branch refuses it, because it would be refs/heads/HEAD. The copies and setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873 take it, and that is right: git checkout HEAD works, and a raw URL at HEAD names the default branch. No table row can hold HEAD under this oracle.
  • For a tag, git's rule for refs/tags/<name> is the branch rule minus the HEAD case, so --branch is right in this character set.
  • A commit sha is well formed under every rule. Both cases of a 40-hex sha and abc1234 are taken, and nothing here asks whether the commit exists.
  • workBenches' sentinel is well formed and is taken by git and by all three copies; it is meant to fail later.

• The order of the patterns cannot matter. They are alternatives in one case clause, so every order gives the same match. Reversing them passes all rows; the mutant is equivalent by construction.

• The sentence is the same and true in all three. Hashed from the die and printf lines, it is byte-identical in all three refusals. It names every one of the nine patterns, and its new clauses use setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's phrases.

• setup.sh's comment is true once setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873 lands. At main, setup-project.py:475 still has the old rule, which is why the PR lands after setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873.

• No doc states the old rule. It appears only at src/openreposhape/standard.py:219. docs/cli.md:96 and :231 say only "clone this commit or tag", and no --help text states the rule.

• What each copy gates, probed at the base 145a5ee3 and at the head for a.lock/b, a/.b, a//b, a/b/ and a.:

  Copy	Base	Head
  setup.sh, piped	1 clone and 1 checkout, then exit 1 (pathspec ... did not match)	exit 2, 0 clones
  install.sh, run as a file and piped	1 curl request with the ref in the URL	exit 2, 0 requests
  launcher --install with the opt-in	exit 0, the ref recorded	exit 2, nothing recorded
  launcher reading a hand-written record	--version prints @ a.lock/b	exit 2, 0 requests

  topic.lock is refused and main is taken by all three, at both.

• Merges. main 5c54af20 and openRepoShape: $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF are checked once, before --version answers and before any fetch, so a control character or a character a terminal draws as another in either is refused, never printed or sent #872's head a2af74a0 are ancestors of the head. Merging setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873 (ac570069) conflicts only in setup-project.py and tests/test_setup_project_typed_name.py. main and setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873 conflict on those same two files without this PR, and setup.sh, install.sh and openRepoShape: a ref git refuses part by part (a.lock/b, a/.b, a//b, a/b/, a.) is refused by each of them before the clone, the fetch or the record, and each refusal states git's rule #875 touches neither.

• The restack holds. git diff 5c54af2 a1fa6768 and git diff 89be75bf 17185b67 are byte-identical (cmp), index lines included. The squash tree is a4b0a79d, which equals 0ccda48b's tree.

• The tests are sound.

  • git_takes_ref runs git each time and copies nothing.
  • The three table tests are offline by construction: the setup.sh test clones a path where nothing exists; the install.sh test runs under its own fakes; the launcher test copies the command from its file and asks only gh auth status, which goes to the fake.
  • There is no composite assert.
  • No 4-line window of the added test lines appears anywhere else in tests/.
  • shellcheck warnings are the same at base and head (5, 0 and 8).

• Runs: 555 and 732 passed at the head, 489 and 699 at the base 145a5ee3. The difference is the three new tests at 33 rows each. The new tests against the base's three copies: 57 failed and 42 passed, as the body says.

• Mutants: six of the writer's (two per copy) are killed with the rows the body lists. Of the reviewer's, the over-refusal */.* → */*.* is killed by refs/tags/v1.0 and a/b.lockb/c, and *.lock/* → *.lock* is killed by 4 rows.

Could not verify

• git 2.47.1 and CI's git: only /usr/bin/git 2.43.0 was run. The tests ask the git that runs them.
• That GitHub's contents API takes ref=HEAD: there was no network.
• bash 3.2: not available here. The new patterns are plain *, . and / globs.
• Windows and macOS: CI is Linux only (ci: run the test suite on Linux only #597).

Lane: openreposhape-2 (openRepoShape-2)

[brettheap]

(lane openRepoShape-2, 2026-10-18T06:13:13Z) Re-verification of #875 (#874)'s fix round 1 at 8d6c5bdb: READY

Every finding from the first review is fixed as asked, or left as a candidate for Brett Heap as agreed. All runs are green. The fix round's code and tests are right. There is one new SHOULD and one NIT, both in text outside the code.

SHOULD

1. The squash subject drops the issue number.
   • squash-message.md (lane 2's attachment) has a first line ending ... states git's rule (#875).
   • Lane 2's other squash messages, and main's log, end with the issue and then the PR, as install.sh and openRepoShape: a $OPENREPOSHAPE_BIN_DIR the bytes refuse is read again in the locale's own charset, so a GB18030, GBK or Shift_JIS name that holds no control character and nothing drawn as another is placed, and where nothing can read it the bytes decide as before #867's (#858) (#867) and openRepoShape: $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF are checked once, before --version answers and before any fetch, so a control character or a character a terminal draws as another in either is refused, never printed or sent #872's (#866) (#872) do.
   • Fix: end the subject ... states git's rule (#874) (#875).
   • Applied: lane 2 changes the squash message's subject. No code changes.

NIT

2. tests/conftest.py:2366-2367: one comment's lead-in is loose.
   • The comment reads "The same kind, and taken by the old line too". It follows rv873's group, "a part that starts with .". a/. is of that kind, but a/b. is not.
   • Fix: say "Of the issue's kind", as the PR body's list does.
   • Lane 2 leaves it on record. It is a comment in a test, and a new commit would need a new gate.

Checked and true

• The delta a1fa6768..8d6c5bdb is one commit and four files (setup.sh, install.sh, openRepoShape, tests/conftest.py). Each finding was checked line by line:
  • SHOULD 1: the three rows Feature/ABC-123, fix/_tmp and fix/-wip are now in REF_PARTS.
  • NIT 3: a/b. and a/. now sit with the issue's names. The 13 names the old line took come first, and the docstring says "the first thirteen names below".
  • NIT 4: setup.sh's comment says "(setup-project.py: a passed-through -- --dry-run still offers gh auth setup-git, which writes the person's global git config on a typed yes, and checked_ref passes a.lock/b, which git refuses #857's why_not_a_ref, held here since setup.sh, install.sh and the openRepoShape command: each keeps its own copy of the old ref rule (*..* | *.lock), so a ref git refuses part by part (a.lock/b, a/.b, a//b) clones the standard before it fails #874)" and "one or two patterns for each".
  • NIT 5: install.sh's note says "before the launcher is fetched".
  • NIT 6: the body's "Not changed" bullet now says the fetch fails first, with 2 requests, and that this is openRepoShape: --version and two fetch refusals print $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF with no check, so an escape or a bidi override in either reaches the terminal as typed, and a scaffold run sends its fetch with them #866's design.
  • NIT 7: the sentence now begins "a ref starts with an ASCII letter or digit, uses only ASCII letters, ...".
  • SHOULD 2 and NIT 8 are left alone as candidates for Brett Heap, and the body records the probes.
  • The pattern lines are unchanged.
• The sentence is the same everywhere. Hashed from the die and printf lines, it is byte-identical in the three copies. It appears once in each, and it equals REF_RULE_WORDS (cmp).
• The sentence matches setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's words. It agrees with setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's REF_RE phrase at ac570069, "an ASCII letter or digit first, then ASCII letters, digits and ._/-".
• The Café case now reads true. Under LC_ALL=C.utf8, --shape-ref Café is refused with "uses only ASCII letters".
• The three over-refusing mutants from the first review are now killed:
  • setup.sh with */[-_]* added, by fix/_tmp and fix/-wip;
  • install.sh with */[A-Z]* added, by Feature/ABC-123;
  • openRepoShape with [!a-z0-9]* in place of [!A-Za-z0-9]*, by Feature/ABC-123.
• The tables pass: 36 rows in each of the three tests.
• The widened enumeration still finds only HEAD. It was re-run against the three copies at 8d6c5bdb: 29,571 names and 6,121 names. Each copy disagrees with git check-ref-format --branch on HEAD alone, and with setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873's REF_RE plus why_not_a_ref on none.
• Other mutants:
  • The two word mutants on the "ASCII" lead are each killed by the 19 refused rows.
  • The old line put back is killed by 13 rows in setup.sh and in openRepoShape.
  • The patterns in reverse order still pass every row. That mutant is equivalent: the patterns are alternatives in one case clause.
• The new tests against the base's three copies: 57 failed and 51 passed (19 names fail in each copy; 17 names pass, three times).
• The two batches at 8d6c5bdb: 561 and 735 passed, 1,296 in all, which is 9 more than at a1fa6768. This matches the body's "Fix round 1" table and its counts.
• Merges:
  • main moved to fc289dd7, four commits since 5c54af2, which touch setup-project.py and tests/conftest.py. The merge with the head is clean (tree 07b98c23). On a probe merge commit, the PR's three test files plus test_setup_project_py gave 1,072 passed.
  • openRepoShape: $OPENREPOSHAPE_REPO and $OPENREPOSHAPE_REF are checked once, before --version answers and before any fetch, so a control character or a character a terminal draws as another in either is refused, never printed or sent #872's head a2af74a0 is still an ancestor of the head.
  • Merging setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873 ac570069 conflicts only in setup-project.py and tests/test_setup_project_typed_name.py. main and setup-project.py: a passed-through --dry-run makes none of the preflight's offers and --shape-ref is held to git's rule part by part, so a rehearsal no longer writes git's global config and a.lock/b is refused before the clone (#857) #873 conflict on those same two files without this PR.
• The trailer: 8d6c5bdb and the squash message carry Co-Authored-By: Claude Sonnet 5.5. Lane 2's agent record shows the writer ran on Sonnet 5.5, so the trailer is right.

Could not verify

• git 2.47.1 and CI's git: only /usr/bin/git 2.43.0 was run.
• bash 3.2, Windows and macOS: none are available here.

Lane: openreposhape-2 (openRepoShape-2)

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