refactor: introduce selene, harden type defs, and use proper EmmyLua syntax (#296)

5 files changed, 44 insertions, 28 deletions

diff --git a/lua/mason-core/functional/function.lua b/lua/mason-core/functional/function.lua
index e85081ce..c6d460a5 100644
--- a/lua/mason-core/functional/function.lua
+++ b/lua/mason-core/functional/function.lua
@@ -47,8 +47,11 @@ _.partial = function(fn, ...)
     end
 end
 
-_.identity = function(a)
-    return a
+---@generic T
+---@param value T
+---@return T
+_.identity = function(value)
+    return value
 end
 
 _.always = function(a)
@@ -62,7 +65,7 @@ _.F = _.always(false)
 
 ---@generic T : fun(...)
 ---@param fn T
----@param cache_key_generator (fun(...): string | nil)|nil
+---@param cache_key_generator (fun(...): any)?
 ---@return T
 _.memoize = function(fn, cache_key_generator)
     cache_key_generator = cache_key_generator or _.identity
diff --git a/lua/mason-core/functional/init.lua b/lua/mason-core/functional/init.lua
index 8d17a572..5d4efdb7 100644
--- a/lua/mason-core/functional/init.lua
+++ b/lua/mason-core/functional/init.lua
@@ -10,13 +10,13 @@ local function lazy_require(module)
     })
 end
 
--- data
+---@module "mason-core.functional.data"
 local data = lazy_require "mason-core.functional.data"
 _.table_pack = data.table_pack
 _.enum = data.enum
 _.set_of = data.set_of
 
--- function
+---@module "mason-core.functional.function"
 local fun = lazy_require "mason-core.functional.function"
 _.curryN = fun.curryN
 _.compose = fun.compose
@@ -28,7 +28,7 @@ _.F = fun.F
 _.memoize = fun.memoize
 _.lazy = fun.lazy
 
--- list
+---@module "mason-core.functional.list"
 local list = lazy_require "mason-core.functional.list"
 _.reverse = list.reverse
 _.list_not_nil = list.list_not_nil
@@ -51,13 +51,13 @@ _.sort_by = list.sort_by
 _.uniq_by = list.uniq_by
 _.join = list.join
 
--- relation
+---@module "mason-core.functional.relation"
 local relation = lazy_require "mason-core.functional.relation"
 _.equals = relation.equals
 _.prop_eq = relation.prop_eq
 _.prop_satisfies = relation.prop_satisfies
 
--- logic
+---@module "mason-core.functional.logic"
 local logic = lazy_require "mason-core.functional.logic"
 _.all_pass = logic.all_pass
 _.any_pass = logic.any_pass
@@ -66,7 +66,7 @@ _.is_not = logic.is_not
 _.complement = logic.complement
 _.cond = logic.cond
 
--- number
+---@module "mason-core.functional.number"
 local number = lazy_require "mason-core.functional.number"
 _.negate = number.negate
 _.gt = number.gt
@@ -76,7 +76,7 @@ _.lte = number.lte
 _.inc = number.inc
 _.dec = number.dec
 
--- string
+---@module "mason-core.functional.string"
 local string = lazy_require "mason-core.functional.string"
 _.matches = string.matches
 _.format = string.format
@@ -86,7 +86,7 @@ _.trim = string.trim
 _.dedent = string.dedent
 _.starts_with = string.starts_with
 
--- table
+---@module "mason-core.functional.table"
 local tbl = lazy_require "mason-core.functional.table"
 _.prop = tbl.prop
 _.pick = tbl.pick
@@ -95,7 +95,7 @@ _.size = tbl.size
 _.to_pairs = tbl.to_pairs
 _.invert = tbl.invert
 
--- type
+---@module "mason-core.functional.type"
 local typ = lazy_require "mason-core.functional.type"
 _.is_nil = typ.is_nil
 _.is = typ.is
diff --git a/lua/mason-core/functional/list.lua b/lua/mason-core/functional/list.lua
index f30dd13d..151b9b25 100644
--- a/lua/mason-core/functional/list.lua
+++ b/lua/mason-core/functional/list.lua
@@ -87,8 +87,7 @@ _.each = fun.curryN(function(fn, list)
 end, 2)
 
 ---@generic T
