feat(vim.fs): dir(), find() error-reporting

Problem:
vim.fs.dir() and vim.fs.find() drop errors returned by uv.fs_scandir().

Solution:
- vim.fs.dir():
  - Return root scan failures as a secondary return value.
  - Propagate recursive scan failures through the iterator. This allows
    callers to distinguish unreadable directories from empty ones.

- vim.fs.find(): Collect errors during search, and return the list as
  a second retval.

runtime/doc/lua.txt

@@ -2596,6 +2596,20 @@ vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
     Gets an iterator over items found in `path` (normalized via
     |vim.fs.normalize()|).
 
+    Example: >lua
+        local it, err = vim.fs.dir(path)
+
+        if err then
+          -- Failed to scan the root directory
+        end
+
+        for name, type, err in it do
+          if err then
+            -- Failed to scan a child directory
+          end
+        end
+<
+
     Attributes: ~
         Since: 0.8.0
 
@@ -2611,11 +2625,14 @@ vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
                   current directory. Only useful when depth > 1 Return an
                   iterator over the items located in {path}
 
-    Return: ~
+    Return (multiple): ~
         (`Iterator`) over items in {path}. Each iteration yields two values:
-        "name" and "type". "name" is the basename of the item relative to
-        {path}. "type" is one of the following: "file", "directory", "link",
-        "fifo", "socket", "char", "block", "unknown".
+        "name" and "type", along with an optional value "err" "name" is the
+        basename of the item relative to {path}. "type" is one of the
+        following: "file", "directory", "link", "fifo", "socket", "char",
+        "block", "unknown". "err" is a string with the format {errname}:
+        {message}
+        (`string?`) err Error encountered while scanning the base directory
 
 vim.fs.dirname({file})                                      *vim.fs.dirname()*
     Gets the parent directory of the given path (not expanded/resolved, the
@@ -2708,9 +2725,12 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
                    through parent directories. Otherwise, search child
                    directories (recursively).
 
-    Return: ~
-        (`string[]`) Normalized paths |vim.fs.normalize()| of all matching
-        items
+    Return (multiple): ~
+        (`string[]`) matches Normalized paths |vim.fs.normalize()| of all
+        matching items
+        (`table[]`) errors list of errors encountered during the search
+        • {err} (`string`) Error message
+        • {path} (`string`) Path at which error was encountered
 
 vim.fs.joinpath({...})                                     *vim.fs.joinpath()*
     Concatenates partial paths (one absolute or relative path followed by zero

runtime/doc/news.txt

@@ -253,6 +253,9 @@ LUA
 • |vim.net.request()| can now accept  `method` param overload for multiple HTTP methods.
 • |writefile()| treats Lua strings as "blob", so it can be used to write
   binary data.
+• |vim.fs.dir()| and |vim.fs.find()| report errors encountered while
+  scanning directories that cannot be read (e.g. due to permissions),
+  instead of treating them as empty.
 • |vim.filetype.inspect()| returns a copy of the internal tables used for
   filetype detection.
 • Added `__eq` metamethod to |vim.VersionRange|. 2 distinct but representing

runtime/lua/vim/fs.lua

@@ -187,17 +187,36 @@ end
 --- (default: `false`)
 --- @field follow? boolean
 
----@alias Iterator fun(): string?, string?
+---@alias Iterator fun(): string?, string?, string?
 
 --- Gets an iterator over items found in `path` (normalized via |vim.fs.normalize()|).
 ---
+--- Example:
+---
+--- ```lua
+--- local it, err = vim.fs.dir(path)
+---
+--- if err then
+---   -- Failed to scan the root directory
+--- end
+---
+--- for name, type, err in it do
+---   if err then
+---     -- Failed to scan a child directory
+---   end
+--- end
+--- ```
+---
 ---@since 10
 ---@param path (string) Directory to iterate over, normalized via |vim.fs.normalize()|.
 ---@param opts? vim.fs.dir.Opts Optional keyword arguments:
----@return Iterator over items in {path}. Each iteration yields two values: "name" and "type".
+---@return Iterator over items in {path}. Each iteration yields two values: "name" and "type", along
+---        with an optional value "err"
 ---        "name" is the basename of the item relative to {path}.
 ---        "type" is one of the following:
 ---        "file", "directory", "link", "fifo", "socket", "char", "block", "unknown".
+---        "err" is a string with the format {errname}: {message}
+---@return string? err Error encountered while scanning the base directory
 function M.dir(path, opts)
   opts = opts or {}
 
@@ -207,31 +226,37 @@ function M.dir(path, opts)
   vim.validate('follow', opts.follow, 'boolean', true)
 
   path = M.normalize(path)
+
+  local rootfs, rooterr = uv.fs_scandir(path)
+
+  if not rootfs then
+    local empty = function()
+      return nil
+    end
+
+    return empty, rooterr
+  end
+
   if not opts.depth or opts.depth == 1 then
-    local fs = uv.fs_scandir(path)
     return function()
-      if not fs then
-        return
-      end
-      return fs_scandir_next(fs, path)
+      return fs_scandir_next(rootfs, path)
     end
   end
 
   --- @async
-  return coroutine.wrap(function()
-    local dirs = { { path, 1 } }
+  local it = coroutine.wrap(function()
+    local dirs = { { path, 1, rootfs } }
     while #dirs > 0 do
-      --- @type string, integer
-      local dir0, level = unpack(table.remove(dirs, 1))
+      --- @type string, integer, any
+      local dir0, level, fs = unpack(table.remove(dirs, 1))
       local dir = level == 1 and dir0 or M.joinpath(path, dir0)
-      local fs = uv.fs_scandir(dir)
       while fs do
         local name, t = fs_scandir_next(fs, dir)
         if not name then
           break
         end
         local f = level == 1 and name or M.joinpath(dir0, name)
-        coroutine.yield(f, t)
+        local err_scan = nil
         if
           opts.depth
           and level < opts.depth
@@ -240,11 +265,19 @@ function M.dir(path, opts)
           ).type == 'directory'))
           and (not opts.skip or opts.skip(f) ~= false)
         then
-          dirs[#dirs + 1] = { f, level + 1 }
+          local fs_next, err = uv.fs_scandir(M.joinpath(path, f))
+          if not fs_next then
+            err_scan = err
+          else
+            dirs[#dirs + 1] = { f, level + 1, fs_next }
+          end
         end
+        coroutine.yield(f, t, err_scan)
       end
     end
   end)
+
+  return it, nil
 end
 
 --- @class vim.fs.find.Opts
@@ -271,6 +304,15 @@ end
 --- (default: `false`)
 --- @field follow? boolean
 
+--- @class vim.fs.find.Error
+--- @inlinedoc
+---
+--- Path at which error was encountered
+--- @field path string
+---
+--- Error message
+--- @field err string
+
 --- Find files or directories (or other items as specified by `opts.type`) in the given path.
 ---
 --- Finds items given in {names} starting from {path}. If {upward} is "true"
@@ -308,7 +350,8 @@ end
 ---             The function should return `true` if the given item is considered a match.
 ---
 ---@param opts? vim.fs.find.Opts Optional keyword arguments:
----@return (string[]) # Normalized paths |vim.fs.normalize()| of all matching items
+---@return string[] matches # Normalized paths |vim.fs.normalize()| of all matching items
+---@return vim.fs.find.Error[] errors # list of errors encountered during the search
 function M.find(names, opts)
   opts = opts or {}
   vim.validate('names', names, { 'string', 'table', 'function' })
@@ -328,6 +371,7 @@ function M.find(names, opts)
   local limit = opts.limit or 1
 
   local matches = {} --- @type string[]
+  local errors = {} --- @type vim.fs.find.Error[]
 
   local function add(match)
     matches[#matches + 1] = M.normalize(match)
@@ -342,9 +386,17 @@ function M.find(names, opts)
     if type(names) == 'function' then
       test = function(p)
         local t = {}
-        for name, type in M.dir(p) do
+        local it, base_err = M.dir(p)
+        if base_err ~= nil then
+          table.insert(errors, { path = p, err = base_err })
+        end
+        for name, type, err in it do
+          local f = M.joinpath(p, name)
+          if err ~= nil then
+            table.insert(errors, { path = f, err = err })
+          end
           if (not opts.type or opts.type == type) and names(name, p) then
-            table.insert(t, M.joinpath(p, name))
+            table.insert(t, f)
           end
         end
         return t
@@ -352,6 +404,11 @@ function M.find(names, opts)
     else
       test = function(p)
         local t = {} --- @type string[]
+        local _, base_err = M.dir(p)
+        if base_err ~= nil then -- Check if the directory itself is readable
+          table.insert(errors, { path = p, err = base_err })
+          return t
+        end
         for _, name in ipairs(names) do
           local f = M.joinpath(p, name)
           local stat = uv.fs_stat(f)
@@ -366,7 +423,7 @@ function M.find(names, opts)
 
     for _, match in ipairs(test(path)) do
       if add(match) then
-        return matches
+        return matches, errors
       end
     end
 
@@ -377,7 +434,7 @@ function M.find(names, opts)
 
       for _, match in ipairs(test(parent)) do
         if add(match) then
-          return matches
+          return matches, errors
         end
       end
     end
@@ -389,19 +446,26 @@ function M.find(names, opts)
         break
       end
 
-      for other, type_ in M.dir(dir) do
+      local it, base_err = M.dir(dir)
+      if base_err ~= nil then
+        table.insert(errors, { path = dir, err = base_err })
+      end
+      for other, type_, err in it do
         local f = M.joinpath(dir, other)
+        if err ~= nil then
+          table.insert(errors, { path = f, err = err })
+        end
         if type(names) == 'function' then
           if (not opts.type or opts.type == type_) and names(other, dir) then
             if add(f) then
-              return matches
+              return matches, errors
             end
           end
         else
           for _, name in ipairs(names) do
             if name == other and (not opts.type or opts.type == type_) then
               if add(f) then
-                return matches
+                return matches, errors
               end
             end
           end
@@ -417,7 +481,7 @@ function M.find(names, opts)
     end
   end
 
-  return matches
+  return matches, errors
 end
 
 --- Find the first parent directory containing a specific "marker", relative to a file path or

test/functional/lua/fs_spec.lua

@@ -287,6 +287,58 @@ describe('vim.fs', function()
         eq('file', result['test.txt'])
       end)
     end)
+
+    describe('error handling', function()
+      before_each(function()
+        mkdir('testdir')
+        mkdir('testdir/noaccess')
+        mkdir('testdir/a')
+        mkdir('testdir/a/noaccess')
+      end)
+      after_each(function()
+        rmdir('testdir')
+      end)
+
+      it('returns error for unreadable root directory', function()
+        local result = exec_lua(function()
+          local _, err = vim.fs.dir('does-not-exist')
+          return err
+        end)
+        eq('ENOENT: no such file or directory: does-not-exist', result)
+      end)
+
+      it('returns iterator errors for unreadable child directories', function()
+        local result = exec_lua(function()
+          -- Stub fs_scandir since chmod doesn't work reliably on Windows.
+          local orig_scandir = vim.uv.fs_scandir
+          vim.uv.fs_scandir = function(path, ...)
+            if path == 'testdir/noaccess' then
+              return nil, 'EACCES: permission denied: testdir/noaccess'
+            end
+            return orig_scandir(path, ...)
+          end
+
+          local ok, errors_or_err = pcall(function()
+            local errors = {} ---@type table<string, string>
+            local it = vim.fs.dir('testdir', { depth = 2 })
+            for f, _, err in it do
+              errors[f] = err
+            end
+            return errors
+          end)
+
+          vim.uv.fs_scandir = orig_scandir
+
+          if not ok then
+            error(errors_or_err)
+          end
+          return errors_or_err
+        end)
+        eq('EACCES: permission denied: testdir/noaccess', result['noaccess'])
+        -- This should be nil because with a depth of 2 we shouldn't be scanning it
+        eq(nil, result['a/noaccess'])
+      end)
+    end)
   end)
 
   describe('find()', function()
@@ -394,6 +446,113 @@ describe('vim.fs', function()
         )
       )
     end)
