feat(lsp): add fswatch watchfunc backend

Problem:
  vim._watch.watchdirs has terrible performance.

Solution:
  - On linux use fswatch as a watcher backend if available.

  - Add File watcher section to health:vim.lsp. Warn if watchfunc is
    libuv-poll.

7 files changed, 140 insertions, 11 deletions

diff --git a/.github/scripts/install_deps.sh b/.github/scripts/install_deps.sh
index 9a782e9698..ad81e053f9 100755
--- a/.github/scripts/install_deps.sh
+++ b/.github/scripts/install_deps.sh
@@ -30,12 +30,12 @@ if [[ $os == Linux ]]; then
   fi
 
   if [[ -n $TEST ]]; then
-    sudo apt-get install -y locales-all cpanminus attr libattr1-dev gdb
+    sudo apt-get install -y locales-all cpanminus attr libattr1-dev gdb fswatch
   fi
 elif [[ $os == Darwin ]]; then
   brew update --quiet
   brew install ninja
   if [[ -n $TEST ]]; then
-    brew install cpanminus
+    brew install cpanminus fswatch
   fi
 fi
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 50beb79adf..516ff6f0fe 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -369,6 +369,9 @@ The following changes to existing APIs or features add new behavior.
 
 • The `workspace/didChangeWatchedFiles` LSP client capability is now enabled
   by default.
+  • On Mac or Windows, `libuv.fs_watch` is used as the backend.
+  • On Linux, `fswatch` (recommended) is used as the backend if available,
+    otherwise `libuv.fs_event` is used on each subdirectory.
 
 • |LspRequest| autocmd callbacks now contain additional information about the LSP
   request status update that occurred.
diff --git a/runtime/lua/vim/_watch.lua b/runtime/lua/vim/_watch.lua
index 03b632b53c..d199cf8e29 100644
--- a/runtime/lua/vim/_watch.lua
+++ b/runtime/lua/vim/_watch.lua
@@ -222,5 +222,81 @@ function M.watchdirs(path, opts, callback)
   return cancel
 end
 
