refactor(versionmap): Version-only keys, Mapping API, and iter_pairs

[vshawrh]

What

• Restrict VersionMap to packaging.version.Version keys only (no string coercion or parsing inside the map).
• Add iter_pairs() to yield (version, value) in descending version order.
• Subclass collections.abc.Mapping (__getitem__, __iter__, __len__); mutations stay on add().
• Use iter_pairs() in VersionMapProvider.find_candidates.
• Update tests to use Version(...) keys and cover invalid keys plus basic Mapping behavior.

Why

• Implements the follow-up from #986: clearer API (callers own version parsing), a single iterator for version + associated data (e.g. URL), and a conventional read-only mapping interface without implying dict-style assignment.

Breaking change: code that constructed VersionMap with string keys must switch to Version("…").

Closes #986

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9305ecaf-fa19-410d-aa76-d19a2558f692

📥 Commits

Reviewing files that changed from the base of the PR and between aec9c9c and fc2cbfa.

📒 Files selected for processing (4)

• src/fromager/resolver.py
• src/fromager/versionmap.py
• tests/test_resolver.py
• tests/test_versionmap.py

---

📝 Walkthrough

Walkthrough

The pull request refactors VersionMap to conform to the Python Mapping protocol while enforcing stricter type safety. VersionMap now inherits from Mapping[Version, typing.Any], implements __iter__ and __len__ for mapping protocol compliance, and introduces iter_pairs() to yield version-value tuples in descending order. All public methods (add, __init__, __getitem__) now accept only Version keys instead of accepting strings, delegating string parsing to callers. The resolver's find_candidates() method is updated to use the new iter_pairs() iterator, eliminating separate index lookups. Tests are updated to pass Version objects as keys and verify the stricter type validation and new mapping capabilities.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly describes the main refactoring: making VersionMap use Version-only keys, implementing the Mapping API, and adding iter_pairs.
Description check	✅ Passed	The description explains both what changed (Version-only keys, Mapping API, iter_pairs) and why (addresses issue #986 requirements), with explicit note of breaking changes.
Linked Issues check	✅ Passed	All three requirements from #986 are met: VersionMap accepts only Version keys (no string coercion), iter_pairs yields version+value pairs, and VersionMap subclasses Mapping with getitem/iter/len.
Out of Scope Changes check	✅ Passed	All changes are in-scope: versionmap.py and resolver.py updates implement the three requirements, test updates cover new API and edge cases, no unrelated modifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}