fix: ensure '0' version is always sorted first (#4049)

Per the osv-schema:
> `introduced` allows a version of the value `"0"` to represent a
version that sorts before any other version.

Previously, we were just coercing "0" to be the general 0 value for the
ecosystem (e.g. in semver `0.0.0`).
This caused problems when trying to match e.g. `0.0.0-pre`, which sorts
before.

Wrapped all the sort_keys in a `VersionKey` type and added a new
sentinel `0` value type that always sorts before other versions.

This is technically incorrect for ecosystems where "0" is a valid
version and that supports pre-releases (e.g. in Maven `alpha` <
`0-alpha` < `0`) but these edge cases are not worth handling.

On an semi unrelated note, also bumped the max version that some invalid
versions get mapped to from `999999` to `9999999999` so that they're
larger than CalVer versions e.g. `20250607`

I'm going to have to do a re-computation/reput of the AffectedVersions
entities to make sure they're all still sorted.

Author: michaelkedar

osv/ecosystems/alpine.py

@@ -31,11 +31,11 @@
 class APK(OrderedEcosystem):
   """Alpine Package Keeper ecosystem helper."""
 
-  def sort_key(self, version):
+  def _sort_key(self, version):
     if not AlpineLinuxVersion.is_valid(version):
       # If version is not valid, it is most likely an invalid input
       # version then sort it to the last/largest element
-      return AlpineLinuxVersion('999999')
+      return AlpineLinuxVersion('9999999999')
     return AlpineLinuxVersion(version)
 
 

osv/ecosystems/alpine_test.py

@@ -45,6 +45,10 @@ def test_apk(self):
     self.assertGreater(
         ecosystem.sort_key('1.13.2-r0'), ecosystem.sort_key('1.13.2_alpha'))
 
+    # Check the 0 sentinel value.
+    self.assertLess(
+        ecosystem.sort_key('0'), ecosystem.sort_key('0.0.0_alpha-r0'))
+
     # Check invalid version handle
     self.assertGreater(
         ecosystem.sort_key('1-0-0'), ecosystem.sort_key('1.13.2-r0'))

osv/ecosystems/bioconductor_test.py

@@ -32,3 +32,19 @@ def test_next_version(self):
       self.assertEqual('1.20.0', ecosystem.next_version('a4', '1.18.0'))
       with self.assertRaises(ecosystems.EnumerateError):
         ecosystem.next_version('doesnotexist123456', '1')
+
+  def test_sort_key(self):
+    """Test sort_key."""
+    ecosystem = ecosystems.get('Bioconductor')
+    self.assertGreater(
+        ecosystem.sort_key('1.20.0'), ecosystem.sort_key('1.18.0'))
+    self.assertLess(ecosystem.sort_key('1.18.0'), ecosystem.sort_key('1.18.1'))
+
+    # Check the 0 sentinel value.
+    self.assertLess(ecosystem.sort_key('0'), ecosystem.sort_key('0.0.0'))
+
+    # Check >= / <= methods
+    self.assertGreaterEqual(
+        ecosystem.sort_key('1.20.0'), ecosystem.sort_key('1.18.0'))
+    self.assertLessEqual(
+        ecosystem.sort_key('1.18.0'), ecosystem.sort_key('1.20.0'))

osv/ecosystems/cran.py

@@ -29,7 +29,7 @@ class CRAN(EnumerableEcosystem):
   _API_PACKAGE_URL_POSIT_CRAN = 'https://packagemanager.posit.co/__api__/' + \
     'repos/2/packages/{package}'
 
-  def sort_key(self, version):
+  def _sort_key(self, version):
     """Sort key."""
     # Some documentation on CRAN versioning and the R numeric_version method:
     # https://cran.r-project.org/doc/manuals/R-exts.html#The-DESCRIPTION-file

osv/ecosystems/cran_test.py

@@ -43,3 +43,18 @@ def test_next_version(self):
 
       # Test atypical versioned package
       self.assertEqual('0.99-8.47', ecosystem.next_version('aqp', '0.99-8.1'))
+
+  def test_sort_key(self):
+    """Test sort_key."""
+    ecosystem = ecosystems.get('CRAN')
+    self.assertGreater(ecosystem.sort_key('1.0-0'), ecosystem.sort_key('0.1-0'))
+    self.assertLess(ecosystem.sort_key('0.1-0'), ecosystem.sort_key('0.1-1'))
+
+    # Check the 0 sentinel value.
+    self.assertLess(ecosystem.sort_key('0'), ecosystem.sort_key('0.0-0'))
+
+    # Check >= / <= methods
+    self.assertGreaterEqual(
+        ecosystem.sort_key('1.10-0'), ecosystem.sort_key('1.2-0'))
+    self.assertLessEqual(
+        ecosystem.sort_key('1.2-0'), ecosystem.sort_key('1.10-0'))

osv/ecosystems/debian.py

@@ -29,11 +29,11 @@
 class DPKG(OrderedEcosystem):
   """Debian package (dpkg) ecosystem"""
 
-  def sort_key(self, version):
+  def _sort_key(self, version):
     if not DebianVersion.is_valid(version):
       # If debian version is not valid, it is most likely an invalid fixed
       # version then sort it to the last/largest element
-      return DebianVersion(999999, '999999')
+      return DebianVersion(9999999999, '9999999999')
     return DebianVersion.from_string(version)
 
 

osv/ecosystems/debian_test.py

@@ -35,6 +35,9 @@ def test_dpkg(self):
     self.assertGreater(
         ecosystem.sort_key('1.13.6-2'), ecosystem.sort_key('1.13.6-1'))
 
+    # Check the 0 sentinel value.
+    self.assertLess(ecosystem.sort_key('0'), ecosystem.sort_key('0:0~0-0'))
+
     # Test that <end-of-life> specifically is greater than normal versions
     self.assertGreater(
         ecosystem.sort_key('<end-of-life>'), ecosystem.sort_key('1.13.6-1'))

osv/ecosystems/ecosystems_base.py

@@ -16,12 +16,58 @@
 from typing import Any
 from warnings import deprecated
 import bisect
+import functools
 import requests
 from urllib.parse import quote
 
 from . import config
 
 
+@functools.total_ordering
+class VersionKey:
+  """A wrapper class for version keys."""
+
+  _key: Any
+  _is_zero: bool
+
+  def __init__(self, key: Any = None, is_zero: bool = False):
+    self._key = key
+    self._is_zero = is_zero
+
+  def __lt__(self, other):
+    if not isinstance(other, VersionKey):
+      return NotImplemented
+
+    if self._is_zero:
+      return not other._is_zero
+
+    if other._is_zero:
+      return False
+
+    return self._key < other._key
+
+  def __eq__(self, other):
+    if not isinstance(other, VersionKey):
+      return NotImplemented
+
+    if self._is_zero:
+      return other._is_zero
+
+    if other._is_zero:
+      return False
+
+    return self._key == other._key
+
+  def __repr__(self):
+    if self._is_zero:
+      return 'VersionKey(is_zero=True)'
+
+    return f'VersionKey(key={self._key!r})'
+
+
+_VERSION_ZERO = VersionKey(is_zero=True)
+
+
 class OrderedEcosystem(ABC):
   """Ecosystem helper that supports comparison between versions."""
 
@@ -34,12 +80,19 @@ def __init__(self, suffix: str | None = None):
     self.suffix = suffix
 
   @abstractmethod
-  def sort_key(self, version: str) -> Any:
+  def _sort_key(self, version: str) -> Any:
     """Comparable key for a version.
     
     If the version string is invalid, return a very large version.
     """
 
+  def sort_key(self, version: str) -> VersionKey:
+    """Sort key."""
+    if version == '0':
+      return _VERSION_ZERO
+
+    return VersionKey(self._sort_key(version))
+
   def sort_versions(self, versions: list[str]):
     """Sort versions."""
     versions.sort(key=self.sort_key)

osv/ecosystems/haskell.py

@@ -32,7 +32,7 @@ class Hackage(EnumerableEcosystem):
 
   _API_PACKAGE_URL = 'https://hackage.haskell.org/package/{package}.json'
 
-  def sort_key(self, version):
+  def _sort_key(self, version):
     """Sort key.
 
     The Haskell package version data type is defined at

osv/ecosystems/haskell_test.py

@@ -42,6 +42,9 @@ def test_sort_key(self):
     self.assertGreater(
         ecosystem.sort_key('1-20-0'), ecosystem.sort_key('1.20.0'))
 
+    # Check the 0 sentinel value.
+    self.assertLess(ecosystem.sort_key('0'), ecosystem.sort_key('0.0.0.1'))
+
     # Check >= / <= methods
     self.assertGreaterEqual(
         ecosystem.sort_key('1-20-0'), ecosystem.sort_key('1.20.0'))