feat(lsp)!: add vim.lsp.status, client.progress and promote LspProgressUpdate (#23958)

`client.messages` could grow unbounded because the default handler only
added new messages, never removing them.

A user either had to consume the messages by calling
`vim.lsp.util.get_progress_messages` or by manually removing them from
`client.messages.progress`. If they didn't do that, using LSP
effectively leaked memory.

To fix this, this deprecates the `messages` property and instead adds a
`progress` ring buffer that only keeps at most 50 messages. In addition
it deprecates `vim.lsp.util.get_progress_messages` in favour of a new
`vim.lsp.status()` and also promotes the `LspProgressUpdate` user
autocmd to a regular autocmd to allow users to pattern match on the
progress kind.

Also closes https://github.com/neovim/neovim/pull/20327

3 files changed, 42 insertions, 20 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 6494c53059..73888a32cc 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -117,19 +117,21 @@ internally and are no longer exposed as part of the API. Instead, use
 - *vim.lsp.diagnostic.set_virtual_text()*
 
 LSP FUNCTIONS
-- *vim.lsp.buf.range_code_action()*	Use |vim.lsp.buf.code_action()| with
-					the `range` parameter.
-- *vim.lsp.util.diagnostics_to_items()*	Use |vim.diagnostic.toqflist()| instead.
-- *vim.lsp.util.set_qflist()*		Use |setqflist()| instead.
-- *vim.lsp.util.set_loclist()*		Use |setloclist()| instead.
-- *vim.lsp.buf_get_clients()*		Use |vim.lsp.get_active_clients()| with
-					{buffer = bufnr} instead.
-- *vim.lsp.buf.formatting()*		Use |vim.lsp.buf.format()| with
-					{async = true} instead.
-- *vim.lsp.buf.formatting_sync()*	Use |vim.lsp.buf.format()| with
-					{async = false} instead.
-- *vim.lsp.buf.range_formatting()*	Use |vim.lsp.formatexpr()|
-					or |vim.lsp.buf.format()| instead.
+- *vim.lsp.buf.range_code_action()*		Use |vim.lsp.buf.code_action()| with
+						the `range` parameter.
+- *vim.lsp.util.diagnostics_to_items()*		Use |vim.diagnostic.toqflist()| instead.
+- *vim.lsp.util.set_qflist()*			Use |setqflist()| instead.
+- *vim.lsp.util.set_loclist()*			Use |setloclist()| instead.
+- *vim.lsp.buf_get_clients()*			Use |vim.lsp.get_active_clients()| with
+						{buffer = bufnr} instead.
+- *vim.lsp.buf.formatting()*			Use |vim.lsp.buf.format()| with
+						{async = true} instead.
+- *vim.lsp.buf.formatting_sync()*		Use |vim.lsp.buf.format()| with
+						{async = false} instead.
+- *vim.lsp.buf.range_formatting()*		Use |vim.lsp.formatexpr()|
+						or |vim.lsp.buf.format()| instead.
+- *vim.lsp.util.get_progress_messages()*	Use |vim.lsp.status()| or access
+						`progress` of |vim.lsp.client|
 
 TREESITTER FUNCTIONS
 - *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()|
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 5b7c013c57..7248d03196 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -659,14 +659,20 @@ callbacks. Example: >lua
     })
 <
 
-Also the following |User| |autocommand| is provided:
+LspProgress                                                       *LspProgress*
+    Upon receipt of a progress notification from the server. Notifications can
+    be polled from a `progress` ring buffer of a |vim.lsp.client| or use
+    |vim.lsp.status()| to get an aggregate message
 
-LspProgressUpdate                                          *LspProgressUpdate*
-    Upon receipt of a progress notification from the server. See
-    |vim.lsp.util.get_progress_messages()|.
+    If the server sends a "work done progress", the `pattern` is set to `kind`
+    (one of `begin`, `report` or `end`).
+
+    When used from Lua, the event contains a `data` table with `client_id` and
+    `result` properties. `result` will contain the request params sent by the
+    server.
 
 Example: >vim
-    autocmd User LspProgressUpdate redrawstatus
+    autocmd LspProgress * redrawstatus
 <
 
 ==============================================================================
@@ -806,6 +812,8 @@ client()                                                      *vim.lsp.client*
         |vim.lsp.start_client()|.
       • {server_capabilities} (table): Response from the server sent on
         `initialize` describing the server's capabilities.
+      • {progress} A ring buffer (|vim.ringbuf()|) containing progress
+        messages sent by the server.
 
 client_is_stopped({client_id})                   *vim.lsp.client_is_stopped()*
     Checks whether a client is stopped.
@@ -1092,6 +1100,13 @@ start_client({config})                                *vim.lsp.start_client()*
         not be fully initialized. Use `on_init` to do any actions once the
         client has been initialized.
 
+status()                                                    *vim.lsp.status()*
+    Consumes the latest progress messages from all clients and formats them as
+    a string. Empty if there are no clients or if no new messages
+
+    Return: ~
+        (string)
+
 stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
     Stops a client(s).
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index dbf5b131eb..87dfefcce8 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -33,8 +33,8 @@ The following changes may require adaptations in user config or plugins.
 • When switching windows, |CursorMoved| autocommands trigger when Nvim is back
   in the main loop rather than immediately. This is more compatible with Vim.
 
-• |LspRequest| autocmd was promoted from a |User| autocmd to a first class
-  citizen.
+• |LspRequest| and LspProgressUpdate (renamed to |LspProgress|) autocmds were
+  promoted from a |User| autocmd to first class citizen.
 
 • Renamed `vim.treesitter.playground` to `vim.treesitter.dev`.
 
@@ -43,6 +43,8 @@ ADDED FEATURES                                                     *news-added*
 
 The following new APIs or features were added.
 
+• Added |vim.lsp.status()| to consume the last progress messages as a string.
+
 • Neovim's LSP client now always saves and restores named buffer marks when
   applying text edits.
 
@@ -142,6 +144,9 @@ release.
   - |nvim_win_get_option()|	Use |nvim_get_option_value()| instead.
   - |nvim_win_set_option()|	Use |nvim_set_option_value()| instead.
 
+• vim.lsp functions:
+  - |vim.lsp.util.get_progress_messages()|	Use |vim.lsp.status()| instead.
+
 • `vim.loop` has been renamed to `vim.uv`.
 
  vim:tw=78:ts=8:sw=2:et:ft=help:norl: