refactor: migrate cursor handling to vim.Pos

This migrates internal cursor handling from the legacy (line, col) tuple
representation to Neovim's experimental `vim.Pos` API, discussed in
#2574 (comment).

Using it removes many of the recurring +1/-1 conversions and comparisons
between the different coordinate systems, making the code easier to read
and should reduce off-by-one mistakes.

For compatibility with existing community sources, `context.cursor` and
`context.get_cursor()` are retained for now, while the implementation
use `context.pos` and `context.get_pos()`.

Author: soifou

lua/blink/cmp/completion/accept/init.lua

@@ -64,12 +64,9 @@ local function apply_item(ctx, item)
 
     -- OR Normal: Apply the text edit and move the cursor
   else
-    local new_cursor = text_edits_lib.get_apply_end_position(item.textEdit, all_text_edits)
-    new_cursor[2] = new_cursor[2]
-
+    local new_pos = text_edits_lib.get_apply_end_position(item.textEdit, all_text_edits)
     text_edits_lib.apply(item.textEdit, all_text_edits)
-
-    ctx.set_cursor(new_cursor)
+    ctx.set_cursor(new_pos)
     text_edits_lib.move_cursor_in_dot_repeat(offset)
   end
 

lua/blink/cmp/completion/accept/preview.lua

@@ -1,7 +1,7 @@
 local nvim = require('blink.lib.nvim')
 
 --- @param item blink.cmp.CompletionItem
---- @return lsp.TextEdit, blink.cmp.CursorPos?
+--- @return lsp.TextEdit, vim.Pos?
 local function preview(item)
   local text_edits_lib = require('blink.cmp.lib.text_edits')
   local text_edit = text_edits_lib.get_from_item(item)
@@ -16,7 +16,7 @@ local function preview(item)
   -- only keep the first line.
   text_edit.newText = vim.split(text_edit.newText, '\n', { plain = true, trimempty = true })[1] or '' -- vim.split returns an empty list if the string was empty, making [1] nil
 
