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.

test/functional/lua/fs_spec.lua

@@ -7,6 +7,8 @@ local eq = t.eq
 local mkdir_p = n.mkdir_p
 local rmdir = n.rmdir
 local nvim_dir = n.nvim_dir
+local command = n.command
+local api = n.api
 local test_build_dir = t.paths.test_build_dir
 local test_source_path = t.paths.test_source_path
 local nvim_prog = n.nvim_prog
@@ -278,6 +280,38 @@ describe('vim.fs', function()
     end)
   end)
 
+  describe('root()', function()
+    before_each(function()
+      command('edit test/functional/fixtures/tty-test.c')
+    end)
+
+    it('works with a single marker', function()
+      eq(test_source_path, exec_lua([[return vim.fs.root(0, '.git')]]))
+    end)
+
+    it('works with multiple markers', function()
+      local bufnr = api.nvim_get_current_buf()
+      eq(
+        vim.fs.joinpath(test_source_path, 'test/functional/fixtures'),
+        exec_lua([[return vim.fs.root(..., {'CMakeLists.txt', '.git'})]], bufnr)
+      )
+    end)
+
+    it('works with a function', function()
+      ---@type string
+      local result = exec_lua([[
+        return vim.fs.root(0, function(name, path)
+          return name:match('%.txt$')
+        end)
+      ]])
+      eq(vim.fs.joinpath(test_source_path, 'test/functional/fixtures'), result)
+    end)
+
+    it('works with a filename argument', function()
+      eq(test_source_path, exec_lua([[return vim.fs.root(..., '.git')]], nvim_prog))
+    end)
+  end)
+
   describe('joinpath()', function()
     it('works', function()
       eq('foo/bar/baz', vim.fs.joinpath('foo', 'bar', 'baz'))