refactor(git): introduce Revision class, normalize naming, slim docs

lua/git/revision.lua

@@ -0,0 +1,61 @@
+---@class ow.Git.Revision
+---@field stage 0|1|2|3?
+---@field path string?
+---@field base string?
+local Revision = {}
+Revision.__index = Revision
+
+local URI_PREFIX = "git://"
+
+---@return string
+function Revision:format()
+    if self.stage then
+        return ":" .. self.stage .. ":" .. self.path
+    elseif self.path then
+        return self.base .. ":" .. self.path
+    end
+    return self.base or error("Revision:format: empty Revision")
+end
+
+---@return string
+function Revision:uri()
+    return URI_PREFIX .. self:format()
+end
+
+---@param parts { stage?: integer, base?: string, path?: string }
+---@return ow.Git.Revision
+function Revision.new(parts)
+    return setmetatable(parts, Revision)
+end
+
+---@param str string
+---@return ow.Git.Revision
+function Revision.parse(str)
+    local stage, path = str:match("^:([0123]):(.+)$")
+    if stage then
+        return Revision.new({
+            stage = tonumber(stage) --[[@as (0|1|2|3)?]],
+            path = path,
+        })
+    end
+    path = str:match("^:([^:]+)$")
+    if path then
+        return Revision.new({ stage = 0, path = path })
+    end
+    local base, p = str:match("^([^:]+):(.+)$")
+    if base then
+        return Revision.new({ base = base, path = p })
+    end
+    return Revision.new({ base = str })
+end
+
+---@param str string
+---@return ow.Git.Revision?
+function Revision.from_uri(str)
+    local raw = str:match("^" .. URI_PREFIX .. "(.+)$")
+    if raw then
+        return Revision.parse(raw)
+    end
+end
+
+return Revision