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

44 files changed, 265 insertions, 231 deletions

diff --git a/lua/mason-core/async/init.lua b/lua/mason-core/async/init.lua
index 7805cade..05401ca2 100644
--- a/lua/mason-core/async/init.lua
+++ b/lua/mason-core/async/init.lua
@@ -39,7 +39,7 @@ local function table_pack(...)
 end
 
 ---@param async_fn fun(...)
----@param should_reject_err boolean|nil: Whether the provided async_fn takes a callback with the signature `fun(err, result)`
+---@param should_reject_err boolean? Whether the provided async_fn takes a callback with the signature `fun(err, result)`
 local function promisify(async_fn, should_reject_err)
     return function(...)
         local args = table_pack(...)
@@ -64,11 +64,12 @@ local function promisify(async_fn, should_reject_err)
 end
 
 local function new_execution_context(suspend_fn, callback, ...)
+    ---@type thread?
     local thread = co.create(suspend_fn)
     local cancelled = false
     local step
     step = function(...)
-        if cancelled then
+        if cancelled or not thread then
             return
         end
         local ok, promise_or_result = co.resume(thread, ...)
@@ -103,7 +104,6 @@ end
 
 ---@generic T
 ---@param suspend_fn T
----@return T
 exports.scope = function(suspend_fn)
     return function(...)
         return new_execution_context(suspend_fn, function(success, err)
diff --git a/lua/mason-core/fetch.lua b/lua/mason-core/fetch.lua
index 8aca8b89..3bb7a214 100644
--- a/lua/mason-core/fetch.lua
+++ b/lua/mason-core/fetch.lua
@@ -14,12 +14,12 @@ local USER_AGENT = "mason.nvim (+https://github.com/williamboman/mason.nvim)"
 ---| '"PATCH"'
 ---| '"DELETE"'
 
----@alias FetchOpts {out_file: string, method: FetchMethod, headers: table<string, string>, data: string}
+---@alias FetchOpts {out_file: string?, method: FetchMethod?, headers: table<string, string>?, data: string?}
 
 ---@async
----@param url string: The url to fetch.
----@param opts FetchOpts | nil
----@return Result: Result<string>
+---@param url string The url to fetch.
+---@param opts FetchOpts?
+---@return Result # Result<string>
 local function fetch(url, opts)
     opts = opts or {}
     if not opts.headers then
diff --git a/lua/mason-core/fs.lua b/lua/mason-core/fs.lua
index f11c83c5..820b938a 100644
--- a/lua/mason-core/fs.lua
+++ b/lua/mason-core/fs.lua
@@ -86,7 +86,7 @@ local function make_module(uv)
 
     ---@param path string
     ---@param contents string
-    ---@param flags string|nil: Defaults to "w".
+    ---@param flags string? Defaults to "w".
     function M.write_file(path, contents, flags)
         log.debug("fs: write_file", path)
         local fd = uv.fs_open(path, flags or "w", 438)
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
diff --git a/lua/mason-core/installer/context.lua b/lua/mason-core/installer/context.lua
index b3801330..b8706698 100644
--- a/lua/mason-core/installer/context.lua
+++ b/lua/mason-core/installer/context.lua
@@ -53,39 +53,39 @@ function ContextualFs.new(cwd)
 end
 
 ---@async
----@param rel_path string: The relative path from the current working directory to the file to append.
+---@param rel_path string The relative path from the current working directory to the file to append.
 ---@param contents string
 function ContextualFs:append_file(rel_path, contents)
     return fs.async.append_file(path.concat { self.cwd:get(), rel_path }, contents)
 end
 
 ---@async
----@param rel_path string: The relative path from the current working directory to the file to write.
+---@param rel_path string The relative path from the current working directory to the file to write.
 ---@param contents string
 function ContextualFs:write_file(rel_path, contents)
     return fs.async.write_file(path.concat { self.cwd:get(), rel_path }, contents)
 end
 
 ---@async
----@param rel_path string: The relative path from the current working directory.
+---@param rel_path string The relative path from the current working directory.
 function ContextualFs:file_exists(rel_path)
     return fs.async.file_exists(path.concat { self.cwd:get(), rel_path })
 end
 
 ---@async
----@param rel_path string: The relative path from the current working directory.
+---@param rel_path string The relative path from the current working directory.
 function ContextualFs:dir_exists(rel_path)
     return fs.async.dir_exists(path.concat { self.cwd:get(), rel_path })
 end
 
 ---@async
----@param rel_path string: The relative path from the current working directory.
+---@param rel_path string The relative path from the current working directory.
 function ContextualFs:rmrf(rel_path)
     return fs.async.rmrf(path.concat { self.cwd:get(), rel_path })
 end
 
 ---@async
----@param rel_path string: The relative path from the current working directory.
+---@param rel_path string The relative path from the current working directory.
 function ContextualFs:unlink(rel_path)
     return fs.async.unlink(path.concat { self.cwd:get(), rel_path })
 end
@@ -104,13 +104,13 @@ function ContextualFs:mkdir(dirpath)
 end
 
 ---@class CwdManager
----@field private install_prefix string: Defines the upper boundary for which paths are allowed as cwd.
+---@field private install_prefix string Defines the upper boundary for which paths are allowed as cwd.
 ---@field private cwd string
 local CwdManager = {}
 CwdManager.__index = CwdManager
 
 function CwdManager.new(install_prefix)
-    assert(type(install_prefix) == "string")
+    assert(type(install_prefix) == "string", "install_prefix not provided")
     return setmetatable({
         install_prefix = install_prefix,
         cwd = nil,
@@ -124,7 +124,7 @@ end
 
 ---@param new_cwd string
 function CwdManager:set(new_cwd)
-    assert(type(new_cwd) == "string")
+    assert(type(new_cwd) == "string", "new_cwd is not a string")
     assert(
         path.is_subdirectory(self.install_prefix, new_cwd),
         ("%q is not a subdirectory of %q"):format(new_cwd, self.install_prefix)
@@ -145,7 +145,7 @@ local InstallContext = {}
 InstallContext.__index = InstallContext
 
 ---@class InstallContextOpts
----@field requested_version string|nil
+---@field requested_version string?
 
 ---@param handle InstallHandle
 ---@param opts InstallContextOpts
@@ -185,8 +185,8 @@ function InstallContext:promote_cwd()
     self.cwd:set(install_path)
 end
 
----@param rel_path string: The relative path from the current working directory to change cwd to. Will only restore to the initial cwd after execution of fn (if provided).
----@param fn async (fun()): (optional) The function to run in the context of the given path.
+---@param rel_path string The relative path from the current working directory to change cwd to. Will only restore to the initial cwd after execution of fn (if provided).
+---@param fn async (fun())? The function to run in the context of the given path.
 function InstallContext:chdir(rel_path, fn)
     local old_cwd = self.cwd:get()
     self.cwd:set(path.concat { old_cwd, rel_path })
@@ -200,8 +200,8 @@ function InstallContext:chdir(rel_path, fn)
     end
 end
 
----@param new_executable_rel_path string: Relative path to the executable file to create.
----@param script_rel_path string: Relative path to the Node.js script.
+---@param new_executable_rel_path string Relative path to the executable file to create.
+---@param script_rel_path string Relative path to the Node.js script.
 function InstallContext:write_node_exec_wrapper(new_executable_rel_path, script_rel_path)
     return self:write_shell_exec_wrapper(
         new_executable_rel_path,
@@ -212,8 +212,8 @@ function InstallContext:write_node_exec_wrapper(new_executable_rel_path, script_
     )
 end
 
----@param new_executable_rel_path string: Relative path to the executable file to create.
----@param module string: The python module to call.
+---@param new_executable_rel_path string Relative path to the executable file to create.
+---@param module string The python module to call.
 function InstallContext:write_pyvenv_exec_wrapper(new_executable_rel_path, module)
     return self:write_shell_exec_wrapper(
         new_executable_rel_path,
@@ -227,7 +227,7 @@ function InstallContext:write_pyvenv_exec_wrapper(new_executable_rel_path, modul
     )
 end
 
----@param new_executable_rel_path string: Relative path to the executable file to create.
+---@param new_executable_rel_path string Relative path to the executable file to create.
 ---@param target_executable_rel_path string
 function InstallContext:write_exec_wrapper(new_executable_rel_path, target_executable_rel_path)
     return self:write_shell_exec_wrapper(
@@ -251,10 +251,10 @@ local BATCH_TEMPLATE = _.dedent [[
 %s %%*
 ]]
 
----@param new_executable_rel_path string: Relative path to the executable file to create.
----@param command string: The shell command to run.
+---@param new_executable_rel_path string Relative path to the executable file to create.
+---@param command string The shell command to run.
 ---@param env table<string, string>?
----@return string: The created executable filename.
+---@return string # The created executable filename.
 function InstallContext:write_shell_exec_wrapper(new_executable_rel_path, command, env)
     return platform.when {
         unix = function()
diff --git a/lua/mason-core/installer/handle.lua b/lua/mason-core/installer/handle.lua
index 7a3fc40f..d88dbaf5 100644
--- a/lua/mason-core/installer/handle.lua
+++ b/lua/mason-core/installer/handle.lua
@@ -35,7 +35,7 @@ end
 ---@class InstallHandle : EventEmitter
 ---@field package Package
 ---@field state InstallHandleState
----@field stdio { buffers: { stdout: string[], stderr: string[] }, sink: StdioSink  }
+---@field stdio { buffers: { stdout: string[], stderr: string[] }, sink: StdioSink }
 ---@field is_terminated boolean
 ---@field private spawn_handles InstallHandleSpawnHandle[]
 local InstallHandle = setmetatable({}, { __index = EventEmitter })
@@ -99,7 +99,7 @@ function InstallHandle:deregister_spawn_handle(luv_handle)
     return false
 end
 
----@return Optional: Optional<InstallHandleSpawnHandle>
+---@return Optional # Optional<InstallHandleSpawnHandle>
 function InstallHandle:peek_spawn_handle()
     return Optional.of_nilable(self.spawn_handles[#self.spawn_handles])
 end
diff --git a/lua/mason-core/installer/init.lua b/lua/mason-core/installer/init.lua
index ecf4f2f0..2ab33bc6 100644
--- a/lua/mason-core/installer/init.lua
+++ b/lua/mason-core/installer/init.lua
@@ -152,7 +152,7 @@ function M.execute(handle, opts)
                 fs.async.rmrf(context.cwd:get())
             end)
 
-            -- unlink linked executables (in the rare occassion an error occurs after linking)
+            -- unlink linked executables (in the rare occasion an error occurs after linking)
             linker.unlink(context.package, context.receipt.links)
 
             if not handle:is_closed() and not handle.is_terminated then
diff --git a/lua/mason-core/log.lua b/lua/mason-core/log.lua
index a2593a56..91505156 100644
--- a/lua/mason-core/log.lua
+++ b/lua/mason-core/log.lua
@@ -37,6 +37,7 @@ local log = {
     },
 }
 
+-- selene: allow(incorrect_standard_library_use)
 local unpack = unpack or table.unpack
 
 do
diff --git a/lua/mason-core/managers/cargo/client.lua b/lua/mason-core/managers/cargo/client.lua
index ae04691d..d5ecb283 100644
--- a/lua/mason-core/managers/cargo/client.lua
+++ b/lua/mason-core/managers/cargo/client.lua
@@ -6,7 +6,7 @@ local M = {}
 
 ---@async
 ---@param crate string
----@return Result: of Crate
+---@return Result # Result<CrateResponse>
 function M.fetch_crate(crate)
     return fetch(("https://crates.io/api/v1/crates/%s"):format(crate)):map_catching(vim.json.decode)
 end
diff --git a/lua/mason-core/managers/cargo/init.lua b/lua/mason-core/managers/cargo/init.lua
index 2dcc3a69..b8cd4fa7 100644
--- a/lua/mason-core/managers/cargo/init.lua
+++ b/lua/mason-core/managers/cargo/init.lua
@@ -23,7 +23,7 @@ local M = {}
 
 ---@async
 ---@param crate string The crate to install.
----@param opts {git: boolean | string, features: string|nil, bin: string[] | nil } | nil
+---@param opts {git: boolean | string, features: string?, bin: string[]? }?
 function M.crate(crate, opts)
     return function()
         M.install(crate, opts).with_receipt()
@@ -32,7 +32,7 @@ end
 
 ---@async
 ---@param crate string The crate to install.
----@param opts {git: boolean | string, features: string|nil, bin: string[] | nil } | nil
+---@param opts {git: boolean | string, features: string?, bin: string[]? }?
 function M.install(crate, opts)
     local ctx = installer.context()
     opts = opts or {}
@@ -40,6 +40,7 @@ function M.install(crate, opts)
         assert(not opts.git, "Providing a version when installing a git crate is not allowed.")
     end)
 
+    ---@type string | string[]
     local final_crate = crate
 
     if opts.git then
@@ -75,8 +76,8 @@ function M.install(crate, opts)
     }
 end
 
----@param output string: The `cargo install --list` output.
----@return table<string, string>: Key is the crate name, value is its version.
+---@param output string The `cargo install --list` output.
+---@return table<string, string> # Key is the crate name, value is its version.
 function M.parse_installed_crates(output)
     local installed_crates = {}
     for _, line in ipairs(vim.split(output, "\n")) do
@@ -89,7 +90,7 @@ function M.parse_installed_crates(output)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_primary_package(receipt, install_dir)
     return M.get_installed_primary_package_version(receipt, install_dir):map_catching(function(installed_version)
@@ -108,7 +109,7 @@ function M.check_outdated_primary_package(receipt, install_dir)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_primary_package_version(receipt, install_dir)
     return spawn
diff --git a/lua/mason-core/managers/composer/init.lua b/lua/mason-core/managers/composer/init.lua
index 2301ac2b..1987d4bd 100644
--- a/lua/mason-core/managers/composer/init.lua
+++ b/lua/mason-core/managers/composer/init.lua
@@ -25,7 +25,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.require(packages).with_receipt()
@@ -33,7 +33,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The composer packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.require(packages)
     local ctx = installer.context()
     local pkgs = _.list_copy(packages)
@@ -72,7 +72,7 @@ function M.install()
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_primary_package(receipt, install_dir)
     if receipt.primary_source.type ~= "composer" then
@@ -105,7 +105,7 @@ function M.check_outdated_primary_package(receipt, install_dir)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_primary_package_version(receipt, install_dir)
     if receipt.primary_source.type ~= "composer" then
diff --git a/lua/mason-core/managers/dotnet/init.lua b/lua/mason-core/managers/dotnet/init.lua
index 62f4d76a..4ad752b6 100644
--- a/lua/mason-core/managers/dotnet/init.lua
+++ b/lua/mason-core/managers/dotnet/init.lua
@@ -16,7 +16,7 @@ end
 
 ---@async
 ---@param pkg string
----@param opt { bin: string[] | nil } | nil
+---@param opt { bin: string[]? }?
 function M.package(pkg, opt)
     return function()
         return M.install(pkg, opt).with_receipt()
@@ -25,7 +25,7 @@ end
 
 ---@async
 ---@param pkg string
----@param opt { bin: string[] | nil } | nil
+---@param opt { bin: string[]? }?
 function M.install(pkg, opt)
     local ctx = installer.context()
     ctx.spawn.dotnet {
diff --git a/lua/mason-core/managers/gem/init.lua b/lua/mason-core/managers/gem/init.lua
index da9b800b..0cbca3ae 100644
--- a/lua/mason-core/managers/gem/init.lua
+++ b/lua/mason-core/managers/gem/init.lua
@@ -54,7 +54,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -62,7 +62,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The Gem packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = _.list_copy(packages or {})
@@ -100,7 +100,7 @@ end
 function M.parse_outdated_gem(outdated_gem)
     local package_name, version_expression = outdated_gem:match "^(.+) %((.+)%)"
     if not package_name or not version_expression then
-        -- unparseable
+        -- unparsable
         return nil
     end
     local current_version, latest_version = unpack(vim.split(version_expression, "<"))
@@ -133,7 +133,7 @@ local function not_empty(s)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_primary_package(receipt, install_dir)
     if receipt.primary_source.type ~= "gem" then
@@ -152,8 +152,8 @@ function M.check_outdated_primary_package(receipt, install_dir)
             :map(function(gem)
                 return {
                     name = receipt.primary_source.package,
-                    current_version = assert(gem.current_version),
-                    latest_version = assert(gem.latest_version),
+                    current_version = assert(gem.current_version, "current_version missing in gem"),
+                    latest_version = assert(gem.latest_version, "latest_version missing in gem"),
                 }
             end)
             :or_else_throw "Primary package is not outdated."
@@ -161,7 +161,7 @@ function M.check_outdated_primary_package(receipt, install_dir)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_primary_package_version(receipt, install_dir)
     return spawn
diff --git a/lua/mason-core/managers/git/init.lua b/lua/mason-core/managers/git/init.lua
index c363cbe8..aea3b47f 100644
--- a/lua/mason-core/managers/git/init.lua
+++ b/lua/mason-core/managers/git/init.lua
@@ -14,7 +14,7 @@ local function with_receipt(repo)
 end
 
 ---@async
----@param opts {[1]: string, recursive: boolean, version: Optional|nil}: The first item in the table is the repository to clone.
+---@param opts {[1]: string, recursive: boolean, version: Optional?} The first item in the table is the repository to clone.
 function M.clone(opts)
     local ctx = installer.context()
     local repo = assert(opts[1], "No git URL provided.")
@@ -37,7 +37,7 @@ function M.clone(opts)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_git_clone(receipt, install_dir)
     if receipt.primary_source.type ~= "git" then
@@ -51,14 +51,14 @@ function M.check_outdated_git_clone(receipt, install_dir)
         end
         return {
             name = receipt.primary_source.remote,
-            current_version = assert(local_head),
-            latest_version = assert(remote_head),
+            current_version = assert(local_head, "no local HEAD"),
+            latest_version = assert(remote_head, "no remote HEAD"),
         }
     end)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_revision(receipt, install_dir)
     return spawn
diff --git a/lua/mason-core/managers/github/client.lua b/lua/mason-core/managers/github/client.lua
index 80011e22..894df658 100644
--- a/lua/mason-core/managers/github/client.lua
+++ b/lua/mason-core/managers/github/client.lua
@@ -10,7 +10,7 @@ local M = {}
 ---@alias GitHubTag {name: string}
 
 ---@param path string
----@return Result: JSON decoded response.
+---@return Result # JSON decoded response.
 local function api_call(path)
     return spawn
         .gh({ "api", path })
@@ -22,8 +22,8 @@ local function api_call(path)
 end
 
 ---@async
----@param repo string: The GitHub repo ("username/repo").
----@return Result: of GitHubRelease[]
+---@param repo string The GitHub repo ("username/repo").
+---@return Result # Result<GitHubRelease[]>
 function M.fetch_releases(repo)
     log.fmt_trace("Fetching GitHub releases for repo=%s", repo)
     local path = ("repos/%s/releases"):format(repo)
@@ -33,8 +33,8 @@ function M.fetch_releases(repo)
 end
 
 ---@async
----@param repo string: The GitHub repo ("username/repo").
----@param tag_name string: The tag_name of the release to fetch.
+---@param repo string The GitHub repo ("username/repo").
+---@param tag_name string The tag_name of the release to fetch.
 function M.fetch_release(repo, tag_name)
     log.fmt_trace("Fetching GitHub release for repo=%s, tag_name=%s", repo, tag_name)
     local path = ("repos/%s/releases/tags/%s"):format(repo, tag_name)
@@ -56,12 +56,12 @@ function M.release_predicate(opts)
     }
 end
 
----@alias FetchLatestGithubReleaseOpts {tag_name_pattern:string|nil, include_prerelease: boolean}
+---@alias FetchLatestGithubReleaseOpts {tag_name_pattern:string?, include_prerelease: boolean}
 
 ---@async
----@param repo string: The GitHub repo ("username/repo").
----@param opts FetchLatestGithubReleaseOpts|nil
----@return Result: of GitHubRelease
+---@param repo string The GitHub repo ("username/repo").
+---@param opts FetchLatestGithubReleaseOpts?
+---@return Result # Result<GitHubRelease>
 function M.fetch_latest_release(repo, opts)
     opts = opts or {
         tag_name_pattern = nil,
@@ -86,8 +86,8 @@ function M.fetch_latest_release(repo, opts)
 end
 
 ---@async
----@param repo string: The GitHub repo ("username/repo").
----@return Result: of GitHubTag[]
+---@param repo string The GitHub repo ("username/repo").
+---@return Result # Result<GitHubTag[]>
 function M.fetch_tags(repo)
     local path = ("repos/%s/tags"):format(repo)
     return api_call(path):map_err(function()
@@ -96,8 +96,8 @@ function M.fetch_tags(repo)
 end
 
 ---@async
----@param repo string: The GitHub repo ("username/repo").
----@return Result: Result<string> - The latest tag name.
+---@param repo string The GitHub repo ("username/repo").
+---@return Result # Result<string> The latest tag name.
 function M.fetch_latest_tag(repo)
     -- https://github.com/williamboman/vercel-github-api-latest-tag-proxy
     return fetch(("https://latest-github-tag.redwill.se/api/repo/%s/latest-tag"):format(repo))
diff --git a/lua/mason-core/managers/github/init.lua b/lua/mason-core/managers/github/init.lua
index a0336d30..2634d02b 100644
--- a/lua/mason-core/managers/github/init.lua
+++ b/lua/mason-core/managers/github/init.lua
@@ -8,10 +8,17 @@ local settings = require "mason.settings"
 
 local M = {}
 
+---@class InstallReceiptGitHubReleaseFileSource
+---@field type '"github_release_file"'
+---@field repo string
+---@field file string
+---@field release string
+
 ---@param repo string
 ---@param asset_file string
 ---@param release string
 local function with_release_file_receipt(repo, asset_file, release)
+    ---@return InstallReceiptGitHubReleaseFileSource
     return function()
         local ctx = installer.context()
         ctx.receipt:with_primary_source {
@@ -23,6 +30,11 @@ local function with_release_file_receipt(repo, asset_file, release)
     end
 end
 
+---@class InstallReceiptGitHubTagSource
+---@field type '"github_tag"'
+---@field repo string
+---@field tag string
+
 ---@param repo string
 ---@param tag string
 local function with_tag_receipt(repo, tag)
@@ -37,7 +49,7 @@ local function with_tag_receipt(repo, tag)
 end
 
 ---@async
----@param opts {repo: string, version: Optional|nil, asset_file: string|fun(release: string):string}
+---@param opts {repo: string, version: Optional?, asset_file: string|fun(release: string):string}
 function M.release_file(opts)
     local ctx = installer.context()
     local release = _.coalesce(opts.version, ctx.requested_version):or_else_get(function()
@@ -50,7 +62,7 @@ function M.release_file(opts)
     local asset_file
     if type(opts.asset_file) == "function" then
         asset_file = opts.asset_file(release)
-    else
+    elseif type(asset_file) == "string" then
         asset_file = opts.asset_file
     end
     if not asset_file then
@@ -71,7 +83,7 @@ function M.release_file(opts)
 end
 
 ---@async
----@param opts {repo: string, version: Optional|nil}
+---@param opts {repo: string, version: Optional?}
 function M.tag(opts)
     local ctx = installer.context()
     local tag = _.coalesce(opts.version, ctx.requested_version):or_else_get(function()
@@ -128,7 +140,7 @@ function M.gunzip_release_file(opts)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptGitHubReleaseFileSource>
 function M.check_outdated_primary_package_release(receipt)
     local source = receipt.primary_source
     if source.type ~= "github_release" and source.type ~= "github_release_file" then
@@ -150,7 +162,7 @@ function M.check_outdated_primary_package_release(receipt)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptGitHubTagSource>
 function M.check_outdated_primary_package_tag(receipt)
     local source = receipt.primary_source
     if source.type ~= "github_tag" then
diff --git a/lua/mason-core/managers/go/init.lua b/lua/mason-core/managers/go/init.lua
index ecb3f82d..71721c50 100644
--- a/lua/mason-core/managers/go/init.lua
+++ b/lua/mason-core/managers/go/init.lua
@@ -23,7 +23,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The go packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The go packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         M.install(packages).with_receipt()
@@ -31,7 +31,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The go packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The go packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local env = {
@@ -65,7 +65,7 @@ function M.install(packages)
     }
 end
 
----@param output string: The output from `go version -m` command.
+---@param output string The output from `go version -m` command.
 function M.parse_mod_version_output(output)
     ---@type {path: string[], mod: string[], dep: string[], build: string[]}
     local result = {}
@@ -100,6 +100,7 @@ function M.parse_package_mod(pkg)
             components[4], -- repo
         }))
     else
+        -- selene: allow(if_same_then_else)
         local components = _.split("/", pkg)
         return trim_wildcard_suffix(_.join("/", {
             components[1],
@@ -110,7 +111,7 @@ function M.parse_package_mod(pkg)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_primary_package_version(receipt, install_dir)
     if vim.in_fast_event() then
@@ -134,7 +135,7 @@ function M.get_installed_primary_package_version(receipt, install_dir)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_primary_package(receipt, install_dir)
     local normalized_pkg_name = M.parse_package_mod(receipt.primary_source.package)
@@ -156,8 +157,8 @@ function M.check_outdated_primary_package(receipt, install_dir)
                     if installed_version ~= latest_version then
                         return {
                             name = normalized_pkg_name,
-                            current_version = assert(installed_version),
-                            latest_version = assert(latest_version),
+                            current_version = assert(installed_version, "missing installed_version"),
+                            latest_version = assert(latest_version, "missing latest_version"),
                         }
                     end
                 end)
diff --git a/lua/mason-core/managers/luarocks/init.lua b/lua/mason-core/managers/luarocks/init.lua
index 9fd59ca1..81d9ae89 100644
--- a/lua/mason-core/managers/luarocks/init.lua
+++ b/lua/mason-core/managers/luarocks/init.lua
@@ -20,8 +20,8 @@ local function with_receipt(package)
     end
 end
 
----@param package string: The luarock package to install.
----@param opts { dev: boolean?, server: string?, bin : string[]? | nil }?
+---@param package string The luarock package to install.
+---@param opts { dev: boolean?, server: string?, bin: string[]? }?
 function M.package(package, opts)
     return function()
         return M.install(package, opts).with_receipt()
@@ -30,7 +30,7 @@ end
 
 ---@async
 ---@param pkg string: The luarock package to install.
----@param opts { dev: boolean?, server: string?, bin : string[]? | nil }?
+---@param opts { dev: boolean?, server: string?, bin: string[]? }?
 function M.install(pkg, opts)
     opts = opts or {}
     local ctx = installer.context()
@@ -67,7 +67,7 @@ M.parse_installed_rocks = _.compose(
 )
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_primary_package_version(receipt, install_dir)
     if receipt.primary_source.type ~= "luarocks" then
@@ -102,7 +102,7 @@ M.parse_outdated_rocks = _.compose(
 )
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_primary_package(receipt, install_dir)
     if receipt.primary_source.type ~= "luarocks" then
@@ -125,8 +125,8 @@ function M.check_outdated_primary_package(receipt, install_dir)
                     function(outdated_rock)
                         return {
                             name = outdated_rock.name,
-                            current_version = assert(outdated_rock.installed),
-                            latest_version = assert(outdated_rock.available),
+                            current_version = assert(outdated_rock.installed, "missing installed luarock version"),
+                            latest_version = assert(outdated_rock.available, "missing available luarock version"),
                         }
                     end
                 )
diff --git a/lua/mason-core/managers/npm/init.lua b/lua/mason-core/managers/npm/init.lua
index 5bb2a087..84d9258a 100644
--- a/lua/mason-core/managers/npm/init.lua
+++ b/lua/mason-core/managers/npm/init.lua
@@ -35,7 +35,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -43,7 +43,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The npm packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = list_copy(packages)
@@ -76,21 +76,21 @@ function M.install(packages)
 end
 
 ---@async
----@param exec_args string[]: The arguments to pass to npm exec.
+---@param exec_args string[] The arguments to pass to npm exec.
 function M.exec(exec_args)
     local ctx = installer.context()
     ctx.spawn.npm { "exec", "--yes", "--", exec_args }
 end
 
 ---@async
----@param script string: The npm script to run.
+---@param script string The npm script to run.
 function M.run(script)
     local ctx = installer.context()
     ctx.spawn.npm { "run", script }
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_primary_package_version(receipt, install_dir)
     if receipt.primary_source.type ~= "npm" then
@@ -103,7 +103,7 @@ function M.get_installed_primary_package_version(receipt, install_dir)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_primary_package(receipt, install_dir)
     if receipt.primary_source.type ~= "npm" then
@@ -123,8 +123,8 @@ function M.check_outdated_primary_package(receipt, install_dir)
                 if outdated_package.current ~= outdated_package.latest then
                     return {
                         name = primary_package,
-                        current_version = assert(outdated_package.current),
-                        latest_version = assert(outdated_package.latest),
+                        current_version = assert(outdated_package.current, "missing current npm package version"),
+                        latest_version = assert(outdated_package.latest, "missing latest npm package version"),
                     }
                 end
             end)
diff --git a/lua/mason-core/managers/opam/init.lua b/lua/mason-core/managers/opam/init.lua
index 4e12a97f..641fb5ff 100644
--- a/lua/mason-core/managers/opam/init.lua
+++ b/lua/mason-core/managers/opam/init.lua
@@ -23,7 +23,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -31,7 +31,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The opam packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = list_copy(packages)
diff --git a/lua/mason-core/managers/pip3/init.lua b/lua/mason-core/managers/pip3/init.lua
index d4eb07b6..078f4c3d 100644
--- a/lua/mason-core/managers/pip3/init.lua
+++ b/lua/mason-core/managers/pip3/init.lua
@@ -27,7 +27,7 @@ local function with_receipt(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.packages(packages)
     return function()
         return M.install(packages).with_receipt()
@@ -35,7 +35,7 @@ function M.packages(packages)
 end
 
 ---@async
----@param packages { [number]: string, bin: string[] | nil }: The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
+---@param packages { [number]: string, bin: string[]? } The pip packages to install. The first item in this list will be the recipient of the requested version, if set.
 function M.install(packages)
     local ctx = installer.context()
     local pkgs = _.list_copy(packages)
@@ -90,7 +90,7 @@ function M.normalize_package(pkg)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.check_outdated_primary_package(receipt, install_dir)
     if receipt.primary_source.type ~= "pip3" then
@@ -121,8 +121,8 @@ function M.check_outdated_primary_package(receipt, install_dir)
                 :map(function(pkg)
                     return {
                         name = normalized_package,
-                        current_version = assert(pkg.version),
-                        latest_version = assert(pkg.latest_version),
+                        current_version = assert(pkg.version, "missing current pip3 package version"),
+                        latest_version = assert(pkg.latest_version, "missing latest pip3 package version"),
                     }
                 end)
                 :or_else_throw "Primary package is not outdated."
@@ -130,7 +130,7 @@ function M.check_outdated_primary_package(receipt, install_dir)
 end
 
 ---@async
----@param receipt InstallReceipt
+---@param receipt InstallReceipt<InstallReceiptPackageSource>
 ---@param install_dir string
 function M.get_installed_primary_package_version(receipt, install_dir)
     if receipt.primary_source.type ~= "pip3" then
diff --git a/lua/mason-core/managers/powershell/init.lua b/lua/mason-core/managers/powershell/init.lua
index 209e0fe1..c0d36f2e 100644
--- a/lua/mason-core/managers/powershell/init.lua
+++ b/lua/mason-core/managers/powershell/init.lua
@@ -9,38 +9,42 @@ local PWSHOPT = {
 }
 
 ---@param script string
----@param opts JobSpawnOpts | nil
----@param custom_spawn JobSpawn | nil
+---@param opts JobSpawnOpts?
+---@param custom_spawn JobSpawn?
 function M.script(script, opts, custom_spawn)
     opts = opts or {}
     ---@type JobSpawn
     local spawner = custom_spawn or spawn
-    return spawner.powershell(vim.tbl_extend("keep", {
-        "-NoProfile",
-        on_spawn = function(_, stdio)
-            local stdin = stdio[1]
-            stdin:write(PWSHOPT.progress_preference)
-            stdin:write(PWSHOPT.security_protocol)
-            stdin:write(script)
-            stdin:close()
-        end,
-        env_raw = process.graft_env(opts.env or {}, { "PSMODULEPATH" }),
-    }, opts))
+    return spawner.powershell(
+        vim.tbl_extend("keep", {
+            "-NoProfile",
+            on_spawn = function(_, stdio)
+                local stdin = stdio[1]
+                stdin:write(PWSHOPT.progress_preference)
+                stdin:write(PWSHOPT.security_protocol)
+                stdin:write(script)
+                stdin:close()
+            end,
+            env_raw = process.graft_env(opts.env or {}, { "PSMODULEPATH" }),
+        }, opts) --[[@as JobSpawnOpts]]
+    )
 end
 
 ---@param command string
----@param opts JobSpawnOpts | nil
----@param custom_spawn JobSpawn | nil
+---@param opts JobSpawnOpts?
+---@param custom_spawn JobSpawn?
 function M.command(command, opts, custom_spawn)
     opts = opts or {}
     ---@type JobSpawn
     local spawner = custom_spawn or spawn
-    return spawner.powershell(vim.tbl_extend("keep", {
-        "-NoProfile",
-        "-Command",
-        PWSHOPT.progress_preference .. PWSHOPT.security_protocol .. command,
-        env_raw = process.graft_env(opts.env or {}, { "PSMODULEPATH" }),
-    }, opts))
+    return spawner.powershell(
+        vim.tbl_extend("keep", {
+            "-NoProfile",
+            "-Command",
+            PWSHOPT.progress_preference .. PWSHOPT.security_protocol .. command,
+            env_raw = process.graft_env(opts.env or {}, { "PSMODULEPATH" }),
+        }, opts) --[[@as JobSpawnOpts]]
+    )
 end
 
 return M
diff --git a/lua/mason-core/managers/std/init.lua b/lua/mason-core/managers/std/init.lua
index a0f9ecc9..ea55654a 100644
--- a/lua/mason-core/managers/std/init.lua
+++ b/lua/mason-core/managers/std/init.lua
@@ -17,16 +17,7 @@ end
 
 ---@async
 ---@param executable string
----@param opts {help_url:string|nil}
-function M.system_executable(executable, opts)
-    return function()
-        M.ensure_executable(executable, opts).with_receipt()
-    end
-end
-
----@async
----@param executable string
----@param opts {help_url:string|nil}
+---@param opts {help_url:string?}?
 function M.ensure_executable(executable, opts)
     local ctx = installer.context()
     opts = opts or {}
@@ -104,7 +95,7 @@ end
 
 ---@async
 ---@param file string
----@param opts {strip_components:integer}|nil
+---@param opts {strip_components:integer}?
 function M.untar(file, opts)
     opts = opts or {}
     local ctx = installer.context()
@@ -121,7 +112,7 @@ end
 
 ---@async
 ---@param file string
----@param opts {strip_components:integer}|nil
+---@param opts {strip_components: integer?}?
 function M.untarxz(file, opts)
     opts = opts or {}
     local ctx = installer.context()
@@ -163,8 +154,8 @@ function M.gunzip(file)
 end
 
 ---@async
----@param flags string: The chmod flag to apply.
----@param files string[]: A list of relative paths to apply the chmod on.
+---@param flags string The chmod flag to apply.
+---@param files string[] A list of relative paths to apply the chmod on.
 function M.chmod(flags, files)
     if platform.is_unix then
         local ctx = installer.context()
diff --git a/lua/mason-core/optional.lua b/lua/mason-core/optional.lua
index e2b2599f..65317b7f 100644
--- a/lua/mason-core/optional.lua
+++ b/lua/mason-core/optional.lua
@@ -72,7 +72,7 @@ function Optional:or_(supplier)
     end
 end
 
----@param exception any: (optional) The exception to throw if the result is a failure.
+---@param exception any? The exception to throw if the result is a failure.
 function Optional:or_else_throw(exception)
     if self:is_present() then
         return self._value
diff --git a/lua/mason-core/package/init.lua b/lua/mason-core/package/init.lua
index b7af8439..ee71655b 100644
--- a/lua/mason-core/package/init.lua
+++ b/lua/mason-core/package/init.lua
@@ -16,11 +16,11 @@ local version_checks = require "mason-core.package.version-check"
 ---@class Package : EventEmitter
 ---@field name string
 ---@field spec PackageSpec
----@field private handle InstallHandle: The currently associated handle.
+---@field private handle InstallHandle The currently associated handle.
 local Package = setmetatable({}, { __index = EventEmitter })
 
 ---@param package_identifier string
----@return string, string | nil
+---@return string, string?
 Package.Parse = function(package_identifier)
     local name, version = unpack(vim.split(package_identifier, "@"))
     return name, version
@@ -36,7 +36,7 @@ Package.Lang = setmetatable({}, {
     end,
 })
 
----@class PackageCategory
+---@enum PackageCategory
 Package.Cat = {
     Compiler = "Compiler",
     Runtime = "Runtime",
@@ -84,7 +84,7 @@ function Package:new_handle()
     return handle
 end
 
----@param opts { version: string|nil } | nil
+---@param opts { version: string? }?
 ---@return InstallHandle
 function Package:install(opts)
     opts = opts or {}
@@ -168,7 +168,7 @@ function Package:get_install_path()
     return path.package_prefix(self.name)
 end
 
----@return Optional: Optional<InstallReceipt>
+---@return Optional # Optional<InstallReceipt>
 function Package:get_receipt()
     local receipt_path = path.concat { self:get_install_path(), "mason-receipt.json" }
     if fs.sync.file_exists(receipt_path) then
diff --git a/lua/mason-core/path.lua b/lua/mason-core/path.lua
index 2060c186..5986c1d7 100644
--- a/lua/mason-core/path.lua
+++ b/lua/mason-core/path.lua
@@ -9,7 +9,7 @@ local sep = (function()
             return "\\"
         end
     else
-        return package.config:sub(1, 1)
+        return string.sub(package.config, 1, 1)
     end
 end)()
 
@@ -27,23 +27,23 @@ function M.is_subdirectory(root_path, path)
     return root_path == path or path:sub(1, #root_path + 1) == root_path .. sep
 end
 
----@param dir string|nil
+---@param dir string?
 function M.install_prefix(dir)
     local settings = require "mason.settings"
     return M.concat { settings.current.install_root_dir, dir }
 end
 
----@param executable string|nil
+---@param executable string?
 function M.bin_prefix(executable)
     return M.concat { M.install_prefix "bin", executable }
 end
 
----@param name string|nil
+---@param name string?
 function M.package_prefix(name)
     return M.concat { M.install_prefix "packages", name }
 end
 
----@param name string|nil
+---@param name string?
 function M.package_build_prefix(name)
     return M.concat { M.install_prefix ".packages", name }
 end
diff --git a/lua/mason-core/platform.lua b/lua/mason-core/platform.lua
index 8fc6ba38..15ebdd47 100644
--- a/lua/mason-core/platform.lua
+++ b/lua/mason-core/platform.lua
@@ -63,7 +63,7 @@ M.os_distribution = fun.lazy(function()
     local Result = require "mason-core.result"
 
     ---Parses the provided contents of an /etc/\*-release file and identifies the Linux distribution.
-    ---@param contents string: The contents of a /etc/\*-release file.
+    ---@param contents string The contents of a /etc/\*-release file.
     ---@return table<string, any>
     local function parse_linux_dist(contents)
         local lines = vim.split(contents, "\n")
diff --git a/lua/mason-core/process.lua b/lua/mason-core/process.lua
index 0c72aa2b..676adebe 100644
--- a/lua/mason-core/process.lua
+++ b/lua/mason-core/process.lua
@@ -34,15 +34,16 @@ end
 -- Also, there's no particular reason we need to refresh the environment (yet).
 local initial_environ = vim.fn.environ()
 
----@param new_paths string[]: A list of paths to prepend the existing PATH with.
+---@param new_paths string[] A list of paths to prepend the existing PATH with.
 function M.extend_path(new_paths)
     local new_path_str = table.concat(new_paths, platform.path_sep)
     return ("%s%s%s"):format(new_path_str, platform.path_sep, initial_environ.PATH or "")
 end
 
----Merges the provided env param with the user's full environent. Provided env has precedence.
+---Merges the provided env param with the user's full environment. Provided env has precedence.
 ---@param env table<string, string>
 ---@param excluded_var_names string[]|nil
+---@return string[]
 function M.graft_env(env, excluded_var_names)
     local excluded_var_names_set = excluded_var_names and _.set_of(excluded_var_names) or {}
     local merged_env = {}
@@ -84,18 +85,18 @@ local function sanitize_env_list(env_list)
     return sanitized_list
 end
 
----@alias JobSpawnCallback fun(success: boolean, exit_code: integer, signal: integer)
+---@alias JobSpawnCallback fun(success: boolean, exit_code: integer?, signal: integer?)
 
 ---@class JobSpawnOpts
----@field env string[]: List of "key=value" string.
+---@field env string[]? List of "key=value" string.
 ---@field args string[]
 ---@field cwd string
 ---@field stdio_sink StdioSink
 
----@param cmd string: The command/executable.
+---@param cmd string The command/executable.
 ---@param opts JobSpawnOpts
 ---@param callback JobSpawnCallback
----@return luv_handle,luv_pipe[],integer: Returns the job handle and the stdio array on success, otherwise returns nil.
+---@return luv_handle?,luv_pipe[]?,integer? # Returns the job handle and the stdio array on success, otherwise returns nil.
 function M.spawn(cmd, opts, callback)
     local stdin = uv.new_pipe(false)
     local stdout = uv.new_pipe(false)
@@ -155,7 +156,7 @@ function M.spawn(cmd, opts, callback)
             opts.stdio_sink.stderr(("Failed to spawn process cmd=%s err=%s\n"):format(cmd, pid_or_err))
         end
         callback(false)
-        return nil, nil
+        return nil, nil, nil
     end
 
     log.debug("Spawned with pid", pid_or_err)
diff --git a/lua/mason-core/receipt.lua b/lua/mason-core/receipt.lua
index 76cd7449..4d346ed8 100644
--- a/lua/mason-core/receipt.lua
+++ b/lua/mason-core/receipt.lua
@@ -115,9 +115,14 @@ function InstallReceiptBuilder:build()
     }
 end
 
+---@class InstallReceiptPackageSource
+---@field type string
+---@field package string
+
 ---@param type InstallReceiptSourceType
 local function package_source(type)
     ---@param pkg string
+    ---@return InstallReceiptPackageSource
     return function(pkg)
         return { type = type, package = pkg }
     end
@@ -156,7 +161,7 @@ function InstallReceiptBuilder.git_remote(remote_url)
     return { type = "git", remote = remote_url }
 end
 
----@class InstallReceipt
+---@class InstallReceipt<T> : { primary_source: T }
 ---@field public name string
 ---@field public schema_version InstallReceiptSchemaVersion
 ---@field public metrics {start_time:integer, completion_time:integer}
diff --git a/lua/mason-core/result.lua b/lua/mason-core/result.lua
index 0a615b8f..f2efd36a 100644
--- a/lua/mason-core/result.lua
+++ b/lua/mason-core/result.lua
@@ -40,7 +40,7 @@ function Result:get_or_else(value)
     end
 end
 
----@param exception any: (optional) The exception to throw if the result is a failure.
+---@param exception any? The exception to throw if the result is a failure.
 function Result:get_or_throw(exception)
     if self:is_success() then
         return self.value
diff --git a/lua/mason-core/spawn.lua b/lua/mason-core/spawn.lua
index 305bbc12..dfd63e83 100644
--- a/lua/mason-core/spawn.lua
+++ b/lua/mason-core/spawn.lua
@@ -41,13 +41,13 @@ local is_executable = _.memoize(function(cmd)
 end, _.identity)
 
 ---@class SpawnArgs
----@field with_paths string[]: (optional) Paths to add to the PATH environment variable.
----@field env table<string, string>: (optional) Example { SOME_ENV = "value", SOME_OTHER_ENV = "some_value" }
----@field env_raw string[]: (optional) Example: { "SOME_ENV=value", "SOME_OTHER_ENV=some_value" }
----@field stdio_sink StdioSink: (optional) If provided, will be used to write to stdout and stderr.
----@field cwd string: (optional)
----@field on_spawn (fun(handle: luv_handle, stdio: luv_pipe[])): (optional) Will be called when the process successfully spawns.
----@field check_executable boolean: (optional) Whether to check if the provided command is executable (defaults to true).
+---@field with_paths string[]? Paths to add to the PATH environment variable.
+---@field env table<string, string>? Example { SOME_ENV = "value", SOME_OTHER_ENV = "some_value" }
+---@field env_raw string[]? Example: { "SOME_ENV=value", "SOME_OTHER_ENV=some_value" }
+---@field stdio_sink StdioSink? If provided, will be used to write to stdout and stderr.
+---@field cwd string?
+---@field on_spawn (fun(handle: luv_handle, stdio: luv_pipe[], pid: integer))? Will be called when the process successfully spawns.
+---@field check_executable boolean? Whether to check if the provided command is executable (defaults to true).
 
 setmetatable(spawn, {
     ---@param normalized_cmd string
diff --git a/lua/mason-core/ui/display.lua b/lua/mason-core/ui/display.lua
index 795cac52..97fc36fc 100644
--- a/lua/mason-core/ui/display.lua
+++ b/lua/mason-core/ui/display.lua
@@ -48,8 +48,8 @@ end
 
 ---@param viewport_context ViewportContext
 ---@param node INode
----@param _render_context RenderContext|nil
----@param _output RenderOutput|nil
+---@param _render_context RenderContext?
+---@param _output RenderOutput?
 local function render_node(viewport_context, node, _render_context, _output)
     ---@class RenderContext
     ---@field viewport_context ViewportContext
@@ -77,7 +77,7 @@ local function render_node(viewport_context, node, _render_context, _output)
 
     ---@class RenderOutput
     ---@field lines string[]: The buffer lines.
-    ---@field virt_texts string[][]: List of (text, highlight) tuples.
+    ---@field virt_texts {line: integer, content: table}[]: List of tuples.
     ---@field highlights RenderHighlight[]
     ---@field keybinds RenderKeybind[]
     ---@field diagnostics RenderDiagnostic[]
@@ -168,7 +168,7 @@ M._render_node = render_node
 ---@alias WindowOpts {effects: table<string, fun()>, highlight_groups: table<string, table>, border: string|table}
 
 ---@param opts WindowOpenOpts
----@param sizes_only boolean: Whether to only return properties that control the window size.
+---@param sizes_only boolean Whether to only return properties that control the window size.
 local function create_popup_window_opts(opts, sizes_only)
     local win_height = vim.o.lines - vim.o.cmdheight - 2 -- Add margin for status and buffer line
     local win_width = vim.o.columns
@@ -191,7 +191,7 @@ local function create_popup_window_opts(opts, sizes_only)
     return popup_layout
 end
 
----@param name string: Human readable identifier.
+---@param name string Human readable identifier.
 ---@param filetype string
 function M.new_view_only_win(name, filetype)
     local namespace = vim.api.nvim_create_namespace(("installer_%s"):format(name))
@@ -402,7 +402,7 @@ function M.new_view_only_win(name, filetype)
             group = autoclose_augroup,
             buffer = bufnr,
             callback = function()
-                -- Schedule is done because otherwise the window wont actually close in some cases (for example if
+                -- Schedule is done because otherwise the window won't actually close in some cases (for example if
                 -- you're loading another buffer into it)
                 vim.schedule(function()
                     if vim.api.nvim_win_is_valid(win_id) then
diff --git a/lua/mason-core/ui/init.lua b/lua/mason-core/ui/init.lua
index eafbf6ed..62f2e6fc 100644
--- a/lua/mason-core/ui/init.lua
+++ b/lua/mason-core/ui/init.lua
@@ -61,7 +61,7 @@ function M.CascadingStyleNode(styles, children)
     return node
 end
 
----@param virt_text string[][]: List of (text, highlight) tuples.
+---@param virt_text string[][] List of (text, highlight) tuples.
 function M.VirtualTextNode(virt_text)
     ---@class VirtualTextNode
     local node = {
@@ -71,7 +71,7 @@ function M.VirtualTextNode(virt_text)
     return node
 end
 
----@param diagnostic {message: string, severity: integer, source: string|nil}
+---@param diagnostic {message: string, severity: integer, source: string?}
 function M.DiagnosticsNode(diagnostic)
     ---@class DiagnosticsNode
     local node = {
@@ -95,10 +95,10 @@ function M.When(condition, node, default_val)
     return default_val or M.Node {}
 end
 
----@param key string: The keymap to register to. Example: "<CR>".
----@param effect string: The effect to call when keymap is triggered by the user.
----@param payload any: The payload to pass to the effect handler when triggered.
----@param is_global boolean|nil: Whether to register the keybind to apply on all lines in the buffer.
+---@param key string The keymap to register to. Example: "<CR>".
+---@param effect string The effect to call when keymap is triggered by the user.
+---@param payload any The payload to pass to the effect handler when triggered.
+---@param is_global boolean? Whether to register the keybind to apply on all lines in the buffer.
 function M.Keybind(key, effect, payload, is_global)
     ---@class KeybindHandlerNode
     local node = {
@@ -115,7 +115,7 @@ function M.EmptyLine()
     return M.Text { "" }
 end
 
----@param rows string[][][]: A list of rows to include in the table. Each row consists of an array of (text, highlight) tuples (aka spans).
+---@param rows string[][][] A list of rows to include in the table. Each row consists of an array of (text, highlight) tuples (aka spans).
 function M.Table(rows)
     local col_maxwidth = {}
     for i = 1, #rows do
diff --git a/lua/mason-registry/init.lua b/lua/mason-registry/init.lua
index 20b8a311..af85db70 100644
--- a/lua/mason-registry/init.lua
+++ b/lua/mason-registry/init.lua
@@ -15,7 +15,7 @@ EventEmitter.init(M)
 local scan_install_root
 
 do
-    ---@type table<string, true>
+    ---@type table<string, true>?
     local cached_dirs
 
     local get_directories = _.compose(
@@ -35,7 +35,6 @@ do
             return cached_dirs
         end
         log.trace "Scanning installation root dir"
-        ---@type string[]
         local ok, entries = pcall(fs.sync.readdir, path.package_prefix())
         if not ok then
             log.debug("Failed to scan installation root dir", entries)
diff --git a/lua/mason/api/command.lua b/lua/mason/api/command.lua
index 5ffd56be..c02b18c0 100644
--- a/lua/mason/api/command.lua
+++ b/lua/mason/api/command.lua
@@ -160,6 +160,7 @@ vim.api.nvim_create_user_command("MasonLog", MasonLog, {
     desc = "Opens the mason.nvim log.",
 })
 
+-- selene: allow(global_usage)
 _G.mason_completion = {
     available_package_completion = function()
         local registry = require "mason-registry"
diff --git a/lua/mason/health/init.lua b/lua/mason/health/init.lua
index 39ceac81..e19e5c8d 100644
--- a/lua/mason/health/init.lua
+++ b/lua/mason/health/init.lua
@@ -15,9 +15,9 @@ local M = {}
 
 ---@class HealthCheck
 ---@field public result HealthCheckResult
----@field public version string|nil
----@field public relaxed boolean|nil
----@field public reason string|nil
+---@field public version string?
+---@field public relaxed boolean?
+---@field public reason string?
 ---@field public name string
 local HealthCheck = {}
 HealthCheck.__index = HealthCheck
@@ -58,7 +58,7 @@ end
 
 ---@param callback fun(result: HealthCheck)
 local function mk_healthcheck(callback)
-    ---@param opts {cmd:string, args:string[], name: string, use_stderr:boolean}
+    ---@param opts {cmd:string, args:string[], name: string, use_stderr: boolean?, version_check: fun(version: string): string?, relaxed: boolean?}
     return function(opts)
         local parse_version =
             _.compose(_.head, _.split "\n", _.if_else(_.always(opts.use_stderr), _.prop "stderr", _.prop "stdout"))
diff --git a/lua/mason/init.lua b/lua/mason/init.lua
index 27e8f2d6..eb64d136 100644
--- a/lua/mason/init.lua
+++ b/lua/mason/init.lua
@@ -4,7 +4,7 @@ local platform = require "mason-core.platform"
 
 local M = {}
 
----@param config MasonSettings | nil
+---@param config MasonSettings?
 function M.setup(config)
     if config then
         settings.set(config)
diff --git a/lua/mason/ui/components/json-schema.lua b/lua/mason/ui/components/json-schema.lua
index d7e3a170..17745ccd 100644
--- a/lua/mason/ui/components/json-schema.lua
+++ b/lua/mason/ui/components/json-schema.lua
@@ -40,10 +40,10 @@ end
 ---@param schema_id string
 ---@param state UiPackageState
 ---@param schema table
----@param key string|nil
----@param level number|nil
----@param key_width number|nil: The width the key should occupate in the UI to produce an even column.
----@param compound_key string|nil
+---@param key string?
+---@param level number?
+---@param key_width number? The width the key should occupate in the UI to produce an even column.
+---@param compound_key string?
 local function JsonSchema(pkg, schema_id, state, schema, key, level, key_width, compound_key)
     level = level or 0
     compound_key = ("%s%s"):format(compound_key or "", key or "")
@@ -112,7 +112,7 @@ local function JsonSchema(pkg, schema_id, state, schema, key, level, key_width,
         -- Leaf node (aka any type that isn't an object)
         local type = resolve_type(schema)
         local heading
-        local label = (key_prefix .. key .. (" "):rep(key_width)):sub(1, key_width + 5) -- + 5 to account for key_prefix plus some extra whitespace
+        local label = (key_prefix .. key .. (" "):rep(key_width or 0)):sub(1, key_width + 5) -- + 5 to account for key_prefix plus some extra whitespace
         if schema.default ~= nil then
             heading = Ui.HlTextNode {
                 {
diff --git a/lua/mason/ui/components/main/package_list.lua b/lua/mason/ui/components/main/package_list.lua
index 766a956e..3a99558f 100644
--- a/lua/mason/ui/components/main/package_list.lua
+++ b/lua/mason/ui/components/main/package_list.lua
@@ -33,7 +33,7 @@ local function PackageListContainer(props)
     }
 end
 
----@param executables table<string, string> | nil
+---@param executables table<string, string>?
 local function ExecutablesTable(executables)
     if not executables or _.size(executables) == 0 then
         return Ui.Node {}
@@ -80,10 +80,12 @@ local function ExpandedPackageInfo(state, pkg, is_installed)
                     #pkg.spec.categories > 0 and p.Bold(table.concat(pkg.spec.categories, ", ")) or p.muted "-",
                 },
             }),
-            ExecutablesTable(is_installed and pkg_state.linked_executables or pkg.spec.executables)
+            Ui.When(is_installed, function()
+                return ExecutablesTable(pkg_state.linked_executables)
+            end)
         )),
         -- ExecutablesTable(is_installed and pkg_state.linked_executables or package.spec.executables),
-        Ui.When(pkg_state.lsp_settings_schema, function()
+        Ui.When(pkg_state.lsp_settings_schema ~= nil, function()
             local has_expanded = pkg_state.expanded_json_schemas["lsp"]
             return Ui.Node {
                 Ui.EmptyLine(),
@@ -115,7 +117,7 @@ end
 
 ---@param state InstallerUiState
 ---@param pkg Package
----@param opts { keybinds: KeybindHandlerNode[], icon: string[], is_installed: boolean, sticky: StickyCursorNode | nil }
+---@param opts { keybinds: KeybindHandlerNode[], icon: string[], is_installed: boolean, sticky: StickyCursorNode? }
 local function PackageComponent(state, pkg, opts)
     local pkg_state = state.packages.states[pkg.name]
     local is_expanded = state.packages.expanded == pkg.name
@@ -128,7 +130,7 @@ local function PackageComponent(state, pkg, opts)
             return Ui.VirtualTextNode { p.Comment " checking for new version…" }
         end),
         Ui.Keybind(settings.current.ui.keymaps.check_package_version, "CHECK_NEW_PACKAGE_VERSION", pkg),
-        Ui.When(pkg_state.new_version, function()
+        Ui.When(pkg_state.new_version ~= nil, function()
             return Ui.DiagnosticsNode {
                 message = ("new version available: %s %s -> %s"):format(
                     pkg_state.new_version.name,
diff --git a/lua/mason/ui/instance.lua b/lua/mason/ui/instance.lua
index 6ac14d30..3f927475 100644
--- a/lua/mason/ui/instance.lua
+++ b/lua/mason/ui/instance.lua
@@ -44,13 +44,13 @@ end
 ---@field is_checking_new_version boolean
 ---@field is_checking_version boolean
 ---@field is_terminated boolean
----@field latest_spawn string|nil
----@field linked_executables table<string, string> | nil
----@field lsp_settings_schema table|nil
----@field new_version NewPackageVersion|nil
+---@field latest_spawn string?
+---@field linked_executables table<string, string>?
+---@field lsp_settings_schema table?
+---@field new_version NewPackageVersion?
 ---@field short_tailed_output string[]
 ---@field tailed_output string[]
----@field version string|nil
+---@field version string?
 
 ---@class InstallerUiState
 local INITIAL_STATE = {
@@ -138,7 +138,7 @@ local mutate_state, get_state = window.state(INITIAL_STATE)
 
 ---@param pkg Package
 ---@param group string
----@param tail boolean|nil: Whether to insert at the end.
+---@param tail boolean? Whether to insert at the end.
 local function mutate_package_grouping(pkg, group, tail)
     mutate_state(function(state)
         remove(state.packages.installing, pkg)