Share one path normalizer, home resolver and repository-root walk

[Mikola Lysenko (mikolalysenko)]

Problem

The architecture audit (§3.B, "Identity, equality and liveness checks") found the same path logic written many times, with rules that drift apart:

• Path normalizers. Twelve hand-rolled ./.. folding loops, each with its own rules (fail on escape, keep the escape, or ignore ..; one separator or both; a floor or none). One of them had a real bug: the pnpm crawler's copy let a second leading .. pop the first, because PathBuf::pop also removes a .. segment. So ../../x collapsed to x.
• Repository-root walks (B22). Three ancestor walks each decided which repository a directory belongs to:
  • policy::find_repo_root_with_warnings (socket.yml) honored .git files, the home-directory stop, GIT_CEILING_DIRECTORIES and owner trust.
  • VEX product detection (vex/product.rs find_git_config) only looked for <dir>/.git/config and walked all the way to /. Inside a submodule it named the superproject as the product; in a linked worktree it found no remote at all; a dotfiles repository at $HOME became the product of every project under it.
  • The JVM not_build_root check stopped at any .git, but crossed the home directory and the ceilings.
• B66. Home resolvers fell back to a relative path. utils::fs::home_dir returned the literal ~, and every caller (~/.cargo registry and config chain, nuget, deno, ruby, python user site-packages, pipx/uv/pdm/conda/pyenv roots) joined onto it, so the probes resolved against the working directory. The Maven default (m2_repo_path_with) had its own copy of the same fallback, so with no home the Maven local repository was ./~/.m2/repository inside the scanned project. The Python crawler's injected-env readers took an empty or relative HOME as-is.
• B74. get read pnpm-lock.yaml with a plain read_to_string. cargo_workspace and the maven checksum-sidecar reader did an lstat, then a blocking read: a hand-rolled copy of the regular-file guard with a check-then-open race.

No GitHub issue tracks these. They are audit IDs B22, B66 and B74, plus the §3.B duplication rows.

Change

1. utils::relpath. One segment stack (Segments) behind every lexical normalizer: resolve_rel(base, rel, floor) fails closed; normalize_rel_keeping_escapes keeps ../ so a containment check can name the escape; normalize_lexically / normalize_lexically_keeping_escapes do the same for Paths; is_anchored is the common absolute/drive check. Each format keeps only its own admission rule (gradle ~/:, sbt any .., cargo socket-owned prefix, and so on).
2. Home resolution (B66).
   • utils::fs::home_dir() -> Option<PathBuf> returns HOME, then USERPROFILE, when set and rooted, else None; callers probe nothing without a home. home_from_env applies the same rule to an injected environment.
   • Routed through it: coursier/ivy process_home, the go crawler, the ruby crawler's ambient_home, update::channel, the Maven ~/.m2 default (JvmEnv::m2_repo is now Option; every caller skips the Maven repo when there is none), and the Python crawler's pdm/poetry/expand_home seams. pipenv_home_dir keeps Python's own Windows precedence but now also rejects a relative value.
