vim-patch:9.1.1308: completion: cannot order matches by distance to cursor (#33491)

Problem:  During insert-mode completion, the most relevant match is often
          the one closest to the cursor—frequently just above the current line.
          However, both `<C-N>` and `<C-P>` tend to rank candidates from the
          current buffer that appear above the cursor near the bottom of the
          completion menu, rather than near the top. This ordering can feel
          unintuitive, especially when `noselect` is active, as it doesn't
          prioritize the most contextually relevant suggestions.

Solution: This change introduces a new sub-option value "nearest" for the
          'completeopt' setting. When enabled, matches from the current buffer
          are prioritized based on their proximity to the cursor position,
          improving the relevance of suggestions during completion
          (Girish Palya).

Key Details:
- Option: "nearest" added to 'completeopt'
- Applies to: Matches from the current buffer only
- Effect: Sorts completion candidates by their distance from the cursor
- Interaction with other options:
  - Has no effect if the `fuzzy` option is also present

This feature is helpful especially when working within large buffers where
multiple similar matches may exist at different locations.

You can test this feature with auto-completion using the snippet below. Try it
in a large file like `vim/src/insexpand.c`, where you'll encounter many
potential matches. You'll notice that the popup menu now typically surfaces the
most relevant matches—those closest to the cursor—at the top. Sorting by
spatial proximity (i.e., contextual relevance) often produces more useful
matches than sorting purely by lexical distance ("fuzzy").

Another way to sort matches is by recency, using an LRU (Least Recently Used)
cache—essentially ranking candidates based on how recently they were used.
However, this is often overkill in practice, as spatial proximity (as provided
by the "nearest" option) is usually sufficient to surface the most relevant
matches.

```vim
set cot=menuone,popup,noselect,nearest inf

def SkipTextChangedIEvent(): string
    # Suppress next event caused by <c-e> (or <c-n> when no matches found)
    set eventignore+=TextChangedI
    timer_start(1, (_) => {
        set eventignore-=TextChangedI
    })
    return ''
enddef

autocmd TextChangedI * InsComplete()

def InsComplete()
    if getcharstr(1) == '' && getline('.')->strpart(0, col('.') - 1) =~ '\k$'
        SkipTextChangedIEvent()
        feedkeys("\<c-n>", "n")
    endif
enddef

inoremap <silent> <c-e> <c-r>=<SID>SkipTextChangedIEvent()<cr><c-e>

inoremap <silent><expr> <tab>   pumvisible() ? "\<c-n>" : "\<tab>"
inoremap <silent><expr> <s-tab> pumvisible() ? "\<c-p>" : "\<s-tab>"
```

closes: vim/vim#17076

https://github.com/vim/vim/commit/b156588eb707a084bbff8685953a8892e1e45bca

Co-authored-by: Girish Palya <girishji@gmail.com>

1 files changed, 4 insertions, 0 deletions

diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 31bcc6485b..a3a5750e78 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -1123,6 +1123,10 @@ vim.go.cia = vim.go.completeitemalign
 --- 	    Useful when there is additional information about the
 --- 	    match, e.g., what file it comes from.
 ---
+---    nearest  Matches are presented in order of proximity to the cursor
+--- 	    position.  This applies only to matches from the current
+--- 	    buffer.  No effect if "fuzzy" is present.
+---
 ---    noinsert Do not insert any text for a match until the user selects
 --- 	    a match from the menu.  Only works in combination with
 --- 	    "menu" or "menuone". No effect if "longest" is present.