Expand scheme-aware version support

[andrew]

Adds a central scheme registry and scheme-specific comparison, validation, normalization, cleaning, and release classification for SemVer variants, language registries, distribution formats, and other version types.

Threads canonical schemes through ranges and set operations, expands native parsing for Composer, Pub, Conan, OpenSSL, nginx, npm, Cargo, PyPI, RubyGems, Maven, and NuGet, and tightens canonical VERS parsing and serialization. Replaces the scheme allowlist test runner with data-driven conformance fixtures sourced from upstream implementations. Raises the minimum Ruby version to 3.3 and adds Ruby 3.3 to CI.

[Copilot]

🔵 Needs a closer look

It introduces broad, scheme-dependent version semantics and large fixture-driven test coverage changes, and requires careful human verification of edge-case correctness across multiple ecosystems.

Pull request overview

This PR expands Vers from a small set of scheme-specific behaviors to a centralized, scheme-aware version system, including canonical scheme handling across parsing, normalization/cleaning, comparison, and range algebra. It also replaces the prior scheme allowlist-based conformance tests with data-driven fixtures sourced from upstream implementations and raises the minimum supported Ruby to 3.3.

Changes:

• Introduces a central scheme registry and many scheme-specific version handlers (SemVer family, language registries, distros, and special formats).
• Threads canonical schemes through VersionRange containment and set operations (union/intersect/complement/exclusions) and tightens VERS serialization/parsing behavior.
• Reworks tests to run against upstream-sourced JSON fixtures; updates docs/CI for Ruby >= 3.3.

File summaries

File	Description
vers.gemspec	Raises required Ruby to 3.3 and updates gem metadata URLs.
README.md	Updates public API docs/examples for scheme-aware behavior and expanded scheme list.
CONTRIBUTING.md	Updates contributor prerequisites to Ruby 3.3+.
CHANGELOG.md	Documents scheme-aware feature expansion and behavioral changes; updates compare link base.
.github/workflows/main.yml	Adds Ruby 3.3 to CI matrix.
lib/vers.rb	Updates public API surface docs/examples to include scheme-aware satisfies? usage and cleaning/normalization.
lib/vers/version.rb	Adds scheme-dispatched comparison/validation/normalization/cleaning via Scheme.handler.
lib/vers/version_range.rb	Adds canonical scheme propagation, exclusion tracking, and scheme-aware containment/algebra rules.
lib/vers/interval.rb	Canonicalizes interval schemes and supports scheme-aware comparisons in containment/union/intersect logic.
lib/vers/constraint.rb	Adds scheme-aware satisfaction comparisons.
lib/vers/scheme.rb	Adds canonical scheme aliases and a central registry of scheme handlers.
lib/vers/version_comparison.rb	Adds shared numeric comparison helpers for scheme implementations.
lib/vers/semver_version.rb	Implements SemVer-family parsing/comparison/normalization plus npm/cargo/go behaviors.
lib/vers/pypi_version.rb	Implements PyPI (PEP 440-like) parsing/comparison/normalization and specifier equality helpers.
lib/vers/composer_version.rb	Implements Composer version parsing/comparison/normalization and branch detection.
lib/vers/pub_version.rb	Implements Pub SemVer behavior including build comparison normalization.
lib/vers/gem_version.rb	Implements RubyGems-style version comparison/validation.
lib/vers/maven_version.rb	Adds Maven validation/normalization/prerelease classification helpers.
lib/vers/nuget_version.rb	Adds NuGet validation/normalization/prerelease classification helpers.
lib/vers/conan_version.rb	Implements Conan version comparison/validation/prerelease classification.
lib/vers/distribution_version.rb	Implements Debian/RPM/ALPM/Gentoo comparison/validation/prerelease classification.
lib/vers/special_version.rb	Implements APK/OpenSSL/datetime/intdot/lexicographic schemes.
lib/vers/bazel_version.rb	Tightens Bazel validity (rejects empty) and adds Bazel normalization behavior.
test/test_bazel_version.rb	Updates Bazel validation tests to reject empty string as invalid.
test/test_version_comparison_conformance.rb	Switches comparison conformance to data-driven fixtures from multiple directories.
test/test_range_conformance.rb	Adds data-driven range conformance test runner with skip-manifest support.
test/test_version_behavior.rb	Adds scheme behavior tests (valid/normalize/clean/stable/prerelease).
test/test_native_range_behavior.rb	Adds scheme-aware native range satisfaction fixture tests.
test/test_scheme_ranges.rb	Adds tests ensuring scheme is preserved through parse/serialize and range algebra.
test/test_parser.rb	Adds tests for percent-encoding in VERS serialization and additional native parsing round-trips.
test/test_vers_spec_suite.rb	Removes the old allowlist-based VERS spec runner.
test/testdata/version_behavior.json	Adds fixture cases for scheme-aware version validity/normalization/stability.
test/testdata/native_range_behavior.json	Adds fixture cases for scheme-aware native range satisfaction behavior.
test/testdata/local/skip.json	Adds skip manifest entries for fixture incompatibilities.
test/testdata/local/provenance.json	Adds provenance metadata for upstream-sourced/generated fixture corpora.
test/testdata/local/tests/apk_tools_version_cmp_test.json	Adds apk-tools-based comparison fixtures.
test/testdata/local/tests/cargo_version_cmp_test.json	Adds Cargo comparison fixtures (upstream-derived).
test/testdata/local/tests/composer_version_cmp_test.json	Adds Composer comparison fixtures (upstream-derived).
test/testdata/local/tests/composer_range_from_native_test.json	Adds Composer native->VERS conversion fixtures.
test/testdata/local/tests/composer_range_containment_test.json	Adds Composer containment fixtures.
test/testdata/local/tests/deb_version_cmp_test.json	Adds dpkg comparison fixtures.
test/testdata/local/tests/deb_univers_version_cmp_test.json	Adds univers-based Debian comparison fixtures.
test/testdata/local/tests/gem_version_cmp_test.json	Adds RubyGems comparison fixtures (upstream-derived).
test/testdata/local/tests/gentoo_univers_version_cmp_test.json	Adds univers-based Gentoo comparison fixtures.
test/testdata/local/tests/maven_range_reference_test.json	Adds Maven containment reference fixtures (upstream-derived).
test/testdata/local/tests/maven_range_generated_test.json	Adds Maven containment generated fixtures (upstream-derived).
test/testdata/local/tests/pub_version_cmp_test.json	Adds Pub comparison fixtures (upstream-derived).
test/testdata/local/tests/pub_range_from_native_test.json	Adds Pub native->VERS conversion fixtures.
test/testdata/local/tests/pub_range_containment_test.json	Adds Pub containment fixtures.

Review details

• Files reviewed: 55/73 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.