fix(gem): crawl bundle-path roots in bundler precedence order, patch every coexisting copy, contain config-sourced roots - #222

Follow-up fix for the verified post-merge audit findings on #218 (gem crawler flat-BUNDLE_PATH discovery, squash 3e51259). Mirrors the multi-copy machinery #216 (squash 0433bcb) built for npm rather than inventing a parallel mechanism.

Audit findings and fixes

1. MULTI-COPY silent false "applied" (most severe). When the same gem@version exists in two discovered stores under one root — scoped vendor/bundle/<engine>/<abi>/gems beside flat vendor/bundle/gems, a real coexist state fix(gem): discover flat BUNDLE_PATH gem layouts — bundler-1 env-var installs were invisible to scan/get/apply #218's tests create — first-wins merging resolved the purl to ONE path: apply patched that copy and reported success while the bundler major that loads the other store ran pristine (vulnerable) bytes.
   Fix (the fix(apply): patch every on-disk copy of a duplicated package (multi-copy silent partial P0) #216 pattern, reused): find_all_packages_for_purls now routes the release-variant ecosystems through an accumulating merge_variant_copies (built on the same push_path the npm merge uses; base-PURL keyed; store-precedence order preserved), and apply's variant branch fans out per copy for gem — per-copy applied events, summary.applied counts each copy (the signal a second copy exists), a failure on any copy fails the run, and a copy that matches no variant fails loudly instead of hiding behind a sibling's success. Rollback already carried every copy post-fix(apply): patch every on-disk copy of a duplicated package (multi-copy silent partial P0) #216 (merge_qualified accumulates + per-path grouping); the new in-process suite pins both directions.
   Scope decisions: PyPI/Maven keep the one-representative contract — their crawlers resolve one install dir per version, and fanning their per-root aliases out is exactly the already_patched double-patch regression fix(apply): patch every on-disk copy of a duplicated package (multi-copy silent partial P0) #216's second commit reverted for nuget. All collapsing consumers (vendor/vex/setup/get/repair vendor) keep the first (highest-precedence) copy. On the audit's scan clause: scan --sync patches every copy (it runs the real nested apply::run), and scan's inventory stays purl-level — deliberately byte-identical to the npm precedent, whose crawl_all keeps the same purl dedup (check_package); emitting duplicate purl rows would diverge from npm and inflate scannedPackages counts.

2. PRECEDENCE. Root probe order was vendor/bundle → env → .bundle/config, inverting bundler's real precedence. Roots are now probed local config → env → default vendor/bundle (Bundler::Settings order), so wherever one representative is still chosen, it is the copy bundler actually loads. Pinned by bundle_roots_probe_in_bundler_precedence_order (RED on base).

3. REGRESSION vs pre-fix(gem): discover flat BUNDLE_PATH gem layouts — bundler-1 env-var installs were invisible to scan/get/apply #218 (gem-env fallback suppressed). The new env/config roots tripped the pre-existing early-return in get_gem_paths, so an env-BUNDLE_PATH project lost the gem env fallback that surfaces DEFAULT/system gem homes (default gems like rexml/json never live in a bundle path). Restored: only the historic project-local vendor/bundle probe keeps its early-return; env/config-rooted stores get the gem-env homes appended, deduped. New e2e get_gem_paths_env_root_still_includes_gempath_homes extends the "local includes every gempath home" pin to the env-root case.

4. SECURITY: config-sourced roots contained-or-skipped. A repo-committed .bundle/config BUNDLE_PATH is attacker-authored input that became a scan/apply WRITE-target root with no guard (absolute values verbatim, .. unnormalized — a malicious clone could direct apply into /usr/local or a sibling checkout). Policy now: after ~ expansion and lexical normalization, a CONFIG-sourced root must be contained within the project root, else it is skipped with a loud stderr warning naming the config value (gem_bundle_config_path_ignored — the crawler has no structured warning channel, so the established stderr path). Windows rooted forms (\evil, C:evil) take the strict branch — Path::join would otherwise substitute them into the base. ENV-sourced BUNDLE_PATH stays trusted (the user's own environment) but is ..-normalized for dedup. normalize_lexically is hoisted from the composer crawler's install-path guard into utils::fs and shared (same containment posture as the setup/gem plugin-index cleanup). Tests: absolute-outside skipped, ../sibling skipped, contained relative (incl. .//.. detours) accepted, plus a pure containment contract.

5. ~ expansion. resolve_bundle_path treated ~/store as relative (cwd.join); bundler File.expand_paths it against $HOME. A leading bare-~ component now expands against home, injected through the _with_env seams so tests stay hermetic (~user is left as before — it needs bundler's passwd lookup).

6. BUNDLE_PATH__SYSTEM. BUNDLE_PATH__SYSTEM: "true" makes bundler ignore the recorded path entirely; the config entry now parses as unset (exact-"true" coercion, either key order), and finding 3's fallback surfaces the system gem homes.

7. Test hermeticity. The six crawler_ruby_e2e.rs tests that laid a Gemfile and asserted exact equality on get_gem_paths while reading ambient BUNDLE_PATH/BUNDLE_APP_CONFIG now route through the new public get_gem_paths_with_env seam — machines with bundler configured no longer go red. The new in-process suite additionally scrubs BUNDLE_* from the child env.

8. CLI_CONTRACT.md. The stale "gem — the crawler inspects only the project rooted at --cwd" claim replaced with the truthful model: env BUNDLE_PATH honored (user-controlled, may point out of tree), config-sourced paths contained-or-skipped per finding 4, bundler-precedence root order, gem-env fallback semantics, and the multi-copy apply/rollback behavior.

TDD evidence (red → green)

All three headline tests failed on base with the exact defect (flat copy byte-for-byte VULNERABLE while apply reported success / one path carried):

• ecosystem_dispatch::find_all_packages_for_purls_carries_every_gem_store_copy (dispatch carries both copies, scoped first; collapsing wrapper keeps one)
• ruby_crawler::bundle_roots_probe_in_bundler_precedence_order (config → env → default)
• tests/in_process_gem_multicopy.rs (real binary: apply patches BOTH copies, summary.applied == 2, two applied events; rollback restores BOTH)

Live era-image proof (docker run --rm only)

socket-patch-test-gem-b1:gemx (aarch64, ruby 3.1.7, bundler 1.17.3), coexist fixture, oracle loaded via real GEM_HOME rubygems resolution inside the container:

• Baked (pre-fix) binary in-container: status: success, applied: 1 — flat store loads VULNERABLE, scoped loads FIXED → the silent partial, live.
• This branch's binary (host apply, container load): applied: 2 — flat FIXED, scoped FIXED.

Gates (verbatim results)

• touched-files rustfmt --check: clean (cargo fmt repo-wide was deliberately not applied — main carries pre-existing drift in unrelated test files)
• cargo clippy --workspace --all-features -- -D warnings: clean
• cargo test -p socket-patch-core --lib: 2413 passed; 0 failed; 4 ignored
• cargo test -p socket-patch-cli --lib: 430 passed; 0 failed; 1 ignored
• crawler_ruby_e2e: 25 passed · crawler_composer_e2e: 32 passed · crawlers_empty_paths_e2e: 13 passed
• e2e_gem (hermetic): 8 passed · in_process_gem_multicopy: 2 · in_process_npm_multicopy: 2 · cli_gem_variant_mismatch_policy: 6 · apply_invariants: 7 · apply_network: 9 · cli_apply_silent: 5 · cli_rollback_silent: 5 · e2e_scan: 5
• docker (blocking in CI): docker_e2e_gem: 2 · docker_e2e_vendor_gem: 2 · docker_e2e_pypi: 1 · docker_e2e_maven: 5 — all green

Documented follow-ups (deliberately NOT in this PR)

• Global ~/.bundle/config BUNDLE_PATH (unscoped bundle config set path, the default on bundler >= 2.1) still unsupported.
• YAMLSerializer backslash-escape unescaping of config values (Windows/UNC paths).
• The Bundler-manifest gate is cwd-only while bundler itself walks up for the Gemfile.
• crawlers→setup module edge + duplicated quote-strip parsing between ruby_crawler and setup/gem — suggest a utils::bundler extraction.
• seen/seen_roots double-dedup readability in the store discovery loop.
• Test scaffold helper for the repeated store-staging boilerplate in the crawler tests.

🤖 Generated with Claude Code