1 files changed, 50 insertions, 40 deletions
diff --git a/runtime/lua/vim/loader.lua b/runtime/lua/vim/loader.lua
index ee01111337..d3d8948654 100644
--- a/runtime/lua/vim/loader.lua
+++ b/runtime/lua/vim/loader.lua
@@ -1,24 +1,46 @@
+local fs = vim.fs -- "vim.fs" is a dependency, so must be loaded early.
 local uv = vim.uv
-local uri_encode = vim.uri_encode
+local uri_encode = vim.uri_encode --- @type function
 
 --- @type (fun(modename: string): fun()|string)[]
 local loaders = package.loaders
 
 local M = {}
 
----@alias CacheHash {mtime: {nsec: integer, sec: integer}, size: integer, type?: uv.aliases.fs_stat_types}
+---@alias CacheHash {mtime: {nsec: integer, sec: integer}, size: integer, type?: string}
 ---@alias CacheEntry {hash:CacheHash, chunk:string}
 
----@class ModuleFindOpts
----@field all? boolean Search for all matches (defaults to `false`)
----@field rtp? boolean Search for modname in the runtime path (defaults to `true`)
----@field patterns? string[] Patterns to use (defaults to `{"/init.lua", ".lua"}`)
----@field paths? string[] Extra paths to search for modname
-
----@class ModuleInfo
----@field modpath string Path of the module
----@field modname string Name of the module
----@field stat? uv.uv_fs_t File stat of the module path
+--- @class vim.loader.find.Opts
+--- @inlinedoc
+---
+--- Search for modname in the runtime path.
+--- (default: `true`)
+--- @field rtp? boolean
+---
+--- Extra paths to search for modname
+--- (default: `{}`)
+--- @field paths? string[]
+---
+--- List of patterns to use when searching for modules.
+--- A pattern is a string added to the basename of the Lua module being searched.
+--- (default: `{"/init.lua", ".lua"}`)
+--- @field patterns? string[]
+---
+--- Search for all matches.
+--- (default: `false`)
+--- @field all? boolean
+
+--- @class vim.loader.ModuleInfo
+--- @inlinedoc
+---
+--- Path of the module
+--- @field modpath string
+---
+--- Name of the module
+--- @field modname string
+---
+--- The fs_stat of the module path. Won't be returned for `modname="*"`
+--- @field stat? uv.uv_fs_t
 
 ---@alias LoaderStats table<string, {total:number, time:number, [string]:number?}?>
 
@@ -28,14 +50,14 @@ M.path = vim.fn.stdpath('cache') .. '/luac'
 ---@nodoc
 M.enabled = false
 
----@class Loader
----@field _rtp string[]
----@field _rtp_pure string[]
----@field _rtp_key string
----@field _hashes? table<string, CacheHash>
+---@class (private) Loader
+---@field private _rtp string[]
+---@field private _rtp_pure string[]
+---@field private _rtp_key string
+---@field private _hashes? table<string, CacheHash>
 local Loader = {
   VERSION = 4,
-  ---@type table<string, table<string,ModuleInfo>>
+  ---@type table<string, table<string,vim.loader.ModuleInfo>>
   _indexed = {},
   ---@type table<string, string[]>
   _topmods = {},
@@ -63,7 +85,7 @@ function Loader.get_hash(path)
 end
 
 local function normalize(path)
-  return vim.fs.normalize(path, { expand_env = false })
+  return fs.normalize(path, { expand_env = false })
 end
 
 --- Gets the rtp excluding after directories.
@@ -189,7 +211,6 @@ function Loader.loader_lib(modname)
   local sysname = uv.os_uname().sysname:lower() or ''
   local is_win = sysname:find('win', 1, true) and not sysname:find('darwin', 1, true)
   local ret = M.find(modname, { patterns = is_win and { '.dll' } or { '.so' } })[1]
-  ---@type function?, string?
   if ret then
     -- Making function name in Lua 5.1 (see src/loadlib.c:mkfuncname) is
     -- a) strip prefix up to and including the first dash, if any
@@ -207,15 +228,13 @@ end
 --- `loadfile` using the cache
 --- Note this has the mode and env arguments which is supported by LuaJIT and is 5.1 compatible.
 ---@param filename? string
----@param mode? "b"|"t"|"bt"
+---@param _mode? "b"|"t"|"bt"
 ---@param env? table
 ---@return function?, string?  error_message
 ---@private
--- luacheck: ignore 312
-function Loader.loadfile(filename, mode, env)
+function Loader.loadfile(filename, _mode, env)
   -- ignore mode, since we byte-compile the Lua source files
-  mode = nil
-  return Loader.load(normalize(filename), { mode = mode, env = env })
+  return Loader.load(normalize(filename), { env = env })
 end
 
 --- Checks whether two cache hashes are the same based on:
@@ -272,17 +291,8 @@ end
 
 --- Finds Lua modules for the given module name.
 ---@param modname string Module name, or `"*"` to find the top-level modules instead
----@param opts? ModuleFindOpts (table|nil) Options for finding a module:
----    - rtp: (boolean) Search for modname in the runtime path (defaults to `true`)
----    - paths: (string[]) Extra paths to search for modname (defaults to `{}`)
----    - patterns: (string[]) List of patterns to use when searching for modules.
----                A pattern is a string added to the basename of the Lua module being searched.
----                (defaults to `{"/init.lua", ".lua"}`)
----    - all: (boolean) Return all matches instead of just the first one (defaults to `false`)
----@return ModuleInfo[] (list) A list of results with the following properties:
----    - modpath: (string) the path to the module
----    - modname: (string) the name of the module
----    - stat: (table|nil) the fs_stat of the module path. Won't be returned for `modname="*"`
+---@param opts? vim.loader.find.Opts Options for finding a module:
+---@return vim.loader.ModuleInfo[]
 function M.find(modname, opts)
   opts = opts or {}
 
@@ -308,7 +318,7 @@ function M.find(modname, opts)
     patterns[p] = '/lua/' .. basename .. pattern
   end
 
-  ---@type ModuleInfo[]
+  ---@type vim.loader.ModuleInfo[]
   local results = {}
 
   -- Only continue if we haven't found anything yet or we want to find all
@@ -432,7 +442,7 @@ end
 function Loader.lsmod(path)
   if not Loader._indexed[path] then
     Loader._indexed[path] = {}
-    for name, t in vim.fs.dir(path .. '/lua') do
+    for name, t in fs.dir(path .. '/lua') do
       local modpath = path .. '/lua/' .. name
       -- HACK: type is not always returned due to a bug in luv
       t = t or Loader.get_hash(modpath).type
@@ -474,12 +484,12 @@ function Loader.track(stat, f)
   end
 end
 
----@class ProfileOpts
+---@class (private) vim.loader._profile.Opts
 ---@field loaders? boolean Add profiling to the loaders
 
 --- Debug function that wraps all loaders and tracks stats
 ---@private
----@param opts ProfileOpts?
+---@param opts vim.loader._profile.Opts?
 function M._profile(opts)
   Loader.get_rtp = Loader.track('get_rtp', Loader.get_rtp)
   Loader.read = Loader.track('read', Loader.read)