fix(vim.version): prerelease compare

Problem:
semver specifies that digit sequences in a prerelease string should be
compared as numbers, not lexically: https://semver.org/#spec-item-11
> Precedence for two pre-release versions with the same major, minor,
> and patch version MUST be determined by comparing each dot separated
> identifier from left to right until a difference is found as follows:
> 1. Identifiers consisting of only digits are compared numerically.
> 2. Identifiers with letters or hyphens are compared lexically in ASCII sort order.
> 3. Numeric identifiers always have lower precedence than non-numeric identifiers.
> 4. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.
Example:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Solution:
cmp_prerel() treats all digit sequences in a prerelease string as
numbers. This doesn't _exactly_ match the spec, which specifies that
only dot-delimited digit sequences should be treated as numbers...

runtime/lua/vim/shared.lua

@@ -66,14 +66,15 @@ end)()
 ---   end
 ---   </pre>
 ---
----@see |vim.split()|
----@see |luaref-patterns|
----@see https://www.lua.org/pil/20.2.html
----@see http://lua-users.org/wiki/StringLibraryTutorial
+--- @see |string.gmatch()|
+--- @see |vim.split()|
+--- @see |luaref-patterns|
+--- @see https://www.lua.org/pil/20.2.html
+--- @see http://lua-users.org/wiki/StringLibraryTutorial
 ---
----@param s string String to split
----@param sep string Separator or pattern
----@param opts (table|nil) Keyword arguments |kwargs|:
+--- @param s string String to split
+--- @param sep string Separator or pattern
+--- @param opts (table|nil) Keyword arguments |kwargs|:
 ---       - keepsep: (boolean) Include segments matching `sep` instead of discarding them.
 ---       - plain: (boolean) Use `sep` literally (as in string.find).
 ---       - trimempty: (boolean) Discard empty segments at start and end of the sequence.

runtime/lua/vim/version.lua

@@ -65,6 +65,33 @@ local M = {}
 local Version = {}
 Version.__index = Version
 
+--- Compares prerelease strings: per semver, number parts must be must be treated as numbers:
+--- "pre1.10" is greater than "pre1.2". https://semver.org/#spec-item-11
+local function cmp_prerel(prerel1, prerel2)
+  if not prerel1 or not prerel2 then
+    return prerel1 and -1 or (prerel2 and 1 or 0)
+  end
+  -- TODO(justinmk): not fully spec-compliant; this treats non-dot-delimited digit sequences as
+  -- numbers. Maybe better: "(.-)(%.%d*)".
+  local iter1 = prerel1:gmatch('([^0-9]*)(%d*)')
+  local iter2 = prerel2:gmatch('([^0-9]*)(%d*)')
+  while true do
+    local word1, n1 = iter1()
+    local word2, n2 = iter2()
+    if word1 == nil and word2 == nil then -- Done iterating.
+      return 0
+    end
+    word1, n1, word2, n2 =
+      word1 or '', n1 and tonumber(n1) or 0, word2 or '', n2 and tonumber(n2) or 0
+    if word1 ~= word2 then
+      return word1 < word2 and -1 or 1
+    end
+    if n1 ~= n2 then
+      return n1 < n2 and -1 or 1
+    end
+  end
+end
+
 function Version:__index(key)
   return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Version[key]
 end
@@ -88,7 +115,7 @@ function Version:__eq(other)
       return false
     end
   end
-  return self.prerelease == other.prerelease
+  return 0 == cmp_prerel(self.prerelease, other.prerelease)
 end
 
 function Version:__tostring()
@@ -111,13 +138,7 @@ function Version:__lt(other)
       return true
     end
   end
-  if self.prerelease and not other.prerelease then
-    return true
-  end
-  if other.prerelease and not self.prerelease then
-    return false
-  end
-  return (self.prerelease or '') < (other.prerelease or '')
+  return -1 == cmp_prerel(self.prerelease, other.prerelease)
 end
 
 ---@param other Version
