Improve VersionMap documentation and add comprehensive tests

[billf]

Improved VersionMap tests and documentation

This PR enhances the VersionMap implementation by:

1. Improving documentation for the insert method to clarify its behavior with alternates
2. Splitting the monolithic test into focused test cases:
   • Basic operations (insertion, duplicate handling)
   • Alternate lookups (exact vs alternate version matching)
   • Latest version operations
   • Removal functionality
3. Adding comprehensive tests for the version_alternate function to verify behavior with:
   • Pre-release versions
   • Major versions > 0
   • Minor versions > 0 (when major is 0)
   • Patch versions (when major and minor are 0)

[billf]

• Add VersionMap utility methods and improve implementation #5
• Improve VersionMap documentation and add comprehensive tests #3 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Pull Request Overview

This PR refines the VersionMap module by enhancing its documentation and substantially expanding test coverage.

• Clarifies the behavior of insert with alternate versions
• Splits the previous monolithic test into focused test cases (basic ops, alternates, latest, removal)
• Adds thorough tests for version_alternate across pre-release, major, minor, and patch scenarios

Comments suppressed due to low confidence (2)

src/semver.rs:285

• [nitpick] The variable names v1 and v2 are inconsistent with the earlier version0..version3 naming. Consider renaming them to version1 and version2 for clarity and consistency.

let v1 = Version::new(1, 0, 0);

src/semver.rs:296

• Consider adding an explicit test for version_alternate(&Version::new(0, 0, 0)) to verify and document the behavior when both major and minor are zero.

fn test_version_alternate_function() {

[Copilot]

[nitpick] Tests mix the infallible insert API with the fallible try_insert. For consistency and clearer error handling, consider using try_insert in all test cases.

Suggested change

	map.insert(Version::new(1, 0, 0), "v1.0.0");
	map.insert(Version::new(2, 0, 0), "v2.0.0");
	map.insert(Version::new(0, 1, 0), "v0.1.0");
	assert!(map.try_insert(Version::new(1, 0, 0), "v1.0.0").is_ok());
	assert!(map.try_insert(Version::new(2, 0, 0), "v2.0.0").is_ok());
	assert!(map.try_insert(Version::new(0, 1, 0), "v0.1.0").is_ok());

[github-actions]

Code Coverage Report

Package	Base Coverage	New Coverage	Difference
graph.rs	🟢 84.58%	🟢 84.58%	⚪ 0%
path.rs	🟢 100%	🟢 100%	⚪ 0%
semver.rs	🟢 97.7%	🟢 97.7%	⚪ 0%
trampoline.rs	🟠 70.83%	🟠 70.83%	⚪ 0%
Overall Coverage	🟢 86.06%	🟢 86.06%	⚪ 0%

Minimum allowed coverage is 0%, this run produced 86.06%