fix(lsp): call on_list() even for single location (#25830)

Problem: Currently there is no way of customizing behavior of
  `declaration`, `definition`, `typeDefinition`, and `implementation`
  methods in `vim.lsp.buf` when LSP server returns `Location`. Instead,
  cursor jumps to that location directly.

Solution: Normalize LSP response to be `Location[]` for those four cases.

runtime/doc/lsp.txt

@@ -1179,8 +1179,8 @@ declaration({options})                             *vim.lsp.buf.declaration()*
       • {options}  (table|nil) additional options
                    • reuse_win: (boolean) Jump to existing window if buffer is
                      already open.
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 definition({options})                               *vim.lsp.buf.definition()*
     Jumps to the definition of the symbol under the cursor.
@@ -1189,8 +1189,8 @@ definition({options})                               *vim.lsp.buf.definition()*
       • {options}  (table|nil) additional options
                    • reuse_win: (boolean) Jump to existing window if buffer is
                      already open.
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 document_highlight()                        *vim.lsp.buf.document_highlight()*
     Send request to the server to resolve document highlights for the current
@@ -1271,8 +1271,8 @@ implementation({options})                       *vim.lsp.buf.implementation()*
 
     Parameters: ~
       • {options}  (table|nil) additional options
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 incoming_calls()                                *vim.lsp.buf.incoming_calls()*
     Lists all the call sites of the symbol under the cursor in the |quickfix|
@@ -1329,8 +1329,8 @@ type_definition({options})                     *vim.lsp.buf.type_definition()*
       • {options}  (table|nil) additional options
                    • reuse_win: (boolean) Jump to existing window if buffer is
                      already open.
-                   • on_list: (function) handler for list results. See
-                     |lsp-on-list-handler|
+                   • on_list: (function) |lsp-on-list-handler| replacing the
+                     default handler. Called for any non-empty result.
 
 workspace_symbol({query}, {options})          *vim.lsp.buf.workspace_symbol()*
     Lists all symbols in the current workspace in the quickfix window.

runtime/lua/vim/lsp/buf.lua

@@ -62,7 +62,8 @@ end
 ---
 ---@param options table|nil additional options
 ---     - reuse_win: (boolean) Jump to existing window if buffer is already open.
----     - on_list: (function) handler for list results. See |lsp-on-list-handler|
+---     - on_list: (function) |lsp-on-list-handler| replacing the default handler.
+---        Called for any non-empty result.
 function M.declaration(options)
   local params = util.make_position_params()
   request_with_options(ms.textDocument_declaration, params, options)
@@ -72,7 +73,8 @@ end
 ---
 ---@param options table|nil additional options
 ---     - reuse_win: (boolean) Jump to existing window if buffer is already open.
----     - on_list: (function) handler for list results. See |lsp-on-list-handler|
+---     - on_list: (function) |lsp-on-list-handler| replacing the default handler.
+---       Called for any non-empty result.
 function M.definition(options)
   local params = util.make_position_params()
   request_with_options(ms.textDocument_definition, params, options)
@@ -82,7 +84,8 @@ end
 ---
 ---@param options table|nil additional options
 ---     - reuse_win: (boolean) Jump to existing window if buffer is already open.
----     - on_list: (function) handler for list results. See |lsp-on-list-handler|
+---     - on_list: (function) |lsp-on-list-handler| replacing the default handler.
+---       Called for any non-empty result.
 function M.type_definition(options)
   local params = util.make_position_params()
   request_with_options(ms.textDocument_typeDefinition, params, options)
@@ -92,7 +95,8 @@ end
 --- quickfix window.
 ---
 ---@param options table|nil additional options
----     - on_list: (function) handler for list results. See |lsp-on-list-handler|
+---     - on_list: (function) |lsp-on-list-handler| replacing the default handler.
+---       Called for any non-empty result.
 function M.implementation(options)
   local params = util.make_position_params()
   request_with_options(ms.textDocument_implementation, params, options)

runtime/lua/vim/lsp/handlers.lua

@@ -407,15 +407,18 @@ local function location_handler(_, result, ctx, config)
 
   -- textDocument/definition can return Location or Location[]
   -- https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_definition
+  if not vim.tbl_islist(result) then
+    result = { result }
+  end
 
-  if vim.tbl_islist(result) then
   local title = 'LSP locations'
   local items = util.locations_to_items(result, client.offset_encoding)
 
   if config.on_list then
     assert(type(config.on_list) == 'function', 'on_list is not a function')
     config.on_list({ title = title, items = items })
-    else
+    return
+  end
   if #result == 1 then
     util.jump_to_location(result[1], client.offset_encoding, config.reuse_win)
     return
@@ -423,10 +426,6 @@ local function location_handler(_, result, ctx, config)
   vim.fn.setqflist({}, ' ', { title = title, items = items })
   api.nvim_command('botright copen')
 end
-  else
-    util.jump_to_location(result, client.offset_encoding, config.reuse_win)
-  end
-end
 
 --see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_declaration
 M[ms.textDocument_declaration] = location_handler