@@ -127,7 +148,7 @@ end
 
 --- @private
 ---
---- Creates a new Version object. Not public currently.
+--- Creates a new Version object, or returns `nil` if `version` is invalid.
 ---
 --- @param version string|number[]|Version
 --- @param strict? boolean Reject "1.0", "0-x", "3.2a" or other non-conforming version strings
@@ -173,6 +194,7 @@ function M._version(version, strict) -- Adapted from https://github.com/folke/la
       build = build ~= '' and build or nil,
     }, Version)
   end
+  return nil -- Invalid version string.
 end
 
 ---TODO: generalize this, move to func.lua
@@ -341,7 +363,7 @@ function M.cmp(v1, v2)
   return -1
 end
 
----Returns `true` if the given versions are equal.
+---Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage.
 ---@param v1 Version|number[]
 ---@param v2 Version|number[]
 ---@return boolean
@@ -349,7 +371,7 @@ function M.eq(v1, v2)
   return M.cmp(v1, v2) == 0
 end
 
----Returns `true` if `v1 < v2`.
+---Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
 ---@param v1 Version|number[]
 ---@param v2 Version|number[]
 ---@return boolean
@@ -357,7 +379,7 @@ function M.lt(v1, v2)
   return M.cmp(v1, v2) == -1
 end
 
----Returns `true` if `v1 > v2`.
+---Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
 ---@param v1 Version|number[]
 ---@param v2 Version|number[]
 ---@return boolean

test/functional/lua/version_spec.lua

@@ -101,6 +101,9 @@ describe('version', function()
       { v1 = 'v9.0.0',           v2 = 'v0.9.0',           want = 1, },
       { v1 = 'v0.9.0',           v2 = 'v0.0.0',           want = 1, },
       { v1 = 'v0.0.9',           v2 = 'v0.0.0',           want = 1, },
+      { v1 = 'v0.0.9+aaa',       v2 = 'v0.0.9+bbb',       want = 0, },
+
+      -- prerelease 💩 https://semver.org/#spec-item-11
       { v1 = 'v1.0.0-alpha',     v2 = 'v1.0.0',           want = -1, },
       { v1 = '1.0.0',            v2 = '1.0.0-alpha',      want = 1, },
       { v1 = '1.0.0-2',          v2 = '1.0.0-1',          want = 1, },
@@ -116,11 +119,11 @@ describe('version', function()
       { v1 = '1.0.0-alpha.beta', v2 = '1.0.0-alpha',      want = 1, },
       { v1 = '1.0.0-alpha',      v2 = '1.0.0-alpha.beta', want = -1, },
       { v1 = '1.0.0-alpha.beta', v2 = '1.0.0-beta',       want = -1, },
-      { v1 = '1.0.0-beta',       v2 = '1.0.0-alpha.beta', want = 1, },
-      { v1 = '1.0.0-beta',       v2 = '1.0.0-beta.2',     want = -1, },
-      -- TODO
-      -- { v1 = '1.0.0-beta.2',     v2 = '1.0.0-beta.11',    want = -1, },
-      { v1 = '1.0.0-beta.11',    v2 = '1.0.0-rc.1',       want = -1, },
+      { v1 = '1.0.0-beta.2',     v2 = '1.0.0-beta.11',    want = -1, },
+      { v1 = '1.0.0-beta.20',    v2 = '1.0.0-beta.11',    want = 1, },
+      { v1 = '1.0.0-alpha.20',   v2 = '1.0.0-beta.11',    want = -1, },
+      { v1 = '1.0.0-a.01.x.3',   v2 = '1.0.0-a.1.x.003',  want = 0, },
+      { v1 = 'v0.9.0-dev-92+9',  v2 = 'v0.9.0-dev-120+3', want = -1, },
     }
     for _, tc in ipairs(testcases) do
       local msg = function(s) return ('v1 %s v2'):format(s == 0 and '==' or (s == 1 and '>' or '<')) end