feat: debounce NES autocommands (#2)

* feat: debounce NES autocommands

* refactor: update NES API usage

Remove unused inline completion code and refactor NES functions to remove
redundant opts and client parameters. Clean up autocommands and key mappings
to use the streamlined NES API.

* docs: add usage guide and remove fixed keymap

Add a usage section to README.md with a Neovim configuration example.

* feat(nes): navigate to suggestion end

Update the apply_pending_nes function to create a new jump_loc
that navigates to the end of the text range. This change displays the
document at the correct position before applying the inline edit.

* feat: update keymap & inline edit flow

- Add Blink integration section to README.md.
- Update inline edit handling in nes to return boolean and schedule mode
  switching for integration with blink

* fix(util): use final function args in debounce

Remove redundant local variable assignment and update debounce to capture
and pass the final arguments. Add tests to confirm final parameters are used.

* ci: make timings more forgiving

* refactor(tests): update debounce tests to use lua_func

Refactor debounce tests in test_util.lua to use child.lua_func for running
tests.

* refactor(debounce): folke debounce

https://github.com/folke/noice.nvim/blob/0427460c2d7f673ad60eb02b35f5e9926cf67c59/lua/noice/util/init.lua#L104

* feat: configurable debounce for Copilot NES

Allow configuration of the debounce interval for Copilot NES by using
vim.g.copilot_nes_debounce in the initialization. If not set, a default
of 500ms is used.

* refactor: swap vim.loop to vim.uv

* refactor(lsp): upvalue for debounce

Author: tris203

README.md

@@ -17,14 +17,60 @@
 - Sign In Flow
 - Status Notification
 
+## Usage
+
+To use the plugin, add the following to your Neovim configuration:
+
+```lua
+return {
+    "copilotlsp-nvim/copilot-lsp",
+    init = function()
+        vim.g.copilot_nes_debounce = 500
+        vim.lsp.enable("copilot")
+        vim.keymap.set("n", "<tab>", function()
+            require("copilot-lsp.nes").apply_pending_nes()
+        end)
+    end,
+}
+```
+
+### Blink Integration
+
+```lua
+return {
+    keymap = {
+        preset = "super-tab",
+        ["<Tab>"] = {
+            function(cmp)
+                if vim.b[vim.api.nvim_get_current_buf()].nes_state then
+                    cmp.hide()
+                    return require("copilot-lsp.nes").apply_pending_nes()
+                end
+                if cmp.snippet_active() then
+                    return cmp.accept()
+                else
+                    return cmp.select_and_accept()
+                end
+            end,
+            "snippet_forward",
+            "fallback",
+        },
+    },
+}
+```
+
+It can also be combined with [fang2hou/blink-copilot](https://github.com/fang2hou/blink-copilot) to get inline completions.
+Just add the completion source to your Blink configuration and it will integrate
+
 # Requirements
 
 - Copilot LSP installed via Mason or system and on PATH
 
 ### Screenshots
 
 #### NES
+
 ![JS Correction](https://github.com/user-attachments/assets/8941f8f9-7d1b-4521-b8e9-f1dcd12d31e9)
 ![Go Insertion](https://github.com/user-attachments/assets/2c0c4ad9-873b-4860-9eff-ecdb76007234)
 
-https://github.com/user-attachments/assets/1d5bed4a-fd0a-491f-91f3-a3335cc28682
+<https://github.com/user-attachments/assets/1d5bed4a-fd0a-491f-91f3-a3335cc28682>

lsp/copilot.lua

@@ -25,33 +25,34 @@ return {
         vim.api.nvim_set_hl(0, "NesDelete", { link = "DiffDelete", default = true })
         vim.api.nvim_set_hl(0, "NesApply", { link = "DiffText", default = true })
 
-        local nes = require("copilot-lsp.nes")
-        local inline_completion = require("copilot-lsp.completion")
+        local au = vim.api.nvim_create_augroup("copilot-language-server", { clear = true })
+        --NOTE: Inline Completions
+        --TODO: We dont currently use this code path, so comment for now until a UI is built
+        -- vim.api.nvim_create_autocmd("TextChangedI", {
+        --     callback = function()
+        --         inline_completion.request_inline_completion(2)
+        --     end,
+        --     group = au,
+        -- })
 
         -- TODO: make this configurable for key maps, or just expose commands to map in config
-        vim.keymap.set("i", "<c-i>", function()
-            inline_completion.request_inline_completion(1)
-        end)
-
-        --TODO: This should go on an auto command
-        --I would like to debounce this, and call it automatically
-        --but we need to work on the clean up logic/tracking for the UI
-        vim.keymap.set("n", "<leader>x", function()
-            nes.request_nes(client)
-        end)
+        -- vim.keymap.set("i", "<c-i>", function()
+        --     inline_completion.request_inline_completion(1)
+        -- end)
 
-        vim.keymap.set("n", "<leader>xa", function()
-            nes.apply_pending_nes(nil, { trigger = true, jump = true }, client)
-        end)
-
-        local au = vim.api.nvim_create_augroup("copilot-language-server", { clear = true })
-        vim.api.nvim_create_autocmd("TextChangedI", {
+        --NOTE: NES Completions
+        local debounced_request = require("copilot-lsp.util").debounce(
+            require("copilot-lsp.nes").request_nes,
+            vim.g.copilot_nes_debounce or 500
+        )
+        vim.api.nvim_create_autocmd({ "TextChangedI", "TextChanged" }, {
             callback = function()
-                inline_completion.request_inline_completion(2)
+                debounced_request(client)
             end,
             group = au,
         })
 
+        --NOTE: didFocus
         vim.api.nvim_create_autocmd("BufEnter", {
             callback = function()
                 local td_params = vim.lsp.util.make_text_document_params()

lua/copilot-lsp/nes/init.lua

@@ -10,7 +10,7 @@ local nes_ns = vim.api.nvim_create_namespace("copilot-nes")
 ---@param result copilotlsp.copilotInlineEditResponse
 local function handle_nes_response(err, result)
     if err then
-        vim.notify(err.message)
+        -- vim.notify(err.message)
         return
     end
     for _, edit in ipairs(result.edits) do
@@ -31,25 +31,36 @@ function M.request_nes(copilot_lss)
 end
 
 ---@param bufnr? integer
----@param opts? nes.Apply.Opts
----@param client vim.lsp.Client
-function M.apply_pending_nes(bufnr, opts, client)
-    opts = opts or {}
-
+---@return boolean
+function M.apply_pending_nes(bufnr)
     bufnr = bufnr and bufnr > 0 and bufnr or vim.api.nvim_get_current_buf()
 
     ---@type copilotlsp.InlineEdit
     local state = vim.b[bufnr].nes_state
     if not state then
-        return
-    end
-    utils.apply_inline_edit(state)
-    nes_ui.clear_suggestion(bufnr, nes_ns)
-    if opts.trigger then
-        vim.schedule(function()
-            M.request_nes(client)
-        end)
+        return false
     end
+    vim.schedule(function()
+        local prev_mode = vim.api.nvim_get_mode().mode
+        if prev_mode == "i" then
+            vim.cmd("stopinsert!")
+        end
+        ---@type lsp.Location
+        local jump_loc = {
+            uri = state.textDocument.uri,
+            range = {
+                start = state.range["end"],
+                ["end"] = state.range["end"],
+            },
+        }
+        vim.lsp.util.show_document(jump_loc, "utf-16", { focus = true })
+        utils.apply_inline_edit(state)
+        nes_ui.clear_suggestion(bufnr, nes_ns)
+        if prev_mode == "i" then
+            vim.cmd("startinsert")
+        end
+    end)
+    return true
 end
 
 return M

lua/copilot-lsp/nes/state.lua

@@ -74,8 +74,13 @@ end
 ---@param edits copilotlsp.InlineEdit[]
 ---@param ns_id integer
 function M._display_next_suggestion(edits, ns_id)
+    local state = vim.b[vim.api.nvim_get_current_buf()].nes_state
+    if state then
+        M.clear_suggestion(vim.api.nvim_get_current_buf(), ns_id)
+    end
+
     if not edits or #edits == 0 then
-        vim.notify("No suggestion available", vim.log.levels.INFO)
+        -- vim.notify("No suggestion available", vim.log.levels.INFO)
         return
     end
     local bufnr = vim.uri_to_bufnr(edits[1].textDocument.uri)

lua/copilot-lsp/nes/ui.lua

@@ -12,10 +12,6 @@
 ---@class nes.EditSuggestionUI
 ---@field preview_winnr? integer
 
----@class nes.Apply.Opts
----@field jump? boolean | { hl_timeout: integer? } auto jump to the end of the new edit
----@field trigger? boolean auto trigger the next edit suggestion
-
 ---@class nes.DeleteExtmark
 --- Holds row information for delete highlight extmark.
 ---@field row number

lua/copilot-lsp/types.lua

@@ -7,4 +7,19 @@ function M.apply_inline_edit(edit)
     vim.lsp.util.apply_text_edits({ edit }, bufnr, "utf-16")
 end
 
+---Debounces calls to a function, and ensures it only runs once per delay
+---even if called repeatedly.
+---@param fn fun(...: any)
+---@param delay integer
+function M.debounce(fn, delay)
+    local timer = vim.uv.new_timer()
+    return function(...)
+        local argv = vim.F.pack_len(...)
+        timer:start(delay, 0, function()
+            timer:stop()
+            vim.schedule_wrap(fn)(vim.F.unpack_len(argv))
+        end)
+    end
+end
+
 return M

lua/copilot-lsp/util.lua

@@ -0,0 +1,116 @@
+local eq = MiniTest.expect.equality
+
+local child = MiniTest.new_child_neovim()
+
+local T = MiniTest.new_set()
+
+T["debounce"] = MiniTest.new_set({
+    hooks = {
+        pre_case = function()
+            child.restart({ "-u", "scripts/minimal_init.lua" })
+        end,
+        post_once = child.stop,
+    },
+})
+T["debounce"]["debounces calls to a function"] = function()
+    child.lua_func(function()
+        _G.called = 0
+        local fn = function()
+            _G.called = _G.called + 1
+        end
+
+        local debounced_fn = require("copilot-lsp.util").debounce(fn, 500)
+        debounced_fn()
+    end)
+
+    local called = child.lua_func(function()
+        return _G.called
+    end)
+    eq(called, 0)
+
+    vim.uv.sleep(100)
+    called = child.lua_func(function()
+        return _G.called
+    end)
+    eq(called, 0)
+    vim.uv.sleep(500)
+    called = child.lua_func(function()
+        return _G.called
+    end)
+    eq(called, 1)
+end
+T["debounce"]["function is called with final calls params"] = function()
+    child.lua_func(function()
+        _G.called = 0
+        local fn = function(a)
+            _G.called = a
+        end
+
+        local debounced_fn = require("copilot-lsp.util").debounce(fn, 500)
+        debounced_fn(1)
+        debounced_fn(2)
+        debounced_fn(3)
+    end)
+
+    local called = child.lua("return _G.called")
+    eq(called, 0)
+
+    vim.uv.sleep(100)
+    called = child.lua("return _G.called")
+    eq(called, 0)
+    vim.uv.sleep(100)
+    called = child.lua("return _G.called")
+    eq(called, 0)
+    vim.uv.sleep(500)
+    called = child.lua("return _G.called")
+    eq(called, 3)
+end
+T["debounce"]["function is only called once"] = function()
+    child.lua_func(function()
+        _G.called = {}
+        local fn = function(a)
+            table.insert(_G.called, a)
+        end
+
+        _G.debounced_fn = require("copilot-lsp.util").debounce(fn, 250)
+    end)
+
+    child.lua_func(function()
+        _G.debounced_fn(0)
+        _G.debounced_fn(1)
+        _G.debounced_fn(2)
+        _G.debounced_fn(3)
+        _G.debounced_fn(4)
+    end)
+
+    local called = child.lua_func(function()
+        return _G.called
+    end)
+    eq(#called, 0)
+
+    vim.uv.sleep(500)
+
+    called = child.lua_func(function()
+        return _G.called
+    end)
+    eq(#called, 1)
+
+    child.lua_func(function()
+        _G.debounced_fn(5)
+        _G.debounced_fn(6)
+        _G.debounced_fn(7)
+        _G.debounced_fn(8)
+        _G.debounced_fn(9)
+    end)
+
+    vim.uv.sleep(500)
+
+    called = child.lua_func(function()
+        return _G.called
+    end)
+    eq(#called, 2)
+
+    eq(called, { 4, 9 })
+end
+
+return T