[brettheap]

Lane: openreposhape-1 (openRepoShape-1)
Claim: #417 (comment)

What

adopt-project.py check takes --local-remote-dir: the directory execute --local-remote-dir will be given. With it, check resolves each relative submodule url the plan keeps in a leg from the bare repository execute would create there, as execute does. Given the same directory, the two commands now give one verdict, line for line, in both of the issue's layouts.

• The flag. cmd_check reads it with getattr(args, "local_remote_dir", None), as _work_root reads work_dir (tests/test_adopt_entry_paths.py calls cmd_check with a Namespace that has no such attribute), and passes it to _entry_findings. That is the one list check prints and execute's _refuse_what_check_finds refuses. _relative_url_findings already took the directory, and already drops its NOTE when it is set. adopt-project.py keeps a source submodule's relative url = ../x unchanged in the leg, where git resolves it against the leg's remote, so execute says adoption verified and the assembly's recursive clone fails unless the dependency happens to sit beside the leg #190's and adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245's resolution logic is unchanged, and so is one finding per cause.
• The topics line. Given the flag, check's WHAT WILL HAPPEN block prints the topics line of the run it checks, topics skipped for local remotes, through the local parameter _print_what_will_happen already had.
• adopt-project.py says adoption verified when a submodule the plan keeps in a leg has a url that names no repository (a relative url that resolves alike from the source and the leg, or an absolute one), so the recursive clone its NEXT: line prints fails; nothing asks whether the url answers #418's NOTE. Given the flag, the NOTE about urls check does not ask still names a url on a network. _unanswered_url_findings dropped that NOTE whenever local_remote_dir was set. Only execute ever passed one, and execute prints no NOTEs, so the condition first mattered once check took the flag. It is gone, with the parameter it used.
• Without the flag check resolves from GitHub's remotes as before. Its findings and exit codes are unchanged, and so is everything it prints, but for the reworded NOTE and the two reworded remediations below.
• Nothing is created. check --local-remote-dir makes no directory and no leg. It reads the disk there only for adopt-project.py says adoption verified when a submodule the plan keeps in a leg has a url that names no repository (a relative url that resolves alike from the source and the leg, or an absolute one), so the recursive clone its NEXT: line prints fails; nothing asks whether the url answers #418's question: whether each relative url, resolved from the bare repositories execute would create there, names a repository git ls-remote reaches.

Wording. Each place that said check always resolves from GitHub's remotes now says where each run resolves from:

