feat(vim.version): more coercion with strict=false

Problem:
"tmux 3.2a" (output from "tmux -V") is not parsed easily.

Solution:
With `strict=false`, discard everything before the first digit.

- rename Semver => Version
- rename vim.version.version() => vim.version._version()
- rename matches() => has()
- remove `opts` from cmp()

1 files changed, 174 insertions, 93 deletions

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index e79acf079b..8d8b0d6da7 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -1,9 +1,59 @@
-local M = {}
+--- @defgroup lua-version
+---
+--- @brief The \`vim.version\` module provides functions for comparing versions and ranges
+--- conforming to the https://semver.org spec. Plugins, and plugin managers, can use this to check
+--- available tools and dependencies on the current system.
+---
+--- Example:
+---   <pre>lua
+---   local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false})
+---   if vim.version.gt(v, {3, 2, 0}) then
+---     -- ...
+---   end
+---   </pre>
+---
+--- \*vim.version()\* returns the version of the current Nvim process.
+---
+--- VERSION RANGE SPEC \*version-range\*
+---
+--- A version "range spec" defines a semantic version range which can be tested against a version,
+--- using |vim.version.range()|.
+---
+--- Supported range specs are shown in the following table.
+--- Note: suffixed versions (1.2.3-rc1) are not matched.
+---   <pre>
+---   1.2.3             is 1.2.3
+---   =1.2.3            is 1.2.3
+---   >1.2.3            greater than 1.2.3
+---   <1.2.3            before 1.2.3
+---   >=1.2.3           at least 1.2.3
+---   ~1.2.3            is >=1.2.3 <1.3.0       "reasonably close to 1.2.3"
+---   ^1.2.3            is >=1.2.3 <2.0.0       "compatible with 1.2.3"
+---   ^0.2.3            is >=0.2.3 <0.3.0       (0.x.x is special)
+---   ^0.0.1            is =0.0.1               (0.0.x is special)
+---   ^1.2              is >=1.2.0 <2.0.0       (like ^1.2.0)
+---   ~1.2              is >=1.2.0 <1.3.0       (like ~1.2.0)
+---   ^1                is >=1.0.0 <2.0.0       "compatible with 1"
+---   ~1                same                    "reasonably close to 1"
+---   1.x               same
+---   1.*               same
+---   1                 same
+---   *                 any version
+---   x                 same
+---
+---   1.2.3 - 2.3.4     is >=1.2.3 <=2.3.4
+---
+---   Partial right: missing pieces treated as x (2.3 => 2.3.x).
+---   1.2.3 - 2.3       is >=1.2.3 <2.4.0
+---   1.2.3 - 2         is >=1.2.3 <3.0.0
+---
+---   Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
+---   1.2 - 2.3.0       is 1.2.0 - 2.3.0
+---   </pre>
 
-local LazyM = {}
-M.LazyM = LazyM
+local M = {}
 
----@class Semver
+---@class Version
 ---@field [1] number
 ---@field [2] number
 ---@field [3] number
@@ -12,14 +62,14 @@ M.LazyM = LazyM
 ---@field patch number
 ---@field prerelease? string
 ---@field build? string
-local Semver = {}
-Semver.__index = Semver
+local Version = {}
+Version.__index = Version
 
-function Semver:__index(key)
-  return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Semver[key]
+function Version:__index(key)
+  return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Version[key]
 end
 
-function Semver:__newindex(key, value)
+function Version:__newindex(key, value)
   if key == 1 then
     self.major = value
   elseif key == 2 then
@@ -31,8 +81,8 @@ function Semver:__newindex(key, value)
   end
 end
 
----@param other Semver
-function Semver:__eq(other)
+---@param other Version
+function Version:__eq(other)
   for i = 1, 3 do
     if self[i] ~= other[i] then
       return false
@@ -41,7 +91,7 @@ function Semver:__eq(other)
   return self.prerelease == other.prerelease
 end
 
-function Semver:__tostring()
+function Version:__tostring()
   local ret = table.concat({ self.major, self.minor, self.patch }, '.')
   if self.prerelease then
     ret = ret .. '-' .. self.prerelease
@@ -52,8 +102,8 @@ function Semver:__tostring()
   return ret
 end
 
----@param other Semver
-function Semver:__lt(other)
+---@param other Version
+function Version:__lt(other)
   for i = 1, 3 do
     if self[i] > other[i] then
       return false
@@ -70,21 +120,32 @@ function Semver:__lt(other)
   return (self.prerelease or '') < (other.prerelease or '')
 end
 
----@param other Semver
-function Semver:__le(other)
+---@param other Version
+function Version:__le(other)
   return self < other or self == other
 end
 
----@param version string|number[]
----@param strict? boolean Reject "1.0", "0-x" or other non-conforming version strings
----@return Semver?
-function LazyM.version(version, strict)
+--- @private
+---
+--- Creates a new Version object. Not public currently.
+---
+--- @param version string|number[]|Version
+--- @param strict? boolean Reject "1.0", "0-x", "3.2a" or other non-conforming version strings
+--- @return Version?
+function M._version(version, strict) -- Adapted from https://github.com/folke/lazy.nvim
   if type(version) == 'table' then
+    if version.major then
+      return setmetatable(vim.deepcopy(version), Version)
+    end
     return setmetatable({
       major = version[1] or 0,
       minor = version[2] or 0,
       patch = version[3] or 0,
-    }, Semver)
+    }, Version)
+  end
+
+  if not strict then -- TODO: add more "scrubbing".
+    version = version:match('%d[^ ]*')
   end
 
   local prerel = version:match('%-([^+]*)')
@@ -110,11 +171,13 @@ function LazyM.version(version, strict)
       patch = patch == '' and 0 or tonumber(patch),
       prerelease = prerel ~= '' and prerel or nil,
       build = build ~= '' and build or nil,
-    }, Semver)
+    }, Version)
   end
 end
 
----@generic T: Semver
+---TODO: generalize this, move to func.lua
+---
+---@generic T: Version
 ---@param versions T[]
 ---@return T?
 function M.last(versions)
@@ -127,13 +190,15 @@ function M.last(versions)
   return last
 end
 
----@class SemverRange
----@field from Semver
----@field to? Semver
+---@class Range
+---@field from Version
+---@field to? Version
 local Range = {}
 
----@param version string|Semver
-function Range:matches(version)
+--- @private
+---
+---@param version string|Version
+function Range:has(version)
   if type(version) == 'string' then
     ---@diagnostic disable-next-line: cast-local-type
     version = M.parse(version)
@@ -146,8 +211,32 @@ function Range:matches(version)
   end
 end
 
----@param spec string
-function LazyM.range(spec)
+--- Parses a semver |version-range| "spec" and returns a range object:
+---   <pre>
+---   {
+---     from: Version
+---     to: Version
+---     has(v: string|Version)
+---   }
+---   </pre>
+---
+--- `:has()` checks if a version is in the range (inclusive `from`, exclusive `to`). Example:
+---   <pre>lua
+---   local r = vim.version.range('1.0.0 - 2.0.0')
+---   print(r:has('1.9.9'))  -- true
+---   print(r:has('2.0.0'))  -- false
+---   </pre>
+---
+--- Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly:
+---   <pre>lua
+---   local r = vim.version.range('1.0.0 - 2.0.0')
+---   print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))
+---   </pre>
+---
+--- @see # https://github.com/npm/node-semver#ranges
+---
+--- @param spec string Version range "spec"
+function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
   if spec == '*' or spec == '' then
     return setmetatable({ from = M.parse('0.0.0') }, { __index = Range })
   end
@@ -158,8 +247,8 @@ function LazyM.range(spec)
     local a = spec:sub(1, hyphen - 1)
     local b = spec:sub(hyphen + 3)
     local parts = vim.split(b, '.', { plain = true })
-    local ra = LazyM.range(a)
-    local rb = LazyM.range(b)
+    local ra = M.range(a)
+    local rb = M.range(b)
     return setmetatable({
       from = ra and ra.from,
       to = rb and (#parts == 3 and rb.from or rb.to),
@@ -209,40 +298,40 @@ function LazyM.range(spec)
 end
 
 ---@private
----@param v string
+---@param v string|Version
 ---@return string
 local function create_err_msg(v)
   if type(v) == 'string' then
     return string.format('invalid version: "%s"', tostring(v))
+  elseif type(v) == 'table' and v.major then
+    return string.format('invalid version: %s', vim.inspect(v))
   end
   return string.format('invalid version: %s (%s)', tostring(v), type(v))
 end
 
----@private
---- Throws an error if `version` cannot be parsed.
----@param v string
-local function assert_version(v, opt)
-  local rv = M.parse(v, opt)
-  if rv == nil then
-    error(create_err_msg(v))
-  end
-  return rv
-end
-
---- Parses and compares two version strings.
+--- Parses and compares two version version objects (the result of |vim.version.parse()|, or
+--- specified literally as a `{major, minor, patch}` tuple, e.g. `{1, 0, 3}`).
 ---
---- semver notes:
---- - Build metadata MUST be ignored when comparing versions.
+--- Example:
+--- <pre>lua
+---   if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then
+---     -- ...
+---   end
+---   local v1 = vim.version.parse('1.0.3-pre')
+---   local v2 = vim.version.parse('0.2.1')
+---   if vim.version.cmp(v1, v2) == 0 then
+---     -- ...
+---   end
+--- </pre>
 ---
----@param v1 string Version.
----@param v2 string Version to compare with v1.
----@param opts table|nil Optional keyword arguments:
----                      - strict (boolean):  see `version.parse` for details. Defaults to false.
----@return integer `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`.
-function M.cmp(v1, v2, opts)
-  opts = opts or { strict = false }
-  local v1_parsed = assert_version(v1, opts)
-  local v2_parsed = assert_version(v2, opts)
+--- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions.
+---
+---@param v1 Version|number[] Version object.
+---@param v2 Version|number[] Version to compare with `v1`.
+---@return integer -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`.
+function M.cmp(v1, v2)
+  local v1_parsed = assert(M._version(v1), create_err_msg(v1))
+  local v2_parsed = assert(M._version(v2), create_err_msg(v1))
   if v1_parsed == v2_parsed then
     return 0
   end
