diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index aa9fb67ad6..130031ff4c 100644 --- a/runtime/doc/lua.txt +++ b/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 diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 09580a6644..6c1b58737a 100644 --- a/runtime/doc/news.txt +++ b/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 diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 7e85e80056..4a524aa467 100644 --- a/runtime/lua/vim/fs.lua +++ b/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 diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua index 8434a36373..302d1445ac 100644 --- a/test/functional/lua/fs_spec.lua +++ b/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 + 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 + 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()