+
+    describe('error handling', function()
+      before_each(function()
+        mkdir('testdir')
+        mkdir('testdir/noaccess')
+        mkdir('testdir/a')
+        mkdir('testdir/a/noaccess')
+        t.write_file('testdir/a/match.lua', '')
+
+        exec_lua(function()
+          -- Stub fs_scandir since chmod doesn't work reliably on Windows.
+          local blocked_prefixes = { 'testdir/noaccess', 'testdir/a/noaccess' }
+          local function is_blocked(path)
+            for _, prefix in ipairs(blocked_prefixes) do
+              if path == prefix or vim.startswith(path, prefix .. '/') then
+                return true
+              end
+            end
+            return false
+          end
+          _G.__orig_fs_scandir = vim.uv.fs_scandir
+          vim.uv.fs_scandir = function(path, ...)
+            if is_blocked(path) then
+              return nil, 'EACCES: permission denied: ' .. path
+            end
+            return _G.__orig_fs_scandir(path, ...)
+          end
+        end)
+      end)
+
+      after_each(function()
+        exec_lua(function()
+          vim.uv.fs_scandir = _G.__orig_fs_scandir
+          _G.__orig_fs_scandir = nil
+        end)
+        rmdir('testdir')
+      end)
+
+      it('returns an error for a nonexistent root path', function()
+        local result = exec_lua(function()
+          local matches, errors = vim.fs.find('foo', { path = 'does-not-exist' })
+          return { matches = matches, errors = errors }
+        end)
+        eq({}, result.matches)
+        eq(1, #result.errors)
+        eq('does-not-exist', result.errors[1].path)
+        eq('ENOENT: no such file or directory: does-not-exist', result.errors[1].err)
+      end)
+
+      it('returns an error for an unreadable root path', function()
+        local result = exec_lua(function()
+          local matches, errors = vim.fs.find('foo', { path = 'testdir/noaccess' })
+          return { matches = matches, errors = errors }
+        end)
+        eq({}, result.matches)
+        eq(1, #result.errors)
+        eq('testdir/noaccess', result.errors[1].path)
+        eq('EACCES: permission denied: testdir/noaccess', result.errors[1].err)
+      end)
+
+      it('collects errors for unreadable child directories during downward search', function()
+        local result = exec_lua(function()
+          local matches, errors = vim.fs.find('match.lua', {
+            path = 'testdir',
+            limit = math.huge,
+            type = 'file',
+          })
+          --- @type table<string, string>
+          local err_by_path = {}
+          for _, e in ipairs(errors) do
+            err_by_path[e.path] = e.err
+          end
+          return { matches = matches, errors = err_by_path }
+        end)
+        eq(1, #result.matches)
+        eq('EACCES: permission denied: testdir/noaccess', result.errors['testdir/noaccess'])
+        eq('EACCES: permission denied: testdir/a/noaccess', result.errors['testdir/a/noaccess'])
+      end)
+
+      it('still returns matches found despite errors elsewhere in the tree', function()
+        local result = exec_lua(function()
+          local matches, errors = vim.fs.find('match.lua', {
+            path = 'testdir',
+            limit = math.huge,
+            type = 'file',
+          })
+          return { matches = matches, has_errors = #errors > 0 }
+        end)
+        eq(1, #result.matches)
+        eq(true, result.has_errors)
+      end)
+
+      it('reports errors for unreadable directories during upward search', function()
+        local result = exec_lua(function()
+          local matches, errors = vim.fs.find('match.lua', {
+            path = 'testdir/noaccess/x',
+            upward = true,
+            stop = 'testdir',
+          })
+          return { matches = matches, errors = errors }
+        end)
+        eq('EACCES: permission denied: testdir/noaccess/x', result.errors[1].err)
+        eq('EACCES: permission denied: testdir/noaccess', result.errors[2].err)
+        eq('testdir/noaccess/x', result.errors[1].path)
+        eq('testdir/noaccess', result.errors[2].path)
+      end)
+    end)
   end)
 
   describe('root()', function()