fix(prune): preserve case-equivalent GitHub dependencies

[Shaurya Saria (icecold009)]

Description

After installing microsoft/apm, changing the manifest to Microsoft/APM could make apm prune delete that still-declared package. Prune now recognizes its existing case-equivalent materialization while preserving the actual directory spelling.

This opts only prune into the existing host-aware materialization matcher. Direct and lockfile-retained transitive dependencies use the same comparison. Aliases, local packages, case-sensitive hosts and in-repository path casing keep their existing rules. Ambiguous case variants fail before cleanup. No rename or global lowercasing is introduced.

Issue and approved scope

Fixes #3034.

Human approval: #3034 (comment)
Coordination comment: #3034 (comment)

Completes the approved scope: dependency preservation, actual orphan removal, host-sensitive regressions and directly related prune documentation. Review contact: Daniel Meppiel (@danielmeppiel).

Type of change

• Bug fix
• Documentation
• New feature
• Maintenance / refactor

Testing

• Tested locally
• Added regression coverage
• All existing tests pass (full suite not run)

Exact head: c347ee3d5dbea58b2ad984b90af96d5559d536af, based on 18c4c43c924ceae890fe0f2038806690e5b2d6c8.

Clean uv sync --frozen --extra dev environment, Python 3.12.14; Ruff 0.15.12 matches the lockfile.

• Focused prune, command-helper, materialization and prune lifecycle suites: 187 passed, 2 skipped.
• tests/quality and tests/spec_conformance/test_lockfile_reqs.py: 100 passed, 1 skipped.
• Final new-case rerun: 19 passed. Temporarily disabling the prune opt-in made all 10 command regressions fail, then exact source bytes were restored.
• Full-scope Ruff lint/format, pylint R0801, architecture, assertion-quality, exact-duplicate and auth-signal checks passed. YAML-I/O, 2100-line and portable-relative-path CI predicates passed.
• uv build --no-build-isolation built the source distribution and wheel.
• git diff --check passed.

The CLI cases use the canonical apm_engine_command fixture, shared lifecycle runner and isolated environment with networking disabled. They execute the source-installed CLI; frozen-binary and remote-CI results are not claimed.

Scenario evidence

Promise	Evidence
Both casing directions preserve package bytes and manifest; real orphans still disappear	Eight command cases, dry-run/real prune, with/without lockfile
Lock-pinned transitive package remains installed	Transitive command regression
Real CLI preserves declared dependency and removes only actual orphan	Two isolated CLI subprocess cases
Unknown hosts, aliases, local paths and virtual suffixes retain casing rules	Host-sensitive helper and command regressions
Ambiguous variants cannot trigger deletion	Real matcher with a platform-neutral duplicate listing; files and lockfile unchanged

AI disclosure: Codex generated this patch and performed the checks above. Jev jev-1.13.0 reviewed the complete six-file diff with no exclusions and no clear issue; advisory review does not replace maintainer review.

Spec conformance (OpenAPM v0.1)

No normative requirement is amended. This restores existing host-aware identity behavior; the existing lockfile conformance suite passed as part of the validation above.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.