3. utils::repo_root. Holds search_dirs, ancestor_search_dirs, find_git_repo and GitRepo::config_path (follows a gitdir: file and a worktree's commondir), plus the owner-trust rule.
   • socket.yml lookup is a thin warning wrapper over it.
   • VEX product detection uses it. When the nearest checkout is owned by another user, or the walk stopped below a repository at the home directory, it now adds a warning to DetectResult::warnings instead of silently falling back to the manifest.
   • JVM not_build_root uses ancestor_search_dirs, which keeps walking past a checkout at the project itself (a submodule can still be a module of the build above it) but now stops at home and at the ceilings.
   • The vex --product help text now describes the nearest-checkout rule.
4. FIFO-safe reads (B74). get reads pnpm-lock.yaml with read_regular_to_string_sync. cargo_workspace::read_manifest and sidecars::maven::read_sidecar keep their lstat check (symlinks still not followed), then read through the non-blocking regular-file helpers.

Behavior changes to note

• Home stop precedence is unchanged from main. The repository walk's home stop reads HOME on Unix and USERPROFILE on Windows (git's rule, as the old policy code did), not the crawler resolver's HOME-then-USERPROFILE order. It now ignores a relative value.
• Crawler home precedence. home_dir keeps main's order (HOME, then USERPROFILE, on every platform). New: a relative or literal ~ value is skipped instead of used.
• JVM build-root walk. It climbs physical parents (project_root canonicalized, as git does), so a relative root like . now finds the reactor/Gradle/sbt build above it (the old lexical ancestors() saw none). For a symlinked project directory, the parents are those of the link target, not of the link. The refusal names the ancestor in the caller's own spelling when that spelling reaches it; otherwise it shows the canonical path without Windows' \\?\ prefix.
• The JVM build-root search no longer reads ~/settings.gradle, ~/pom.xml or ~/build.sbt when the project sits directly under $HOME (git's home rule).

Duplicate copies deleted

Concept	Before	After
./.. folding loops	12 (fs, npm_crawler private, npm_crawler yarnrc, cargo_workspace, gradle/mod, sbt/build, pypi_requirements, cargo_manifest, cargo_config, composer_crawler, vendor/jvm/gradle, jvm/maven_reactor)	1 (utils::relpath::Segments)
Repo-root ancestor walks	3 (policy, vex/product, maven_repo)	1 (utils::repo_root)
Owner-trust / ceiling / home-stop helpers	in policy only	moved to utils::repo_root (policy copy deleted)
"HOME then USERPROFILE" crawler home rules in core	9 (fs, go_crawler, ruby ambient_home, coursier process_home, update::channel, maven m2_repo_path_with, python pdm/poetry config, poetry cache/installer, expand_home)	1 rule (utils::fs::home_from_env; home_dir is it over the process env)

Home readers that remain, on purpose, because they follow another tool's own rule: the repository walk's home stop (git), pipenv_home_dir (Python's expanduser), Gradle's passwd-vs-$HOME check (gradle_cache::home_mismatch_with), npm's .npmrc env (patch/redirect/npmrc.rs), the socket-cli config location (utils/socket_cli_config.rs) and update::state's cache-dir chain. The npm crawler's macOS global-prefix fallback (npm_crawler.rs HOME read) is in pm:npm scope (#1008) and is left there; it already skips an empty HOME but would accept a relative one.

Testing

All commands ran in the worktree through /private/tmp/claude-501/heavy-job.sh with CARGO_INCREMENTAL=0, -j4, on macOS:

• cargo build -p socket-patch-core -p socket-patch-cli --tests: clean.
• cargo clippy -p socket-patch-core -p socket-patch-cli --all-targets: no lint on any line this PR changes (checked by intersecting every clippy location with the diff against the merge base). The macOS toolchain reports lints that are already on main (for example unix_default unused in pdm_dir_candidates). Linux clippy -D warnings is left to CI.
• cargo test -p socket-patch-core --lib: 5595 passed, 1 failed. The failure is utils::digest::tests::production_digests_go_through_the_helpers, which already fails on main and is fixed by Fix main CI red on stale digest pending-list entries #1016.
• cargo test -p socket-patch-core --test crawler_maven_e2e --test crawler_gradle_e2e --test crawler_python_e2e --test crawler_cargo_e2e --test telemetry_helpers_e2e: all passed. The first round also ran crawler_{nuget,ruby,go,composer}_e2e and covgap_crawlers_composer_crawler: all passed.
• cargo test -p socket-patch-cli --lib: 862 passed.
• cargo test -p socket-patch-cli --test e2e_socket_yml_policy --test covgap_commands_vex --test e2e_vex --test e2e_embedded_vex --test vex_terminal_output --test vendor_jvm_cli --test maven_sidecar_cli --test covgap_commands_get --test in_process_get_modes --test gradle_agent_cli --test contract_gradle_codes --test e2e_scan --test in_process_scan: all passed (11 ignored in e2e_scan). The first round also ran cli_parse_scan, cli_parse_vex, policy_pypi_names, scan_pnpm_relocated_store_cwd_e2e, in_process_cargo_apply and scan_requirements_lock_only: all passed.
• Failing-first and new tests:
  • detect_in_submodule_names_the_submodule and detect_in_linked_worktree_uses_the_common_config were run against the old product.rs. Both failed: the submodule got pkg:github/acme/superproject and the worktree got None.
  • detect_below_a_home_repository_warns_and_uses_the_manifest: a dotfiles repo at HOME above the project gives the manifest PURL plus a warning; run from HOME itself, the repo is the product.
  • home_dir_never_returns_a_relative_path (old code returned "~"), m2_repo_path_with_no_usable_home_names_no_repository (old code returned ~/.m2/repository) and injected_home_must_be_rooted (python seams; old code returned Library/… / .config/pypoetry under the CWD for HOME="").
  • not_build_root_walks_a_relative_root_and_names_the_callers_spelling: absolute and relative project roots under a parent Gradle build give the refusal with the caller's spelling of the root.
  • keeping_escapes_keeps_every_leading_parent covers the old ../../x → x collapse.
  • FIFO guards: filter_to_installed_purls_pnpm_pnp_hosted_fifo_lock_does_not_wedge (watchdog thread that fails the test instead of hanging), read_manifest_rejects_a_fifo_without_blocking, read_sidecar_rejects_a_fifo_without_blocking. These are guards, not failing-first: a FIFO present from the start is already rejected by the lock inventory or the lstat on main. The B74 change closes the window where a FIFO is swapped in after those checks, which no test races.
  • utils::relpath and utils::repo_root unit tests: fold, floor, keep-escapes, anchored spellings; nearest .git dir or file, home stop (including the reported skipped home repo), ceilings, the ancestor walk past a checkout at the start, submodule/worktree config resolution, and the owner rule.

The intermediate commits were not each built on their own; the final tree was. Please squash-merge.

Deferred

• No VEX-level test for the untrusted-owner warning: faking another owner needs root. The rule itself is unit-tested in repo_root (owner_trusted).
• The npm crawler's macOS HOME fallback accepts a relative HOME (pm:npm scope, Fix open npm issues #1008).
• policy::repo_relative_checked (directory → repo-relative string) and patch::package::canonical_member_key (lowercasing tarball keys) are different operations, not normalizer copies, and are unchanged.
• The npm_crawler.rs normalizer hunk sits near pnpm store code; Fix 15 open pnpm issues across hosted, vendored and agent modes #1007 does not touch npm_crawler.rs today, and the branch merges cleanly with main.
• No maintainer-decision items (Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704, Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966, Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615, Decide: where patch API calls go when a token is set but the org slug can't be resolved #648, C34, E44-E47) are touched.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches home/Maven local repo resolution and many crawler path probes across ecosystems; behavior changes are intentional (no usable home, relative roots, git product detection) but could skip caches or shift warnings in edge CI/container environments.

Overview
Centralizes duplicated path, home, and git-checkout logic so crawlers, policy, VEX, and JVM vendor checks behave consistently and fail closed on unsafe paths.

utils::relpath replaces a dozen hand-rolled ./.. normalizers (composer, npm/pnpm, gradle, sbt, cargo, PyPI includes, etc.) with one stack-based implementation, including a fix where pnpm’s old normalizer collapsed ../../x to x. utils::fs::home_dir now returns Option<PathBuf> and only accepts rooted HOME/USERPROFILE, so callers no longer probe CWD-relative ~ or ./~/.m2 (B66); JvmEnv::m2_repo is optional and wired through Maven/Gradle apply and scan paths.

utils::repo_root is the single git ancestor walk (ceilings, home stop, owner trust, gitdir:/worktree config). Policy socket.yml lookup, VEX --product git detection, and JVM not_build_root all use it—submodules and worktrees name themselves, dotfiles at $HOME don’t claim every project (with warnings), and build-root search walks physical parents so relative . still finds the reactor above.

FIFO-safe reads (B74): hosted get reads pnpm-lock.yaml via read_regular_to_string_sync; Cargo manifest and Maven sidecar reads use the same regular-file helpers after lstat, with new unix tests so a FIFO can’t wedge the suite.

^{Reviewed by Cursor Bugbot for commit e13f87a. Configure here.}

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

bugbot run

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e13f87a. Configure here.}