-return M
+--- @param data string
+--- @param opts vim._watch.Opts?
+--- @param callback vim._watch.Callback
+local function fswatch_output_handler(data, opts, callback)
+  local d = vim.split(data, '%s+')
+
+  -- only consider the last reported event
+  local fullpath, event = d[1], d[#d]
+
+  if skip(fullpath, opts) then
+    return
+  end
+
+  --- @type integer
+  local change_type
+
+  if event == 'Created' then
+    change_type = M.FileChangeType.Created
+  elseif event == 'Removed' then
+    change_type = M.FileChangeType.Deleted
+  elseif event == 'Updated' then
+    change_type = M.FileChangeType.Changed
+  elseif event == 'Renamed' then
+    local _, staterr, staterrname = uv.fs_stat(fullpath)
+    if staterrname == 'ENOENT' then
+      change_type = M.FileChangeType.Deleted
+    else
+      assert(not staterr, staterr)
+      change_type = M.FileChangeType.Created
+    end
+  end
+
+  if change_type then
+    callback(fullpath, change_type)
+  end
+end
+
+--- @param path string The path to watch. Must refer to a directory.
+--- @param opts vim._watch.Opts?
+--- @param callback vim._watch.Callback Callback for new events
+--- @return fun() cancel Stops the watcher
+function M.fswatch(path, opts, callback)
+  -- debounce isn't the same as latency but close enough
+  local latency = 0.5 -- seconds
+  if opts and opts.debounce then
+    latency = opts.debounce / 1000
+  end
 
+  local obj = vim.system({
+    'fswatch',
+    '--event=Created',
+    '--event=Removed',
+    '--event=Updated',
+    '--event=Renamed',
+    '--event-flags',
+    '--recursive',
+    '--latency=' .. tostring(latency),
+    '--exclude',
+    '/.git/',
+    path,
+  }, {
+    stdout = function(err, data)
+      if err then
+        error(err)
+      end
+
+      for line in vim.gsplit(data or '', '\n', { plain = true, trimempty = true }) do
+        fswatch_output_handler(line, opts, callback)
+      end
+    end,
+  })
+
+  return function()
+    obj:kill(2)
+  end
+end
+
+return M
diff --git a/runtime/lua/vim/lsp/_watchfiles.lua b/runtime/lua/vim/lsp/_watchfiles.lua
index c66a76feae..49328fbe9b 100644
--- a/runtime/lua/vim/lsp/_watchfiles.lua
+++ b/runtime/lua/vim/lsp/_watchfiles.lua
@@ -9,6 +9,8 @@ local M = {}
 
 if vim.fn.has('win32') == 1 or vim.fn.has('mac') == 1 then
   M._watchfunc = watch.watch
+elseif vim.fn.executable('fswatch') == 1 then
+  M._watchfunc = watch.fswatch
 else
   M._watchfunc = watch.watchdirs
 end
@@ -177,4 +179,3 @@ function M.cancel(client_id)
 end
 
 return M
-
diff --git a/runtime/lua/vim/lsp/health.lua b/runtime/lua/vim/lsp/health.lua
index 15e4555b55..797a1097f9 100644
--- a/runtime/lua/vim/lsp/health.lua
+++ b/runtime/lua/vim/lsp/health.lua
@@ -1,10 +1,9 @@
 local M = {}
 
---- Performs a healthcheck for LSP
-function M.check()
-  local report_info = vim.health.info
-  local report_warn = vim.health.warn
+local report_info = vim.health.info
+local report_warn = vim.health.warn
 
+local function check_log()
   local log = vim.lsp.log
   local current_log_level = log.get_level()
   local log_level_string = log.levels[current_log_level] ---@type string
@@ -27,9 +26,11 @@ function M.check()
 
   local report_fn = (log_size / 1000000 > 100 and report_warn or report_info)
   report_fn(string.format('Log size: %d KB', log_size / 1000))
+end
 
-  local clients = vim.lsp.get_clients()
+local function check_active_clients()
   vim.health.start('vim.lsp: Active Clients')
+  local clients = vim.lsp.get_clients()
   if next(clients) then
     for _, client in pairs(clients) do
       local attached_to = table.concat(vim.tbl_keys(client.attached_buffers or {}), ',')
@@ -48,4 +49,33 @@ function M.check()
   end
 end
 
+local function check_watcher()
+  vim.health.start('vim.lsp: File watcher')
+  local watchfunc = vim.lsp._watchfiles._watchfunc
+  assert(watchfunc)
+  local watchfunc_name --- @type string
+  if watchfunc == vim._watch.watch then
+    watchfunc_name = 'libuv-watch'
+  elseif watchfunc == vim._watch.watchdirs then
+    watchfunc_name = 'libuv-watchdirs'
+  elseif watchfunc == vim._watch.fswatch then
+    watchfunc_name = 'fswatch'
+  else
+    local nm = debug.getinfo(watchfunc, 'S').source
+    watchfunc_name = string.format('Custom (%s)', nm)
+  end
+
+  report_info('File watch backend: ' .. watchfunc_name)
+  if watchfunc_name == 'libuv-watchdirs' then
+    report_warn('libuv-watchdirs has known performance issues. Consider installing fswatch.')
+  end
+end
+
+--- Performs a healthcheck for LSP
+function M.check()
+  check_log()
+  check_active_clients()
+  check_watcher()
+end
+
 return M
diff --git a/test/functional/lua/watch_spec.lua b/test/functional/lua/watch_spec.lua
index fa84459b67..115fee8091 100644
--- a/test/functional/lua/watch_spec.lua
+++ b/test/functional/lua/watch_spec.lua
@@ -21,6 +21,15 @@ describe('vim._watch', function()
 
   local function run(watchfunc)
     it('detects file changes (watchfunc=' .. watchfunc .. '())', function()
+      if watchfunc == 'fswatch' then
+        skip(is_os('mac'), 'flaky test on mac')
+        skip(
+          not is_ci() and helpers.fn.executable('fswatch') == 0,
+          'fswatch not installed and not on CI'
+        )
+        skip(is_os('win'), 'not supported on windows')
+      end
+
       if watchfunc == 'watch' then
         skip(is_os('bsd'), 'Stopped working on bsd after 3ca967387c49c754561c3b11a574797504d40f38')
       else
@@ -95,6 +104,7 @@ describe('vim._watch', function()
 
       vim.uv.sleep(100)
       touch(watched_path)
+      vim.uv.sleep(100)
       os.remove(watched_path)
       vim.uv.sleep(100)
 
@@ -113,5 +123,5 @@ describe('vim._watch', function()
 
   run('watch')
   run('watchdirs')
+  run('fswatch')
 end)
-
diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua
index 1610351090..1e787d2b0c 100644
--- a/test/functional/plugin/lsp_spec.lua
+++ b/test/functional/plugin/lsp_spec.lua
@@ -4494,6 +4494,15 @@ describe('LSP', function()
       it(
         string.format('sends notifications when files change (watchfunc=%s)', watchfunc),
         function()
+          if watchfunc == 'fswatch' then
+            skip(
+              not is_ci() and fn.executable('fswatch') == 0,
+              'fswatch not installed and not on CI'
+            )
+            skip(is_os('win'), 'not supported on windows')
+            skip(is_os('mac'), 'flaky')
+          end
+
           skip(
             is_os('bsd'),
             'kqueue only reports events on watched folder itself, not contained files #26110'
@@ -4614,6 +4623,7 @@ describe('LSP', function()
 
     test_filechanges('watch')
     test_filechanges('watchdirs')
+    test_filechanges('fswatch')
 
     it('correctly registers and unregisters', function()
       local root_dir = '/some_dir'
@@ -5078,4 +5088,3 @@ describe('LSP', function()
     end)
   end)
 end)
-