fix: change deprecation presentation

Deprecation with vim.deprecate is currently too noisy. Show the
following warning instead:

[function] is deprecated. Run ":checkhealth vim.deprecated" for more information.

The important part is that the full message needs to be short enough to
fit in one line in order to not trigger the "Press ENTER or type command
to continue" prompt.

The full information and stack trace for the deprecated functions will
be shown in the new healthcheck `vim.deprecated`.

3 files changed, 98 insertions, 24 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index ad2b3f5dab..5e9be509c8 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -1031,6 +1031,42 @@ function vim._cs_remote(rcid, server_addr, connect_error, args)
   }
 end
 
+do
+  local function truncated_echo(msg)
+    -- Truncate message to avoid hit-enter-prompt
+    local max_width = vim.o.columns * math.max(vim.o.cmdheight - 1, 0) + vim.v.echospace
+    local msg_truncated = string.sub(msg, 1, max_width)
+    vim.api.nvim_echo({ { msg_truncated, 'WarningMsg' } }, true, {})
+  end
+
+  local notified = false
+
+  function vim._truncated_echo_once(msg)
+    if not notified then
+      truncated_echo(msg)
+      notified = true
+      return true
+    end
+    return false
+  end
+end
+
+--- This is basically the same as debug.traceback(), except the full paths are shown.
+local function traceback()
+  local level = 4
+  local backtrace = { 'stack traceback:' }
+  while true do
+    local info = debug.getinfo(level, 'Sl')
+    if not info then
+      break
+    end
+    local msg = ('  %s:%s'):format(info.source:sub(2), info.currentline)
+    table.insert(backtrace, msg)
+    level = level + 1
+  end
+  return table.concat(backtrace, '\n')
+end
+
 --- Shows a deprecation message to the user.
 ---
 ---@param name        string     Deprecated feature (function, API, etc.).
@@ -1043,12 +1079,12 @@ end
 ---@return string|nil # Deprecated message, or nil if no message was shown.
 function vim.deprecate(name, alternative, version, plugin, backtrace)
   plugin = plugin or 'Nvim'
-  local will_be_removed = 'will be removed'
-
-  -- Only issue warning if feature is hard-deprecated as specified by MAINTAIN.md.
-  -- Example: if removal_version is 0.12 (soft-deprecated since 0.10-dev), show warnings starting at
-  -- 0.11, including 0.11-dev
   if plugin == 'Nvim' then
+    require('vim.deprecated.health').add(name, version, traceback(), alternative)
+
+    -- Only issue warning if feature is hard-deprecated as specified by MAINTAIN.md.
+    -- Example: if removal_version is 0.12 (soft-deprecated since 0.10-dev), show warnings starting at
+    -- 0.11, including 0.11-dev
     local major, minor = version:match('(%d+)%.(%d+)')
     major, minor = tonumber(major), tonumber(minor)
 
@@ -1059,8 +1095,12 @@ function vim.deprecate(name, alternative, version, plugin, backtrace)
       return
     end
 
-    local removal_version = string.format('nvim-%d.%d', major, minor)
-    will_be_removed = vim.fn.has(removal_version) == 1 and 'was removed' or will_be_removed
+    local msg = ('%s is deprecated. Run ":checkhealth vim.deprecated" for more information'):format(
+      name
+    )
+
+    local displayed = vim._truncated_echo_once(msg)
+    return displayed and msg or nil
   else
     vim.validate {
       name = { name, 'string' },
@@ -1068,22 +1108,16 @@ function vim.deprecate(name, alternative, version, plugin, backtrace)
       version = { version, 'string', true },
       plugin = { plugin, 'string', true },
     }
-  end
 
-  local msg = ('%s is deprecated'):format(name)
-  msg = alternative and ('%s, use %s instead.'):format(msg, alternative) or (msg .. '.')
-  msg = ('%s%s\nFeature %s in %s %s'):format(
-    msg,
-    (plugin == 'Nvim' and ' :help deprecated' or ''),
-    will_be_removed,
-    plugin,
-    version
-  )
-  local displayed = vim.notify_once(msg, vim.log.levels.WARN)
-  if displayed and backtrace ~= false then
-    vim.notify(debug.traceback('', 2):sub(2), vim.log.levels.WARN)
+    local msg = ('%s is deprecated'):format(name)
+    msg = alternative and ('%s, use %s instead.'):format(msg, alternative) or (msg .. '.')
+    msg = ('%s\nFeature will be removed in %s %s'):format(msg, plugin, version)
+    local displayed = vim.notify_once(msg, vim.log.levels.WARN)
+    if displayed and backtrace ~= false then
+      vim.notify(debug.traceback('', 2):sub(2), vim.log.levels.WARN)
+    end
+    return displayed and msg or nil
   end
-  return displayed and msg or nil
 end
 
 require('vim._options')
diff --git a/runtime/lua/vim/deprecated/health.lua b/runtime/lua/vim/deprecated/health.lua
new file mode 100644
index 0000000000..0f6b1f578c
--- /dev/null
+++ b/runtime/lua/vim/deprecated/health.lua
@@ -0,0 +1,42 @@
+local M = {}
+local health = vim.health
+
+local deprecated = {}
+
+function M.check()
+  if next(deprecated) == nil then
+    health.ok('No deprecated functions detected')
+    return
+  end
+
+  for name, v in vim.spairs(deprecated) do
+    health.start('')
+
+    local version, backtraces, alternative = v[1], v[2], v[3]
+    local major, minor = version:match('(%d+)%.(%d+)')
+    major, minor = tonumber(major), tonumber(minor)
+    local removal_version = string.format('nvim-%d.%d', major, minor)
+    local will_be_removed = vim.fn.has(removal_version) == 1 and 'was removed' or 'will be removed'
+
+    local msg = ('%s is deprecated. Feature %s in Nvim %s'):format(name, will_be_removed, version)
+    local msg_alternative = alternative and ('use %s instead.'):format(alternative)
+    local advice = { msg_alternative }
+    table.insert(advice, backtraces)
+    advice = vim.iter(advice):flatten():totable()
+    health.warn(msg, advice)
+  end
+end
+
+function M.add(name, version, backtrace, alternative)
+  if deprecated[name] == nil then
+    deprecated[name] = { version, { backtrace }, alternative }
+    return
+  end
+
+  local it = vim.iter(deprecated[name][2])
+  if it:find(backtrace) == nil then
+    table.insert(deprecated[name][2], backtrace)
+  end
+end
+
+return M
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index b5146e5beb..348204abb7 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -1279,9 +1279,7 @@ M.handlers.signs = {
           vim.deprecate(
             'Defining diagnostic signs with :sign-define or sign_define()',
             'vim.diagnostic.config()',
-            '0.12',
-            nil,
-            false -- suppress backtrace
+            '0.12'
           )
 
           if not opts.signs.text then