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

15 files changed, 117 insertions, 108 deletions

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()