commit 63323a9c81a8a694c01175cac0d3088aa63ffc2b
parent b98aefc5841a26cfabe127bd764d633f6f49fb41
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 27 Apr 2025 10:32:25 -0700
feat(checkhealth): trigger FileType event after showing report #33677
Problem:
`FileType` event is fired before checkhealth report is finished, so
user can't override report settings or contents.
https://github.com/neovim/neovim/pull/33172#issuecomment-2833513916
Solution:
- Trigger FileType event later.
- Document how to remove emojis.
Diffstat:
4 files changed, 137 insertions(+), 92 deletions(-)
diff --git a/runtime/doc/health.txt b/runtime/doc/health.txt
@@ -9,18 +9,18 @@
==============================================================================
Checkhealth *vim.health* *health*
-
vim.health is a minimal framework to help users troubleshoot configuration and
any other environment conditions that a plugin might care about. Nvim ships
with healthchecks for configuration, performance, python support, ruby
support, clipboard support, and more.
To run all healthchecks, use: >vim
-
- :checkhealth
+ :checkhealth
<
+
Plugin authors are encouraged to write new healthchecks. |health-dev|
+
COMMANDS *health-commands*
*:che* *:checkhealth*
@@ -56,7 +56,6 @@ Local mappings in the healthcheck buffer:
q Closes the window.
Global configuration:
-
*g:health*
g:health Dictionary with the following optional keys:
- `style` (`'float'|nil`) Set to "float" to display :checkhealth in
@@ -65,16 +64,26 @@ g:health Dictionary with the following optional keys:
Example: >lua
vim.g.health = { style = 'float' }
+
+Local configuration:
+
+Checkhealth sets its buffer filetype to "checkhealth". You can customize the
+buffer by handling the |FileType| event. For example if you don't want emojis
+in the health report: >vim
+ autocmd FileType checkhealth :set modifiable | silent! %s/\v( ?[^\x00-\x7F])//g
+<
+
+
--------------------------------------------------------------------------------
Create a healthcheck *health-dev*
Healthchecks are functions that check the user environment, configuration, or
any other prerequisites that a plugin cares about. Nvim ships with
healthchecks in:
- - $VIMRUNTIME/autoload/health/
- - $VIMRUNTIME/lua/vim/lsp/health.lua
- - $VIMRUNTIME/lua/vim/treesitter/health.lua
- - and more...
+• $VIMRUNTIME/autoload/health/
+• $VIMRUNTIME/lua/vim/lsp/health.lua
+• $VIMRUNTIME/lua/vim/treesitter/health.lua
+• and more...
To add a new healthcheck for your own plugin, simply create a "health.lua"
module on 'runtimepath' that returns a table with a "check()" function. Then
@@ -82,35 +91,35 @@ module on 'runtimepath' that returns a table with a "check()" function. Then
For example if your plugin is named "foo", define your healthcheck module at
one of these locations (on 'runtimepath'):
- - lua/foo/health/init.lua
- - lua/foo/health.lua
+• lua/foo/health/init.lua
+• lua/foo/health.lua
-If your plugin also provides a submodule named "bar" for which you want
-a separate healthcheck, define the healthcheck at one of these locations:
- - lua/foo/bar/health/init.lua
- - lua/foo/bar/health.lua
+If your plugin also provides a submodule named "bar" for which you want a
+separate healthcheck, define the healthcheck at one of these locations:
+• lua/foo/bar/health/init.lua
+• lua/foo/bar/health.lua
All such health modules must return a Lua table containing a `check()`
function.
Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path
with your plugin name: >lua
-
- local M = {}
-
- M.check = function()
- vim.health.start("foo report")
- -- make sure setup function parameters are ok
- if check_setup() then
- vim.health.ok("Setup is correct")
- else
- vim.health.error("Setup is incorrect")
- end
- -- do some more checking
- -- ...
- end
-
- return M
+ local M = {}
+
+ M.check = function()
+ vim.health.start("foo report")
+ -- make sure setup function parameters are ok
+ if check_setup() then
+ vim.health.ok("Setup is correct")
+ else
+ vim.health.error("Setup is incorrect")
+ end
+ -- do some more checking
+ -- ...
+ end
+
+ return M
+<
error({msg}, {...}) *vim.health.error()*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
@@ -159,7 +159,8 @@ PERFORMANCE
PLUGINS
-• todo
+• Customize :checkhealth by handling a `FileType checkhealth` event.
+ |health-usage|
STARTUP
diff --git a/runtime/lua/vim/health.lua b/runtime/lua/vim/health.lua
@@ -1,16 +1,16 @@
--- @brief
----<pre>help
---- vim.health is a minimal framework to help users troubleshoot configuration and
---- any other environment conditions that a plugin might care about. Nvim ships
---- with healthchecks for configuration, performance, python support, ruby
---- support, clipboard support, and more.
---
---- To run all healthchecks, use: >vim
+--- vim.health is a minimal framework to help users troubleshoot configuration and any other
+--- environment conditions that a plugin might care about. Nvim ships with healthchecks for
+--- configuration, performance, python support, ruby support, clipboard support, and more.
---
---- :checkhealth
---- <
+--- To run all healthchecks, use:
+--- ```vim
+--- :checkhealth
+--- ```
--- Plugin authors are encouraged to write new healthchecks. |health-dev|
---
+---<pre>help
--- COMMANDS *health-commands*
---
--- *:che* *:checkhealth*
@@ -46,7 +46,6 @@
--- q Closes the window.
---
--- Global configuration:
----
--- *g:health*
--- g:health Dictionary with the following optional keys:
--- - `style` (`'float'|nil`) Set to "float" to display :checkhealth in
@@ -55,53 +54,64 @@
--- Example: >lua
--- vim.g.health = { style = 'float' }
---
+---</pre>
+---
+--- Local configuration:
+---
+--- Checkhealth sets its buffer filetype to "checkhealth". You can customize the buffer by handling
+--- the |FileType| event. For example if you don't want emojis in the health report:
+--- ```vim
+--- autocmd FileType checkhealth :set modifiable | silent! %s/\v( ?[^\x00-\x7F])//g
+--- ```
+---
+---<pre>help
--- --------------------------------------------------------------------------------
--- Create a healthcheck *health-dev*
+---</pre>
---
---- Healthchecks are functions that check the user environment, configuration, or
---- any other prerequisites that a plugin cares about. Nvim ships with
---- healthchecks in:
---- - $VIMRUNTIME/autoload/health/
---- - $VIMRUNTIME/lua/vim/lsp/health.lua
---- - $VIMRUNTIME/lua/vim/treesitter/health.lua
---- - and more...
+--- Healthchecks are functions that check the user environment, configuration, or any other
+--- prerequisites that a plugin cares about. Nvim ships with healthchecks in:
+--- - $VIMRUNTIME/autoload/health/
+--- - $VIMRUNTIME/lua/vim/lsp/health.lua
+--- - $VIMRUNTIME/lua/vim/treesitter/health.lua
+--- - and more...
---
---- To add a new healthcheck for your own plugin, simply create a "health.lua"
---- module on 'runtimepath' that returns a table with a "check()" function. Then
---- |:checkhealth| will automatically find and invoke the function.
+--- To add a new healthcheck for your own plugin, simply create a "health.lua" module on
+--- 'runtimepath' that returns a table with a "check()" function. Then |:checkhealth| will
+--- automatically find and invoke the function.
---
--- For example if your plugin is named "foo", define your healthcheck module at
--- one of these locations (on 'runtimepath'):
---- - lua/foo/health/init.lua
---- - lua/foo/health.lua
----
---- If your plugin also provides a submodule named "bar" for which you want
---- a separate healthcheck, define the healthcheck at one of these locations:
---- - lua/foo/bar/health/init.lua
---- - lua/foo/bar/health.lua
----
---- All such health modules must return a Lua table containing a `check()`
---- function.
----
---- Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path
---- with your plugin name: >lua
----
---- local M = {}
----
---- M.check = function()
---- vim.health.start("foo report")
---- -- make sure setup function parameters are ok
---- if check_setup() then
---- vim.health.ok("Setup is correct")
---- else
---- vim.health.error("Setup is incorrect")
---- end
---- -- do some more checking
---- -- ...
---- end
----
---- return M
----</pre>
+--- - lua/foo/health/init.lua
+--- - lua/foo/health.lua
+---
+--- If your plugin also provides a submodule named "bar" for which you want a separate healthcheck,
+--- define the healthcheck at one of these locations:
+--- - lua/foo/bar/health/init.lua
+--- - lua/foo/bar/health.lua
+---
+--- All such health modules must return a Lua table containing a `check()` function.
+---
+--- Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path with your plugin
+--- name:
+---
+--- ```lua
+--- local M = {}
+---
+--- M.check = function()
+--- vim.health.start("foo report")
+--- -- make sure setup function parameters are ok
+--- if check_setup() then
+--- vim.health.ok("Setup is correct")
+--- else
+--- vim.health.error("Setup is incorrect")
+--- end
+--- -- do some more checking
+--- -- ...
+--- end
+---
+--- return M
+--- ```
local M = {}
@@ -405,7 +415,6 @@ function M._check(mods, plugin_names)
vim.cmd.bwipe('health://')
end
vim.cmd.file('health://')
- vim.cmd.setfiletype('checkhealth')
-- This should only happen when doing `:checkhealth vim`
if next(healthchecks) == nil then
@@ -485,6 +494,7 @@ function M._check(mods, plugin_names)
-- Once we're done writing checks, set nomodifiable.
vim.bo[bufnr].modifiable = false
+ vim.cmd.setfiletype('checkhealth')
end
return M
diff --git a/test/functional/plugin/health_spec.lua b/test/functional/plugin/health_spec.lua
@@ -78,6 +78,15 @@ describe(':checkhealth', function()
]])
)
end)
+
+ it("vim.provider works with a misconfigured 'shell'", function()
+ clear()
+ command([[set shell=echo\ WRONG!!!]])
+ command('let g:loaded_perl_provider = 0')
+ command('let g:loaded_python3_provider = 0')
+ command('checkhealth vim.provider')
+ eq(nil, string.match(curbuf_contents(), 'WRONG!!!'))
+ end)
end)
describe('vim.health', function()
@@ -109,6 +118,33 @@ describe('vim.health', function()
]])
end)
+ it('user FileType handler can modify report', function()
+ -- Define a FileType autocmd that removes emoji chars.
+ source [[
+ autocmd FileType checkhealth :set modifiable | silent! %s/\v( ?[^\x00-\x7F])//g
+ checkhealth full_render
+ ]]
+ n.expect([[
+
+ ==============================================================================
+ test_plug.full_render: 1 1
+
+ report 1 ~
+ - OK life is fine
+ - WARNING no what installed
+ - ADVICE:
+ - pip what
+ - make what
+
+ report 2 ~
+ - stuff is stable
+ - ERROR why no hardcopy
+ - ADVICE:
+ - :help |:hardcopy|
+ - :help |:TOhtml|
+ ]])
+ end)
+
it('concatenates multiple reports', function()
command('checkhealth success1 success2 test_plug')
n.expect([[
@@ -245,17 +281,6 @@ describe('vim.health', function()
end)
end)
-describe(':checkhealth vim.provider', function()
- it("works correctly with a wrongly configured 'shell'", function()
- clear()
- command([[set shell=echo\ WRONG!!!]])
- command('let g:loaded_perl_provider = 0')
- command('let g:loaded_python3_provider = 0')
- command('checkhealth vim.provider')
- eq(nil, string.match(curbuf_contents(), 'WRONG!!!'))
- end)
-end)
-
describe(':checkhealth window', function()
before_each(function()
clear { args = { '-u', 'NORC', '+set runtimepath+=test/functional/fixtures' } }