----@param list T[]
----@return T[]: A shallow copy of the list.
+---@type fun(list: T[]): T[]
 _.list_copy = _.map(fun.identity)
 
 _.concat = fun.curryN(function(a, b)
@@ -173,15 +172,15 @@ _.join = fun.curryN(function(sep, list)
 end, 2)
 
 ---@generic T
----@param fun (item: T): any
+---@param id fun(item: T): any
 ---@param list T[]
 ---@return T[]
-_.uniq_by = fun.curryN(function(comp, list)
+_.uniq_by = fun.curryN(function(id, list)
     local set = {}
     local result = {}
     for i = 1, #list do
         local item = list[i]
-        local uniq_key = comp(item)
+        local uniq_key = id(item)
         if not set[uniq_key] then
             set[uniq_key] = true
             table.insert(result, item)
diff --git a/lua/mason-core/functional/logic.lua b/lua/mason-core/functional/logic.lua
index 0e0044d5..125a94ee 100644
--- a/lua/mason-core/functional/logic.lua
+++ b/lua/mason-core/functional/logic.lua
@@ -4,7 +4,8 @@ local _ = {}
 
 ---@generic T
 ---@param predicates (fun(item: T): boolean)[]
----@return fun(item: T): boolean
+---@param item T
+---@return boolean
 _.all_pass = fun.curryN(function(predicates, item)
     for i = 1, #predicates do
         if not predicates[i](item) then
@@ -16,7 +17,8 @@ end, 2)
 
 ---@generic T
 ---@param predicates (fun(item: T): boolean)[]
----@return fun(item: T): boolean
+---@param item T
+---@return boolean
 _.any_pass = fun.curryN(function(predicates, item)
     for i = 1, #predicates do
         if predicates[i](item) then
@@ -26,11 +28,12 @@ _.any_pass = fun.curryN(function(predicates, item)
     return false
 end, 2)
 
----@generic T
+---@generic T, U
 ---@param predicate fun(item: T): boolean
----@param on_true fun(item: T): any
----@param on_false fun(item: T): any
+---@param on_true fun(item: T): U
+---@param on_false fun(item: T): U
 ---@param value T
+---@return U
 _.if_else = fun.curryN(function(predicate, on_true, on_false, value)
     if predicate(value) then
         return on_true(value)
@@ -40,6 +43,7 @@ _.if_else = fun.curryN(function(predicate, on_true, on_false, value)
 end, 4)
 
 ---@param value boolean
+---@return boolean
 _.is_not = function(value)
     return not value
 end
@@ -47,10 +51,15 @@ end
 ---@generic T
 ---@param predicate fun(value: T): boolean
 ---@param value T
+---@return boolean
 _.complement = fun.curryN(function(predicate, value)
     return not predicate(value)
 end, 2)
 
+---@generic T, U
+---@param predicate_transformer_pairs {[1]: (fun(value: T): boolean), [2]: (fun(value: T): U)}[]
+---@param value T
+---@return U?
 _.cond = fun.curryN(function(predicate_transformer_pairs, value)
     for _, pair in ipairs(predicate_transformer_pairs) do
         local predicate, transformer = pair[1], pair[2]
diff --git a/lua/mason-core/functional/table.lua b/lua/mason-core/functional/table.lua
index 65d05cc8..150de9ce 100644
--- a/lua/mason-core/functional/table.lua
+++ b/lua/mason-core/functional/table.lua
@@ -2,14 +2,18 @@ local fun = require "mason-core.functional.function"
 
 local _ = {}
 
----@param index any
----@param tbl table
+---@generic T, U
+---@param index T
+---@param tbl table<T, U>
+---@return U?
 _.prop = fun.curryN(function(index, tbl)
     return tbl[index]
 end, 2)
 
----@param keys any[]
----@param tbl table
+---@generic T, U
+---@param keys T[]
+---@param tbl table<T, U>
+---@return table<T, U>
 _.pick = fun.curryN(function(keys, tbl)
     local ret = {}
     for _, key in ipairs(keys) do
@@ -21,8 +25,9 @@ end, 2)
 _.keys = fun.curryN(vim.tbl_keys, 1)
 _.size = fun.curryN(vim.tbl_count, 1)
 
----@param tbl table<any, any>
----@return any[][]
+---@generic K, V
+---@param tbl table<K, V>
+---@return { [1]: K, [2]: V }[]
 _.to_pairs = fun.curryN(function(tbl)
     local result = {}
     for k, v in pairs(tbl) do