@@ -252,58 +341,50 @@ function M.cmp(v1, v2, opts)
   return -1
 end
 
---- Parses a semantic version string.
----
---- Ignores leading "v" and surrounding whitespace, e.g. " v1.0.1-rc1+build.2",
---- "1.0.1-rc1+build.2", "v1.0.1-rc1+build.2" and "v1.0.1-rc1+build.2 " are all parsed as:
---- <pre>
----   { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
---- </pre>
----
----@param version string Version string to be parsed.
----@param opts table|nil Optional keyword arguments:
----                      - strict (boolean):  Default false. If `true`, no coercion is attempted on
----                      input not strictly conforming to semver v2.0.0
----                      (https://semver.org/spec/v2.0.0.html). E.g. `parse("v1.2")` returns nil.
----@return table|nil parsed_version Parsed version table or `nil` if `version` is invalid.
-function M.parse(version, opts)
-  if type(version) ~= 'string' then
-    error(create_err_msg(version))
-  end
-  opts = opts or { strict = false }
-
-  if opts.strict then
-    return LazyM.version(version, true)
-  end
-
-  version = vim.trim(version) -- TODO: add more "scrubbing".
-  return LazyM.version(version, false)
-end
-
----Returns `true` if `v1` are `v2` are equal versions.
----@param v1 string
----@param v2 string
+---Returns `true` if the given versions are equal.
+---@param v1 Version|number[]
+---@param v2 Version|number[]
 ---@return boolean
 function M.eq(v1, v2)
   return M.cmp(v1, v2) == 0
 end
 
----Returns `true` if `v1` is less than `v2`.
----@param v1 string
----@param v2 string
+---Returns `true` if `v1 < v2`.
+---@param v1 Version|number[]
+---@param v2 Version|number[]
 ---@return boolean
 function M.lt(v1, v2)
   return M.cmp(v1, v2) == -1
 end
 
----Returns `true` if `v1` is greater than `v2`.
----@param v1 string
----@param v2 string
+---Returns `true` if `v1 > v2`.
+---@param v1 Version|number[]
+---@param v2 Version|number[]
 ---@return boolean
 function M.gt(v1, v2)
   return M.cmp(v1, v2) == 1
 end
 
+--- Parses a semantic version string and returns a version object which can be used with other
+--- `vim.version` functions. For example "1.0.1-rc1+build.2" returns:
+--- <pre>
+---   { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
+--- </pre>
+---
+--- @see # https://semver.org/spec/v2.0.0.html
+---
+---@param version string Version string to parse.
+---@param opts table|nil Optional keyword arguments:
+---                      - strict (boolean):  Default false. If `true`, no coercion is attempted on
+---                      input not conforming to semver v2.0.0. If `false`, `parse()` attempts to
+---                      coerce input such as "1.0", "0-x", "tmux 3.2a" into valid versions.
+---@return table|nil parsed_version Version object or `nil` if input is invalid.
+function M.parse(version, opts)
+  assert(type(version) == 'string', create_err_msg(version))
+  opts = opts or { strict = false }
+  return M._version(version, opts.strict)
+end
+
 setmetatable(M, {
   __call = function()
     return vim.fn.api_info().version