• The NOTE check prints when every relative url names one repository from GitHub's legs now ends: "...a url that names another repository; check, given the same --local-remote-dir, resolves it there too."
• RELATIVE_URL_REMEDIATION now ends: "check and execute resolve it from the leg remotes execute would create: the GitHub repositories the plan's org: names, or, under --local-remote-dir, the bare repositories there, which check asks only when given the same --local-remote-dir. execute resolves it again before it creates any leg." It used to say that check's plan ok "settles nothing" there.
• URL_ANSWERS_NOTHING_REMEDIATION (adopt-project.py says adoption verified when a submodule the plan keeps in a leg has a url that names no repository (a relative url that resolves alike from the source and the leg, or an absolute one), so the recursive clone its NEXT: line prints fails; nothing asks whether the url answers #418) now ends: "a relative one is resolved from the leg's remote, which is on GitHub, or, under --local-remote-dir, the bare repository execute would create there."
• The first line of execute --local-remote-dir's refusal (_as_resolved_here): "N finding(s) in , as check prints them given the same --local-remote-dir, with each relative submodule url resolved from the leg remotes this run would create there:".
• Docstrings and comments: the module docstring (twice), _FromTheLeg, _relative_url_findings, _unanswered_url_findings, _entry_findings, _remote_urls, _refuse_what_check_finds, _as_resolved_here, and the comments "WHERE check ASKS" (split branch, adopt-project.py: plan, check and execute never look for the plan's split branch (adopt/three-repo-shape) in the repository the split is pushed to, so a re-run after an earlier run left it passes check, creates both legs, and dies at a non-fast-forward push of the split #320) and "THE CLONE URL IS execute'S OWN". The first said that check does not know whether --local-remote-dir will be passed, and the second that check has no such flag; both now say that check's own flag is not read there.

docs/cli.md is regenerated with scripts/render-cli-reference.py, so check's usage and options list the flag. tests/test_cli_reference.py passes.

Why (repro on main)

The issue's script, with a check --local-remote-dir line added and --project Thing in layout B (since #499, plan refuses --project Northwind there as adopt-not-the-source, the source's origin being testorg/Thing), run on main da48256c (the branch's base) and again on this branch's head. Main 78fe3fff prints the same lines as da48256c, and this branch merged with it the same lines as the head. git 2.43.0, Python 3.12.3, local only, with a stub gh first on PATH, GIT_CONFIG_GLOBAL=/dev/null and GIT_ALLOW_PROTOCOL=file. <T> is the run's scratch directory.

On main:

== layout A: origin <T>/remotes/Thing.git, url ../dep, project Northwind
check exit 1: FINDING plan-submodule-relative-url
check --local-remote-dir exit 2: unrecognized arguments: --local-remote-dir <T>/remotes
execute exit 0: adoption verified, leg repositories made: 2
the assembly's recursive clone: exit 0
== layout B: origin git@github.com:testorg/Thing.git, url ../dep, project Thing
check exit 0: plan ok
check --local-remote-dir exit 2: unrecognized arguments: --local-remote-dir <T>/remotes
execute exit 2: REFUSED plan-submodule-relative-url, leg repositories made: 0

On this branch:

== layout A: origin <T>/remotes/Thing.git, url ../dep, project Northwind
check exit 1: FINDING plan-submodule-relative-url
check --local-remote-dir exit 0: plan ok
execute exit 0: adoption verified, leg repositories made: 2
the assembly's recursive clone: exit 0
== layout B: origin git@github.com:testorg/Thing.git, url ../dep, project Thing
check exit 0: plan ok
check --local-remote-dir exit 1: FINDING plan-submodule-relative-url
execute exit 2: REFUSED plan-submodule-relative-url, leg repositories made: 0

In layout B, check --local-remote-dir's finding and the line under execute's refusal are the same text:

FINDING plan-submodule-relative-url: the submodule `vendor/lib` (entry `vendor/`) has leg: code, and its url in the source's .gitmodules is the relative `../dep`, which git resolves against the remote of the repository holding that file: from the source, at `git@github.com:testorg/Thing.git` (its remote `origin`), to `git@github.com:testorg/dep`, and from the code leg, at `<T>/remotes/Thing-code.git`, to `<T>/remotes/dep`; the assembly's recursive clone resolves it from the leg
REFUSED plan-submodule-relative-url: 1 finding(s) in <T>/plan.yaml, as `check` prints them given the same --local-remote-dir, with each relative submodule url resolved from the leg remotes this run would create there:
  FINDING plan-submodule-relative-url: (the same text)

How

• main(): check gains --local-remote-dir (type=Path, default None), as execute has it.
• cmd_check: local_remote_dir = getattr(args, "local_remote_dir", None), passed to _entry_findings and, as local, to _print_what_will_happen.
• _unanswered_url_findings: drops its local_remote_dir parameter and the condition that dropped the NOTE under one. _submodule_findings calls it without the parameter.
• The texts above, and docs/cli.md.

Tests

New and changed tests, in tests/test_adopt_relative_submodule_url.py and tests/test_adopt_submodule_url_answers.py:

• New: test_check_and_execute_given_one_local_remote_dir_agree[A-local-origin, B-github-origin]. These are the issue's two layouts end to end (they need git filter-repo). check with no flag gives the opposite verdict in each. Given the directory, check's FINDING lines equal execute's. In A, check passes, execute verifies and the recursive clone checks the dependency out. In B, check exits 1, execute exits 2, and neither makes a leg.
• New: test_check_given_local_remotes_still_notes_a_url_on_a_network. Under check --local-remote-dir, adopt-project.py says adoption verified when a submodule the plan keeps in a leg has a url that names no repository (a relative url that resolves alike from the source and the leg, or an absolute one), so the recursive clone its NEXT: line prints fails; nothing asks whether the url answers #418's NOTE still names an https:// url check did not ask.
• Extended (these run in both modes, without git filter-repo):
  • test_execute_resolves_again_from_the_remotes_it_would_create (x4, layout B): check --local-remote-dir exits 1 with the refusal's FINDING lines, makes nothing, and the refusal's new first line and remediation are asserted.
  • test_a_relative_origin_resolves_from_the_source_working_tree (x2, layout A): check --local-remote-dir passes for the directory beside the dependency and prints topics skipped for local remotes; for another directory it finds, line for line, what execute refuses.
  • test_execute_refuses_a_relative_url_that_names_nothing_from_either_side: asserts the new URL_ANSWERS_NOTHING_REMEDIATION wording.
• Reworded asserts: the alike() NOTE, FROM_THE_LOCAL_LEGS and three docstrings.

Before the fix, 16 of these tests fail, with the new tests on main's adopt-project.py. With it, the two files and tests/test_cli_reference.py give 78 passed.

Revert table. Each change is reverted alone in a standalone clone, with the new tests in place and git filter-repo on PATH, over the two test files and tests/test_cli_reference.py (78 tests):

reverted	failed	which
nothing (head 9bd5585)	0	78 passed
R1: check's --local-remote-dir argument	14	test_execute_resolves_again... x4, test_a_relative_origin... x2, test_check_and_execute_given_one_local_remote_dir_agree x2, test_check_given_local_remotes_still_notes_a_url_on_a_network, and 5 in test_cli_reference.py (docs/cli.md lists the flag)
R2: cmd_check passes the flag to _entry_findings	9	the same 9 adopt tests as R1
R3: the topics line follows the flag	2	test_a_relative_origin... x2
R4: #418's NOTE dropped under a local_remote_dir	1	test_check_given_local_remotes_still_notes_a_url_on_a_network
R5: the relative-url NOTE's new clause	6	test_check_keeps_a_relative_url_its_github_leg_resolves_alike x5, test_each_relative_url_is_resolved_on_its_own
R6: the refusal's first line	5	test_execute_resolves_again... x4, test_execute_refuses_a_relative_url_that_names_nothing_from_either_side
R7: RELATIVE_URL_REMEDIATION	4	test_execute_resolves_again... x4
R8: URL_ANSWERS_NOTHING_REMEDIATION	1	test_execute_refuses_a_relative_url_that_names_nothing_from_either_side
all (main's adopt-project.py and docs/cli.md)	16	every new and reworded test

Chained together, R1 to R8 leave only docstrings, comments and the now-unused getattr line different from main.

Targeted runs at head 9bd5585, dirty 0, with /usr/bin/python3 -m pytest, a stub gh first on PATH, a bogus GH_TOKEN and an empty GH_CONFIG_DIR. They cover 87 files: the 86 that grep -l -E 'adopt-project|adopt_project|\bADOPT\b' tests/*.py names, which include tests/test_shape_doctor.py and tests/test_scaffold_leg_path_collisions.py, plus tests/test_cli_reference.py.

• With git filter-repo on PATH: 6391 passed, 13 skipped, EXIT=0 (61 min).
• With it hidden (PATH=<stub>:/usr/local/bin:/usr/bin:/bin): 6045 passed, 359 skipped, EXIT=0 (45 min).

Windows

CI is Linux only since #597, so this was not run on Windows. Even so:

• The new tests read nothing back as bytes. Every path they make is a tmp_path name or a fixed ASCII name (remotes, Thing.git, dependency, elsewhere, clone), legal on NTFS.
• The new helper finding_lines compares lines from splitlines(), which takes \r\n too. str.removeprefix is Python 3.9, the oldest version this standard runs on.
• The url in the new adopt-project.py says adoption verified when a submodule the plan keeps in a leg has a url that names no repository (a relative url that resolves alike from the source and the leg, or an absolute one), so the recursive clone its NEXT: line prints fails; nothing asks whether the url answers #418 test is an https:// url, which no platform asks.

Not in this PR

• check --local-remote-dir uses the directory for each relative submodule url alone: where it is resolved, and whether it answers there (adopt-project.py says adoption verified when a submodule the plan keeps in a leg has a url that names no repository (a relative url that resolves alike from the source and the leg, or an absolute one), so the recursive clone its NEXT: line prints fails; nothing asks whether the url answers #418). It also prints the topics line of that run. It does not ask the other questions only execute --local-remote-dir asks. Each was measured with one plan and one directory, on this branch merged with main 78fe3fff: check --local-remote-dir says plan ok, and execute --local-remote-dir refuses leg-remote-exists for a <dir>/Northwind-code.git already there (after it has made Northwind-spec.git, which it leaves behind), adopt-unwritable-value for a source directory whose name is not UTF-8 (the clone URL), adopt-name-too-long for a --project of 248 characters (<dir>/<name>-code.git is 257 bytes), and plan-tracking-branch-missing for a tracking_branch that only the source's remote origin has (it asks the source itself). Where the directory is a file, or its parent cannot be written, execute ends in a traceback (exit 1) before any leg exists. The other way round, check --local-remote-dir still finds adopt-branch-exists or plan-split-branch-taken for a branch the source's origin, the assembly repository on GitHub, held when it was last fetched. Only execute without --local-remote-dir meets that branch, and execute --local-remote-dir verifies the plan. Each of these execute paths is unchanged here and the same on main 78fe3fff, and each is reported to Tracking: adopt-project.py, converting an existing repository in place #457's checklist.
• The issue's own "Not this issue": a kept submodule url that names no repository at all. adopt-project.py says adoption verified when a submodule the plan keeps in a leg has a url that names no repository (a relative url that resolves alike from the source and the leg, or an absolute one), so the recursive clone its NEXT: line prints fails; nothing asks whether the url answers #418 (PR adopt-project.py: a kept submodule url on this disk where git ls-remote reaches no repository is a finding execute refuses before any leg, so it no longer ends adoption verified over a recursive clone that fails (#418) #618) now finds one on this machine's disk. One on a network is still not asked, and the NOTE names it.

Known limits

• check answers for execute --local-remote-dir only when it is given the same directory. A relative --local-remote-dir is resolved from the directory each command runs in, as execute resolves it.
• check makes nothing in the directory, and asks the disk there only whether each relative url it resolves from it answers. Whether a leg is already there, and whether the directory can be made and written, are execute's to find (see "Not in this PR").

Closes #417

🤖 Generated with Claude Code

Summary by Sourcery

Make check --local-remote-dir resolve relative submodule URLs like execute so both commands consistently validate local-remote adoptions.

New Features:

• Add check --local-remote-dir so relative submodule URLs are evaluated against the same local bare repositories used by execute.
• Report local-remote execution context in check output and expose the option in the CLI reference.

Bug Fixes:

• Align check and execute verdicts for relative submodule URLs when both commands use the same local remote directory.
• Preserve network URL notes while correctly checking relative URLs against local remotes.

Enhancements:

• Update diagnostics and remediation text to describe URL resolution consistently across GitHub and local-remote modes.

Documentation:

• Regenerate the CLI documentation to include check --local-remote-dir.

Tests:

• Add end-to-end coverage verifying that check and execute agree line for line with shared local remotes.
• Extend relative-submodule and URL-answer tests for local remote resolution, output, and network notes.

[sourcery-ai]

Reviewer's Guide

The PR makes check --local-remote-dir model execute --local-remote-dir when resolving relative submodule URLs, while preserving GitHub-based behavior without the flag, and adds comprehensive documentation and tests proving matching verdicts and diagnostics.

Sequence diagram for matching check and execute local remote resolution

sequenceDiagram
    participant User
    participant Check as check
    participant Findings as _entry_findings
    participant Remotes as _remote_urls
    participant Execute as execute
    participant Disk as local_remote_dir

    User->>Check: --local-remote-dir
    Check->>Findings: _entry_findings(plan, source, local_remote_dir)
    Findings->>Remotes: resolve relative submodule URL
    Remotes->>Disk: read bare repository path
    Disk-->>Remotes: leg remote URL
    Remotes-->>Findings: resolved URL
    Findings-->>Check: findings and topics
    Check-->>User: plan ok or FINDING

    User->>Execute: --local-remote-dir
    Execute->>Findings: _refuse_what_check_finds(..., local_remote_dir)
    Findings->>Remotes: resolve relative submodule URL
    Remotes->>Disk: use remotes this run would create
    Disk-->>Remotes: leg remote URL
    Remotes-->>Findings: resolved URL
    Findings-->>Execute: matching findings
    Execute-->>User: verify or refuse before creating legs

Loading

Flow diagram for check local remote resolution modes

flowchart TD
    Start["check"] --> Flag{"--local-remote-dir given?"}
    Flag -->|No| GitHub["Resolve relative submodule URLs from GitHub leg remotes"]
    Flag -->|Yes| Local["Resolve relative submodule URLs from bare repositories in local_remote_dir"]
    GitHub --> Findings["_entry_findings"]
    Local --> Findings
    Findings --> Output["Print findings, remediation, and WHAT WILL HAPPEN"]
    Local --> Topics["Print topics skipped for local remotes"]
    Output --> Verdict["check verdict"]

Loading

File-Level Changes

Change	Details	Files
Add check --local-remote-dir support so relative submodule URLs are resolved against the same local bare repositories that execute would create.	Add the CLI option and safely read it for programmatic callers lacking the attribute. Thread the directory through entry findings and local-remote topic reporting. Reuse local repository resolution for relative URL findings, keeping GitHub resolution as the default. Align finding, remediation, NOTE, refusal, docstring, and comment wording with the new behavior.	adopt-project.py docs/cli.md
Expand coverage to verify that check and execute produce consistent verdicts and diagnostics for local remote layouts.	Add end-to-end tests for local-origin and GitHub-origin layouts, including adoption and recursive clone behavior. Assert finding-line equality between check and execute refusals. Cover local-mode topic output and preservation of NOTES for network URLs. Update existing expectations for refusal and remediation wording.	tests/test_adopt_relative_submodule_url.py tests/test_adopt_submodule_url_answers.py tests/test_cli_reference.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#417	Let check accept --local-remote-dir and use it to resolve kept relative submodule URLs from the same local bare-repository remotes as execute, so both commands agree when given the same directory.	✅
#417	Update CLI documentation and user-facing explanations to describe resolution behavior accurately, including that check uses local remotes only when given the flag and otherwise retains its GitHub-remote behavior.	✅

Possibly linked issues

• adopt-project.py check takes no --local-remote-dir and resolves a relative submodule url from GitHub's remotes, while execute --local-remote-dir resolves it from the bare repositories it creates, so under that test path check refuses an adoption execute verifies and passes one execute refuses #417: The PR adds the matching flag, passes it into finding checks, and tests both layouts so check agrees with execute.
• adopt-project.py check takes no --local-remote-dir and resolves a relative submodule url from GitHub's remotes, while execute --local-remote-dir resolves it from the bare repositories it creates, so under that test path check refuses an adoption execute verifies and passes one execute refuses #417: The PR implements the issue by letting check use execute's local bare remotes to resolve relative submodule URLs, matching verdicts in both reported layouts.

---

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.

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

[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