fix(diagnostic)!: make virtual text handler opt-in (#32079)

Making this opt-out (on by default) was the wrong choice from the
beginning. It is too visually noisy to be enabled by default.

BREAKING CHANGE: Users must opt-in to the diagnostic virtual text
handler by adding

  vim.diagnostic.config({ virtual_text = true })

to their config.

4 files changed, 30 insertions, 6 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 7d97a18437..d4939d8cc7 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -464,7 +464,7 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
     Fields: ~
       • {underline}?         (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`)
                              Use underline for diagnostics.
-      • {virtual_text}?      (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `true`)
+      • {virtual_text}?      (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `false`)
                              Use virtual text for diagnostics. If multiple
                              diagnostics are set for a namespace, one prefix
                              per diagnostic + the last diagnostic message are
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 33ffeae2bb..ef97957d22 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -70,7 +70,9 @@ DIAGNOSTICS
   the "severity_sort" option.
 • Diagnostics are filtered by severity before being passed to a diagnostic
   handler |diagnostic-handlers|.
-
+• The "virtual_text" handler is disabled by default. Enable with >lua
+    vim.diagnostic.config({ virtual_text = true })
+<
 EDITOR
 
 • The order in which signs are placed was changed. Higher priority signs will
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 0939ff591e..ead75f7d51 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -70,7 +70,7 @@ end
 --- Use virtual text for diagnostics. If multiple diagnostics are set for a
 --- namespace, one prefix per diagnostic + the last diagnostic message are
 --- shown.
---- (default: `true`)
+--- (default: `false`)
 --- @field virtual_text? boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText
 ---
 --- Use signs for diagnostics |diagnostic-signs|.
@@ -312,7 +312,7 @@ M.severity = {
 local global_diagnostic_options = {
   signs = true,
   underline = true,
-  virtual_text = true,
+  virtual_text = false,
   float = true,
   update_in_insert = false,
   severity_sort = false,
diff --git a/test/functional/lua/diagnostic_spec.lua b/test/functional/lua/diagnostic_spec.lua
index e52a8991ce..80f4307d5b 100644
--- a/test/functional/lua/diagnostic_spec.lua
+++ b/test/functional/lua/diagnostic_spec.lua
@@ -369,6 +369,9 @@ describe('vim.diagnostic', function()
   end)
 
   it('handles one namespace clearing highlights while the other still has highlights', function()
+    exec_lua(function()
+      vim.diagnostic.config({ virtual_text = true })
+    end)
     -- 1 Error (1)
     -- 1 Warning (2)
     -- 1 Warning (2) + 1 Warning (1)
@@ -443,6 +446,10 @@ describe('vim.diagnostic', function()
   end)
 
   it('does not display diagnostics when disabled', function()
+    exec_lua(function()
+      vim.diagnostic.config({ virtual_text = true })
+    end)
+
     eq(
       { 0, 2 },
       exec_lua(function()
@@ -916,6 +923,10 @@ describe('vim.diagnostic', function()
 
   describe('reset()', function()
     it('diagnostic count is 0 and displayed diagnostics are 0 after call', function()
+      exec_lua(function()
+        vim.diagnostic.config({ virtual_text = true })
+      end)
+
       -- 1 Error (1)
       -- 1 Warning (2)
       -- 1 Warning (2) + 1 Warning (1)
@@ -2117,7 +2128,11 @@ describe('vim.diagnostic', function()
     end)
 
     it('can perform updates after insert_leave', function()
-      exec_lua [[vim.api.nvim_set_current_buf( _G.diagnostic_bufnr)]]
+      exec_lua(function()
+        vim.diagnostic.config({ virtual_text = true })
+        vim.api.nvim_set_current_buf(_G.diagnostic_bufnr)
+      end)
+
       api.nvim_input('o')
       eq({ mode = 'i', blocking = false }, api.nvim_get_mode())
 
@@ -2258,7 +2273,10 @@ describe('vim.diagnostic', function()
     end)
 
     it('can perform updates while in insert mode, if desired', function()
-      exec_lua [[vim.api.nvim_set_current_buf( _G.diagnostic_bufnr)]]
+      exec_lua(function()
+        vim.diagnostic.config({ virtual_text = true })
+        vim.api.nvim_set_current_buf(_G.diagnostic_bufnr)
+      end)
       api.nvim_input('o')
       eq({ mode = 'i', blocking = false }, api.nvim_get_mode())
 
@@ -2292,6 +2310,10 @@ describe('vim.diagnostic', function()
     end)
 
     it('can set diagnostics without displaying them', function()
+      exec_lua(function()
+        vim.diagnostic.config({ virtual_text = true })
+      end)
+
       eq(
         0,
         exec_lua(function()