Match package targets by PurlKey identity, not by lowercase (#1292)

[Mikola Lysenko (mikolalysenko)]

LLM Description written by Claude Code:claude-opus-5-5

Fixes #1292

Summary

get, remove and rollback select packages through utils::target::Target. Before this PR it used two case rules. Versioned purls compared through the case-preserving PurlKey. Versionless purls, names and the ambiguity guard lowercased every ecosystem. So remove pkg:npm/jsonstream or remove jsonstream also dropped JSONStream's patch, and with rollback also restored its files. Go's Sirupsen/sirupsen logrus counted as one package.

Target now keys packages by one identity: package_identity, the PurlKey spelling (canonical_base_purl) without the version.

Why (leverage)

• B 1: remove, rollback and get treat case-distinct packages as one: remove pkg:npm/jsonstream also removes JSONStream's patch #1292, a destructive command acting on a second, distinct package.
• D 1: the private lowercase + PEP 503 identity fold in utils/target.rs is deleted. Purl targets stop going through the lenient scan --package filter matcher, so one equivalence (PurlKey) decides "same package" for every Target purl.
• R: M (a deliberate selection change, limited to case-distinct packages).

Register row C80 (register); living document doc/02-cli.md {{C80}}.

What changed

• package_identity returns canonical_base_purl minus the version. Case folds only for PyPI (PEP 503), NuGet and Composer. It stays case-sensitive for npm, Go, Maven, cargo and gem.

• Versionless purl targets match by identity equality in matches_package and matches_patch. Versioned purl targets in matches_package use PurlKey::same, the same rule matches_patch already used. This means get no longer selects a package that remove with the same spelling can't select.

• settle counts case-distinct identities:

  • a lowercase name that reaches JSONStream and jsonstream is ambiguous_target;
  • a name typed with an uppercase letter settles on its exact-case package (JSONStream).

  The settled target narrows to one identity (only: Option<String>); before, it narrowed with a full_name_only flag.

• Names are still matched case-insensitively (LODASH → lodash). package_spec_matches (used by scan --package and socket.yml) is unchanged.

• CLI_CONTRACT.md: the target-grammar paragraph documents the case rule and the new ambiguity case.

Deleted

The lowercase + PEP 503 fold in package_identity, and the package_spec_matches calls for purl targets. Production: utils/target.rs +78/−34 (mostly doc comments). Tests: +113 core, +55 CLI. Contract: 2 lines.

Behavior

These changes are limited to case-distinct packages in case-sensitive ecosystems:

• pkg:npm/jsonstream no longer selects pkg:npm/JSONStream@…. The same holds for Go, Maven, cargo and gem.
• A lowercase name reaching case-distinct packages exits 1 with ambiguous_target. Before, it selected both.
• A versionless purl now also matches a versionless record purl of the same package. Before, it required an @version.

Everything else is unchanged, including the PyPI/NuGet/Composer spelling folds (existing #926/#1024 tests are green).

Tie-break, open to review: #1292's acceptance asks that jsonstream be ambiguous but JSONStream settle on itself. I implemented that as "an uppercase letter in the typed name means exact case". All-lowercase is how users type any name, so it stays ambiguous.

Test evidence

• cargo clippy --workspace --all-features -- -D warnings: clean.
• cargo test -p socket-patch-core --lib: 6093 passed, 4 failed. The 4 are the known root-sandbox failures, which also fail on main (relax_loop_must_not_traverse_symlinked_root, an_unremovable_hidden_lock_keeps_every_store_entry, wire_write_failure_maps_error_and_leaves_lock_untouched, wire_failure_rolls_back_already_written_files).
• New core tests:
  • purl_targets_agree_on_case_in_every_ecosystem: a table over npm, golang, maven, cargo, gem, pypi, nuget and composer, checking versioned and versionless targets with matches_patch and matches_package;
  • case_distinct_packages_are_two_packages;
  • an updated package_identity_drops_version_and_qualifiers.
• cargo test -p socket-patch-cli --all-features --test in_process_target_ambiguity: 9 passed.
  • Red → green: with utils/target.rs from main, remove_never_reaches_a_case_distinct_package and rollback_refuses_a_lowercase_name_reaching_case_distinct_packages FAIL. Both pass on this branch.

Risk

Medium-low. One file of logic. The selection only narrows: a target never selects more than it did before.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WeCUZpHUvuy3cinyNW94My

---

Note

Medium Risk
Changes selection for get/remove/rollback on case-distinct packages in case-sensitive ecosystems—previously a single lowercase target could affect the wrong patch; behavior narrows rather than broadens.

Overview
Fixes #1292 by unifying how get, remove, and rollback decide “same package” in utils::target::Target.

Package identity now comes from canonical_base_purl / PurlKey: case is preserved for npm, Go, Maven, cargo, and gem; PyPI, NuGet, and Composer still fold per ecosystem rules. Versionless purl targets and patch matching use that identity instead of lowercasing everything or going through package_spec_matches. Versioned purl matches_package uses PurlKey::same, aligned with matches_patch.

Ambiguity / settle: lowercase names that would hit multiple case-distinct packages (e.g. jsonstream → JSONStream and jsonstream) exit with ambiguity; a name with an uppercase letter settles to exact-case spelling (JSONStream). Narrowing is stored in only: Option<String> instead of full_name_only.

Docs (CLI_CONTRACT.md) and in-process CLI tests cover the new behavior; core unit tests exercise per-ecosystem case rules.

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

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

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 9c7a1da. Configure here.}

[Mikola Lysenko (mikolalysenko)]

[agent] Two checks are red on 9c7a1da, and neither failure comes from this PR:

• e2e (ubuntu-latest, e2e_safety_pnpm): get 80630680-… --mode agent + apply no longer patch minimist/index.js (hash mismatch, missing layout note).
• hosted-e2e: preflight_required_patches_are_published and the install proofs report no free patch for pkg:npm/minimist@1.2.2.

Both match #1293: production stopped serving the pinned minimist patch between 15:29Z and 15:49Z, and every PR and merge-group run fails the same way. Neither suite reaches the code this PR changes: the UUID path of get doesn't call Target::matches_package or settle. The fix is #1301, which repins the suites to the republished patch across 37 files. I'm not porting that repin here. It would bring 37 unrelated files into this PR and conflict with #1301. A re-run can't help either, because the failure is deterministic until the repin lands. After #1301 merges, merging main into this branch should turn both checks green. Every other check passes (98 passed, 2 skipped on page 1), and Bugbot found no issues.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Ready for review (burn-down agent).

• Head: 9c7a1da9
• CI: every check green except main-wide failures that also fail on main at a8e9397: e2e (ubuntu-latest, e2e_safety_pnpm), hosted-e2e (withdrawn free minimist@1.2.2 patch, Merge queue blocked: production no longer publishes free minimist@1.2.2 patch #1293; fixes in Repin live minimist@1.2.2 suites to republished patch 642d7f02 (#1293) #1301/Follow the republished minimist canary patch #1302), and the ci-ok roll-up.
• Bugbot: reviewed this head, no findings; no open review threads.
• No CHANGELOG.md changes.

---

Generated by Claude Code