path: root/runtime/lua/vim/lsp/inline_completion.lua

--- @brief
--- This module provides the LSP "inline completion" feature, for completing multiline text (e.g.,
--- whole methods) instead of just a word or line, which may result in "syntactically or
--- semantically incorrect" code. Unlike regular completion, this is typically presented as overlay
--- text instead of a menu of completion candidates.
---
--- LSP spec: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_inlineCompletion
---
--- To try it out, here is a quickstart example using Copilot: [lsp-copilot]()
---
--- 1. Install Copilot:
---    ```sh
---    npm install --global @github/copilot-language-server
---    ```
--- 2. Define a config, (or copy `lsp/copilot.lua` from https://github.com/neovim/nvim-lspconfig):
---    ```lua
---    vim.lsp.config('copilot', {
---      cmd = { 'copilot-language-server', '--stdio' },
---      root_markers = { '.git' },
---       init_options = {
---         editorInfo = {
---           name = 'Neovim', version = tostring(vim.version()) },
---           editorPluginInfo = { name = 'Neovim', version = tostring(vim.version()) },
---         },
---    })
---    ```
--- 3. Activate the config:
---    ```lua
---    vim.lsp.enable('copilot')
---    ```
--- 4. Sign in to Copilot, or use the `:LspCopilotSignIn` command from https://github.com/neovim/nvim-lspconfig
--- 5. Enable inline completion:
---    ```lua
---    vim.lsp.inline_completion.enable()
---    ```
--- 6. Set a keymap for `vim.lsp.inline_completion.get()` and invoke the keymap.

local util = require('vim.lsp.util')
local log = require('vim.lsp.log')
local protocol = require('vim.lsp.protocol')
local grammar = require('vim.lsp._snippet_grammar')
local api = vim.api
local nvim_on = require('vim._core.util').nvim_on

local Capability = require('vim.lsp._capability')

local M = {}

local namespace = api.nvim_create_namespace('nvim.lsp.inline_completion')

---@class vim.lsp.inline_completion.Item
---@field _index integer The index among all items form all clients.
---@field client_id integer Client ID
---@field insert_text string|lsp.StringValue The text to be inserted, can be a snippet.
---@field _filter_text? string
---@field range? vim.Range Which range it be applied.
---@field command? lsp.Command Corresponding server command.

---@class (private) vim.lsp.inline_completion.ClientState
---@field items? lsp.InlineCompletionItem[]

---@class (private) vim.lsp.inline_completion.Completor : vim.lsp.Capability
---@field active table<integer, vim.lsp.inline_completion.Completor?>
---@field timer? uv.uv_timer_t Timer for debouncing automatic requests
---@field current? vim.lsp.inline_completion.Item Currently selected item
---@field _overlay? boolean Whether `current` replaces buffer text, per its original range
---@field client_state table<integer, vim.lsp.inline_completion.ClientState>
local Completor = {
  name = 'inline_completion',
  method = 'textDocument/inlineCompletion',
  active = {},
}
Completor.__index = Completor
setmetatable(Completor, Capability)
Capability.all[Completor.name] = Completor

---@package
---@param buf integer
---@return vim.lsp.inline_completion.Completor
function Completor:new(buf)
  self = Capability.new(self, buf)
  self.client_state = {}
  nvim_on({ 'InsertEnter', 'CursorMovedI', 'TextChangedP' }, self.augroup, { buf = buf }, function()
    self:automatic_request()
  end)
  nvim_on({ 'InsertLeave' }, self.augroup, { buf = buf }, function()
    self:abort()
  end)
  return self
end

---@package
function Completor:destroy()
  self:reset_timer()
  api.nvim_buf_clear_namespace(self.bufnr, namespace, 0, -1)
  Capability.destroy(self)
end

--- Longest common prefix
---
---@param a string
---@param b string
---@return integer index where the common prefix ends, exclusive
local function lcp(a, b)
  local i, la, lb = 1, #a, #b
  while i <= la and i <= lb and a:sub(i, i) == b:sub(i, i) do
    i = i + 1
  end
  return i
end

--- `lsp.Handler` for `textDocument/inlineCompletion`.
---
---@package
---@param err? lsp.ResponseError
---@param result? lsp.InlineCompletionItem[]|lsp.InlineCompletionList
---@param ctx lsp.HandlerContext
function Completor:handler(err, result, ctx)
  if err then
    log.error('inline_completion', err)
    return
  end
  if not result or not vim.startswith(api.nvim_get_mode().mode, 'i') then
    return
  end

  local items = result.items or result
  self.client_state[ctx.client_id].items = items
  self:select(1)
end

---@package
function Completor:count_items()
  local n = 0
  for _, state in pairs(self.client_state) do
    local items = state.items
    if items then
      n = n + #items
    end
  end
  return n
end

---@package
---@param i integer
---@return integer?, lsp.InlineCompletionItem?
function Completor:get_item(i)
  local n = self:count_items()
  i = i % (n + 1)
  ---@type integer[]
  local client_ids = vim.tbl_keys(self.client_state)
  table.sort(client_ids)
  for _, client_id in ipairs(client_ids) do
    local items = self.client_state[client_id].items
    if items then
      if i > #items then
        i = i - #items
      else
        return client_id, items[i]
      end
    end
  end
end

--- Select the {index}-th completion item.
---
---@package
---@param index integer
---@param show_index? boolean
function Completor:select(index, show_index)
  self.current = nil
  local client_id, item = self:get_item(index)
  if not client_id or not item then
    self:hide()
    return
  end

  local client = assert(vim.lsp.get_client_by_id(client_id))
  local range = item.range and vim.range.lsp(self.bufnr, item.range, client.offset_encoding)
  self.current = {
    _index = index,
    client_id = client_id,
    insert_text = item.insertText,
    range = range,
    _filter_text = item.filterText,
    command = item.command,
  }
  -- Recorded here because `show()` may grow the range over typed characters.
  self._overlay = range ~= nil and not range:is_empty()

  local hint = show_index and (' (%d/%d)'):format(index, self:count_items()) or nil
  self:show(hint)
end

--- Show or update the current completion item.
---
---@package
---@param hint? string
function Completor:show(hint)
  self:hide()
  local current = self.current
  if not current then
    return
  end

  local insert_text = current.insert_text
  local text = type(insert_text) == 'string' and insert_text
    or tostring(grammar.parse(insert_text.value))
  local lines = {} ---@type [string, string][][]
  for s in vim.gsplit(text, '\n', { plain = true }) do
    table.insert(lines, { { s, 'ComplHint' } })
  end
  if hint then
    table.insert(lines[#lines], { hint, 'ComplHintMore' })
  end

  local row, col ---@type integer, integer
  if current.range then
    row, col = current.range:to_extmark()
  else
    row, col =
      vim.pos.cursor(self.bufnr, api.nvim_win_get_cursor(vim.fn.bufwinid(self.bufnr))):to_extmark()
  end

  -- To ensure that virtual text remains visible continuously (without flickering)
  -- while the user is editing the buffer, we allow displaying expired virtual text.
  -- Since the position of virtual text may become invalid after document changes,
  -- out-of-range items are ignored.
  local line_text = api.nvim_buf_get_lines(self.bufnr, row, row + 1, false)[1]
  if not (line_text and #line_text >= col) then
    self.current = nil
    return
  end

  -- The first line of the text to be inserted
  -- usually contains characters entered by the user,
  -- which should be skipped before displaying the virtual text.
  -- Splitting on a nonempty separator always yields a line, with its first chunk.
  local virt_text = assert(lines[1])
  assert(virt_text[1])
  local skip = lcp(line_text:sub(col + 1), virt_text[1][1])
  local winid = api.nvim_get_current_win()
  -- At least, characters before the cursor should be skipped.
  if api.nvim_win_get_buf(winid) == self.bufnr then
    local cursor_row, cursor_col =
      vim.pos.cursor(self.bufnr, api.nvim_win_get_cursor(winid)):to_extmark()
    if row == cursor_row then
      -- Characters typed since the request lie past the item's range, so `accept()`
      -- would leave them behind. `skip` stops where the buffer stops matching.
      if current.range and col + skip - 1 >= cursor_col then
        local start_row, start_col, _, end_col = current.range:to_extmark()
        if end_col < cursor_col then
          current.range = vim.range.extmark(self.bufnr, start_row, start_col, row, cursor_col)
        end
      end
      skip = math.max(skip, cursor_col - col + 1)
    end
  end
  virt_text[1][1] = virt_text[1][1]:sub(skip)
  col = col + skip - 1

  local virt_lines = { unpack(lines, 2) }
  for i, s in ipairs(virt_lines) do
    if #s == 1 and s[1][1] == '' then
      virt_lines[i] = {}
    end
  end

  api.nvim_buf_set_extmark(self.bufnr, namespace, row, col, {
    virt_text = virt_text,
    virt_lines = virt_lines,
    virt_text_pos = (self._overlay and 'overlay') or 'inline',
    hl_mode = 'combine',
  })
end

--- Hide the current completion item.
---
---@package
function Completor:hide()
  api.nvim_buf_clear_namespace(self.bufnr, namespace, 0, -1)
end

---@package
---@param kind lsp.InlineCompletionTriggerKind
function Completor:request(kind)
  for client_id in pairs(self.client_state) do
    local client = assert(vim.lsp.get_client_by_id(client_id))
    ---@type lsp.InlineCompletionContext
    local context = { triggerKind = kind }
    if
      kind == protocol.InlineCompletionTriggerKind.Invoked and api.nvim_get_mode().mode:match('^v')
    then
      context.selectedCompletionInfo = {
        range = util.make_given_range_params(nil, nil, self.bufnr, client.offset_encoding).range,
        text = table.concat(vim.fn.getregion(vim.fn.getpos("'<"), vim.fn.getpos("'>")), '\n'),
      }
    end

    ---@type lsp.InlineCompletionParams
    local params = {
      textDocument = util.make_text_document_params(self.bufnr),
      position = util.make_position_params(0, client.offset_encoding).position,
      context = context,
    }
    client:request('textDocument/inlineCompletion', params, function(...)
      self:handler(...)
    end, self.bufnr)
  end
end

---@private
function Completor:reset_timer()
  local timer = self.timer
  if timer then
    self.timer = nil
    if not timer:is_closing() then
      timer:stop()
      timer:close()
    end
  end
end

--- Automatically request with debouncing, used as callbacks in autocmd events.
---
---@package
function Completor:automatic_request()
  self:show()
  self:reset_timer()
  self.timer = vim.defer_fn(function()
    self:request(protocol.InlineCompletionTriggerKind.Automatic)
  end, 200)
end

--- Abort the current completion item and pending requests.
---
---@package
function Completor:abort()
  util._cancel_requests({
    bufnr = self.bufnr,
    method = 'textDocument/inlineCompletion',
    type = 'pending',
  })
  self:reset_timer()
  self:hide()
  self.current = nil
end

--- Accept the current completion item to the buffer.
---
---@package
---@param item vim.lsp.inline_completion.Item
function Completor:accept(item)
  local insert_text = item.insert_text
  if type(insert_text) == 'string' then
    if item.range then
      local start_row, start_col, end_row, end_col = item.range:to_extmark()
      -- The line may have shrunk past the range since the item arrived.
      local end_line = api.nvim_buf_get_lines(self.bufnr, end_row, end_row + 1, true)[1]
      end_col = math.min(end_col, #end_line)

      local lines = vim.split(insert_text, '\n')
      api.nvim_buf_set_text(self.bufnr, start_row, start_col, end_row, end_col, lines)
      local win = api.nvim_get_current_win()
      win = api.nvim_win_get_buf(win) == self.bufnr and win or vim.fn.bufwinid(self.bufnr)
      local row, col = item.range:to_mark()
      api.nvim_win_set_cursor(win, {
        row + #lines - 1,
        (#lines == 1 and col or 0) + #<