feat(fs): add vim.fs.root (#28477)

vim.fs.root() is a function for finding a project root relative to a
buffer using one or more "root markers". This is useful for LSP and
could be useful for other "projects" designs, as well as for any plugins
which work with a "projects" concept.

1 files changed, 29 insertions, 7 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index eaf61ff3fe..92c49bca40 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2891,13 +2891,6 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
     narrow the search to find only that type.
 
     Examples: >lua
-        -- location of Cargo.toml from the current buffer's path
-        local cargo = vim.fs.find('Cargo.toml', {
-          upward = true,
-          stop = vim.uv.os_homedir(),
-          path = vim.fs.dirname(vim.api.nvim_buf_get_name(0)),
-        })
-
         -- list all test directories under the runtime directory
         local test_dirs = vim.fs.find(
           {'test', 'tst', 'testdir'},
@@ -3013,6 +3006,35 @@ vim.fs.parents({start})                                     *vim.fs.parents()*
         (`nil`)
         (`string?`)
 
+vim.fs.root({source}, {marker})                                *vim.fs.root()*
+    Find the first parent directory containing a specific "marker", relative
+    to a buffer's directory.
+
+    Example: >lua
+        -- Find the root of a Python project, starting from file 'main.py'
+        vim.fs.root(vim.fs.joinpath(vim.env.PWD, 'main.py'), {'pyproject.toml', 'setup.py' })
+
+        -- Find the root of a git repository
+        vim.fs.root(0, '.git')
+
+        -- Find the parent directory containing any file with a .csproj extension
+        vim.fs.root(0, function(name, path)
+          return name:match('%.csproj$') ~= nil
+        end)
+<
+
+    Parameters: ~
+      • {source}  (`integer|string`) Buffer number (0 for current buffer) or
+                  file path to begin the search from.
+      • {marker}  (`string|string[]|fun(name: string, path: string): boolean`)
+                  A marker, or list of markers, to search for. If a function,
+                  the function is called for each evaluated item and should
+                  return true if {name} and {path} are a match.
+
+    Return: ~
+        (`string?`) Directory path containing one of the given markers, or nil
+        if no directory was found.
+
 
 ==============================================================================
 Lua module: vim.glob                                                *vim.glob*