-  local original_cursor = nvim.win_get_cursor(0)
+  local original_pos = vim.pos.cursor(0)
   local cursor_pos = {
     text_edit.range.start.line + 1,
     text_edit.range.start.character + #text_edit.newText,
@@ -33,7 +33,7 @@ local function preview(item)
     cursor_moved = true
   end
 
-  return undo_text_edit, cursor_moved and original_cursor or nil
+  return undo_text_edit, cursor_moved and original_pos or nil
 end
 
 return preview

lua/blink/cmp/completion/brackets/config.lua

@@ -1,5 +1,5 @@
 local css_exceptions = function(ctx)
-  local str = string.sub(ctx.line, 1, ctx.cursor[2] or #ctx.line)
+  local str = string.sub(ctx.line, 1, ctx.pos.col or #ctx.line)
   return not str:find('[%w_-]*::?[%w-]*$')
 end
 local typescript_exceptions = function(ctx) return ctx.line:find('^%s*import%s') == nil end

lua/blink/cmp/completion/brackets/semantic.lua

@@ -4,7 +4,7 @@ local config = require('blink.cmp.config').completion.accept.auto_brackets
 local utils = require('blink.cmp.completion.brackets.utils')
 
 --- @class blink.cmp.SemanticRequest
---- @field cursor blink.cmp.CursorPos
+--- @field pos vim.Pos
 --- @field item blink.cmp.CompletionItem
 --- @field filetype string
 --- @field callback fun(added: boolean)
@@ -34,17 +34,18 @@ function semantic.process_request(tokens)
   local request = semantic.request
   if request == nil then return end
 
-  local cursor = nvim.win_get_cursor(0)
+  local pos = vim.pos.cursor(0)
+
   -- cancel if the cursor moved
-  if request.cursor[1] ~= cursor[1] or request.cursor[2] ~= cursor[2] then return semantic.finish_request() end
+  if request.pos ~= pos then return semantic.finish_request() end
 
   for _, token in ipairs(tokens) do
     if
       (token.type == 'function' or token.type == 'method')
-      and cursor[1] - 1 == token.line
-      and cursor[2] >= token.start_col
+      and pos.row == token.line
+      and pos.col >= token.start_col
       -- we do <= to check 1 character before the cursor (`bar|` would check `r`)
-      and cursor[2] <= token.end_col
+      and pos.col <= token.end_col
     then
       -- add the brackets
       -- TODO: make dot repeatable
@@ -55,12 +56,12 @@ function semantic.process_request(tokens)
         {
           newText = brackets_for_filetype[1] .. brackets_for_filetype[2],
           range = {
-            start = { line = cursor[1] - 1, character = start_col },
-            ['end'] = { line = cursor[1] - 1, character = start_col },
+            start = { line = pos.row, character = start_col },
+            ['end'] = { line = pos.row, character = start_col },
           },
         },
       }, nvim.get_current_buf(), 'utf-8')
-      nvim.win_set_cursor(0, { cursor[1], start_col + #brackets_for_filetype[1] })
+      nvim.win_set_cursor(0, { pos.row + 1, start_col + #brackets_for_filetype[1] })
       return semantic.finish_request()
     end
   end
@@ -89,9 +90,9 @@ function semantic.add_brackets_via_semantic_token(ctx, filetype, item)
     if highlighter == nil then return resolve(false) end
 
     semantic.timer:stop()
-    local cursor = nvim.win_get_cursor(0)
+    local pos = vim.pos.cursor(0)
     semantic.request = {
-      cursor = nvim.win_get_cursor(0),
+      pos = pos,
       filetype = filetype,
       item = item,
       callback = resolve,
@@ -102,7 +103,7 @@ function semantic.add_brackets_via_semantic_token(ctx, filetype, item)
 
     -- first check if a semantic token already exists at the current cursor position
     -- we get the token 1 character before the cursor (`bar|` would check `r`)
-    local tokens = vim.lsp.semantic_tokens.get_at_pos(0, cursor[1] - 1, cursor[2] - 1)
+    local tokens = vim.lsp.semantic_tokens.get_at_pos(0, pos.row, pos.col - 1)
     if tokens ~= nil then semantic.process_request(tokens) end
     if semantic.request == nil then
       -- a matching token exists, and brackets were added

lua/blink/cmp/completion/list.lua

@@ -10,7 +10,7 @@
 --- @field items blink.cmp.CompletionItem[]
 --- @field selected_item_idx? integer
 --- @field is_explicitly_selected boolean
---- @field preview_undo? { text_edit: lsp.TextEdit, cursor_before?: blink.cmp.CursorPos, cursor_after: blink.cmp.CursorPos }
+--- @field preview_undo? { text_edit: lsp.TextEdit, pos_before?: vim.Pos, pos_after: vim.Pos }
 ---
 --- @field show fun(context: blink.cmp.Context, items: table<string, blink.cmp.CompletionItem[]>)
 --- @field fuzzy fun(context: blink.cmp.Context, items: table<string, blink.cmp.CompletionItem[]>): blink.cmp.CompletionItem[]
@@ -140,12 +140,9 @@ end
 
 function list.fuzzy(ctx, items_by_source)
   local fuzzy = require('blink.cmp.fuzzy')
-  local filtered_items = fuzzy.fuzzy(
-    ctx.get_line(),
-    ctx.get_cursor()[2],
-    items_by_source,
-    require('blink.cmp.config').completion.keyword.range
-  )
+  local pos = ctx.get_pos()
+  local filtered_items =
+    fuzzy.fuzzy(ctx.get_line(), pos.col, items_by_source, require('blink.cmp.config').completion.keyword.range)
 
   -- apply the per source max_items
   filtered_items = require('blink.cmp.sources.lib').apply_max_items_for_completions(ctx, filtered_items)
@@ -328,13 +325,13 @@ function list.undo_preview()
   -- The text edit may be out of date due to the user typing more characters
   -- so we adjust the range to compensate
   -- TODO: Set offset_encoding
-  local old_cursor_col = list.preview_undo.cursor_after[2]
-  local new_cursor_col = context.get_cursor()[2]
-  text_edit = text_edits_lib.compensate_for_cursor_movement(text_edit, old_cursor_col, new_cursor_col)
+  local old_pos = list.preview_undo.pos_after
+  local new_pos = context.get_pos()
+  text_edit = text_edits_lib.compensate_for_cursor_movement(text_edit, old_pos, new_pos)
 
   require('blink.cmp.lib.text_edits').apply(text_edit)
-  if list.preview_undo.cursor_before ~= nil then
-    require('blink.cmp.completion.trigger.context').set_cursor(list.preview_undo.cursor_before)
+  if list.preview_undo.pos_before ~= nil then
+    require('blink.cmp.completion.trigger.context').set_cursor(list.preview_undo.pos_before)
   end
 
   list.preview_undo = nil
@@ -345,11 +342,12 @@ function list.apply_preview(item)
   list.undo_preview()
 
   -- apply the new preview
-  local undo_text_edit, undo_cursor = require('blink.cmp.completion.accept.preview')(item)
+  local undo_text_edit, undo_pos = require('blink.cmp.completion.accept.preview')(item)
+
   list.preview_undo = {
     text_edit = undo_text_edit,
-    cursor_before = undo_cursor,
-    cursor_after = context.get_cursor(),
+    pos_before = undo_pos,
+    pos_after = context.get_pos(),
   }
 end
 

lua/blink/cmp/completion/trigger/context.lua

@@ -12,7 +12,8 @@ local nvim = require('blink.lib.nvim')
 --- @field mode blink.cmp.Mode
 --- @field id integer
 --- @field bufnr integer
---- @field cursor blink.cmp.CursorPos
+--- @field cursor { [1]: integer, [2]: integer } Deprecated, use `pos` intead
+--- @field pos vim.Pos
 --- @field line string
 --- @field term blink.cmp.ContextTerm
 --- @field bounds blink.cmp.ContextBounds
@@ -23,11 +24,12 @@ local nvim = require('blink.lib.nvim')
 ---
 --- @field new fun(opts: blink.cmp.ContextOpts): blink.cmp.Context
 --- @field get_keyword fun(): string
---- @field within_query_bounds fun(self: blink.cmp.Context, cursor: blink.cmp.CursorPos, include_start_bound?: boolean): boolean
+--- @field within_query_bounds fun(self: blink.cmp.Context, include_start_bound?: boolean): boolean
 ---
 --- @field get_mode fun(): blink.cmp.Mode
---- @field get_cursor fun(): blink.cmp.CursorPos
---- @field set_cursor fun(cursor: blink.cmp.CursorPos)
+--- @field get_pos fun(): vim.Pos
+--- @field get_cursor fun(): { [1]: integer, [2]: integer } Deprecated, use `get_pos` intead
+--- @field set_cursor fun(pos: vim.Pos)
 --- @field get_line fun(num?: integer): string
 --- @field get_bounds fun(range: blink.cmp.CompletionKeywordRange): blink.cmp.ContextBounds
 --- @field get_term_command fun(): blink.cmp.ContextTermCommand?
@@ -60,15 +62,15 @@ local nvim = require('blink.lib.nvim')
 local context = {}
 
 function context.new(opts)
-  local cursor = context.get_cursor()
-  local line = context.get_line()
+  local pos = context.get_pos()
 
   return setmetatable({
     mode = context.get_mode(),
     id = opts.id,
     bufnr = nvim.get_current_buf(),
-    cursor = cursor,
-    line = line,
+    pos = pos,
+    cursor = pos:to_cursor(),
+    line = context.get_line(),
     term = { command = context.get_term_command() },
     bounds = context.get_bounds('full'),
     trigger = {
@@ -89,18 +91,19 @@ function context.get_keyword()
   return string.sub(context.get_line(), range.start_col, range.start_col + range.length - 1)
 end
 
---- @param cursor blink.cmp.CursorPos
 --- @param include_start_bound? boolean Whether to include the start boundary as inside of the query. E.g. start_col = 1 (one indexed), cursor[2] = 0 (zero indexed) would be considered within the query bounds with this flag enabled.
 --- @return boolean
-function context:within_query_bounds(cursor, include_start_bound)
-  local row, col = cursor[1], cursor[2]
-  col = col + 1 -- Convert from 0-indexed to 1-indexed
+function context:within_query_bounds(include_start_bound)
+  local pos, bounds = self.pos, self.bounds
+  if pos.row + 1 ~= bounds.line_number then return false end
 
-  local bounds = self.bounds
-  if include_start_bound then
-    return row == bounds.line_number and col >= bounds.start_col and col <= (bounds.start_col + bounds.length)
-  end
-  return row == bounds.line_number and col > bounds.start_col and col <= (bounds.start_col + bounds.length)
+  local cursor_col = pos.col + 1
+  local end_col = bounds.start_col + bounds.length
+  if cursor_col > end_col then return false end
+
+  if include_start_bound then return cursor_col >= bounds.start_col end
+
+  return cursor_col > bounds.start_col
 end
 
 function context.get_mode()
@@ -117,20 +120,25 @@ function context.get_mode()
     or 'default'
 end
 
-function context.get_cursor()
-  return context.get_mode() == 'cmdline' and { 1, vim.fn.getcmdpos() - 1 } or nvim.win_get_cursor(0)
+function context.get_pos()
+  local bufnr = context.bufnr or 0
+  if context.get_mode() == 'cmdline' then return vim.pos(bufnr, 0, vim.fn.getcmdpos() - 1) end
+
+  return vim.pos.cursor(bufnr)
 end
 
-function context.set_cursor(cursor)
+function context.get_cursor() return context.get_pos():to_cursor() end
+
+function context.set_cursor(pos)
   local mode = context.get_mode()
   if vim.tbl_contains({ 'default', 'term', 'cmdwin' }, mode) then
-    nvim.win_set_cursor(0, cursor)
+    nvim.win_set_cursor(0, pos:to_cursor())
     return
   end
 
   assert(mode == 'cmdline', 'Unsupported mode for setting cursor: ' .. mode)
-  assert(cursor[1] == 1, 'Cursor must be on the first line in cmdline mode')
-  vim.fn.setcmdpos(cursor[2])
+  assert(pos.row == 0, 'Cursor must be on the first line in cmdline mode')
+  vim.fn.setcmdpos(pos.col + 1)
 end
 
 function context.get_line(num)
@@ -143,16 +151,18 @@ function context.get_line(num)
   end
 
   -- This method works for normal buffers and the terminal prompt
-  if num == nil then num = context.get_cursor()[1] - 1 end
+  if not num then num = context.get_pos().row end
+
   return nvim.buf_get_lines(0, num, num + 1, false)[1] or ''
 end
 
 --- Gets characters around the cursor and returns the range, 0-indexed
 function context.get_bounds(range)
   local line = context.get_line()
-  local cursor = context.get_cursor()
-  local start_col, end_col = require('blink.cmp.fuzzy').get_keyword_range(line, cursor[2], range)
-  return { line = line, line_number = cursor[1], start_col = start_col + 1, length = end_col - start_col }
+  local pos = context.get_pos()
+  local start_col, end_col = require('blink.cmp.fuzzy').get_keyword_range(line, pos.col, range)
+
+  return { line = line, line_number = pos.row + 1, start_col = start_col + 1, length = end_col - start_col }
 end
 
 --- Get the terminal command in the current line without the shell prompt.
@@ -168,18 +178,10 @@ end
 function context.get_term_command()
   if context.get_mode() ~= 'term' then return end
 
-  local cursor = context.get_cursor()
-  local cursor_row = cursor[1]
-  local cursor_col = cursor[2] + 1
-  local line = string.sub(context.get_line(), 1, cursor_col - 1)
-
-  local extmarks = nvim.buf_get_extmarks(
-    0,
-    nvim.create_namespace('blink_cmp_term_command_start'),
-    { cursor_row - 1, cursor_col - 1 },
-    { cursor_row - 1, 0 },
-    { limit = 1 }
-  )
+  local pos = context.get_pos()
+  local line = string.sub(context.get_line(), 1, pos.col)
+  local ns = nvim.create_namespace('blink_cmp_term_command_start')
+  local extmarks = nvim.buf_get_extmarks(0, ns, { pos.row, pos.col }, { pos.row, 0 }, { limit = 1 })
 
   --- If we find no mark for the start of the terminal command the terminal or shell
   --- probably does not support the FTCS_COMMAND_START escape sequence. The best effort