From ad7211ac8f62d7c1f2696edb304fccb9ec4fdef9 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 27 Apr 2025 10:32:25 -0700 Subject: [PATCH] feat(checkhealth): trigger FileType event after showing report 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. --- runtime/doc/health.txt | 65 +++++++++-------- runtime/doc/news.txt | 2 + runtime/lua/vim/health.lua | 98 ++++++++++++++------------ test/functional/plugin/health_spec.lua | 47 +++++++++--- 4 files changed, 129 insertions(+), 83 deletions(-) diff --git a/runtime/doc/health.txt b/runtime/doc/health.txt index 3d37b88321..a93eab6f6c 100644 --- 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 = {} - 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 - 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 + return M +< error({msg}, {...}) *vim.health.error()* diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 435c3a6ef4..cdf2db8032 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -343,6 +343,8 @@ PLUGINS • 'commentstring' values can now be specified in a Treesitter capture's `bo.commentstring` metadata field, providing finer grained support for languages like `JSX`. +• 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 index c95499e500..215bafc582 100644 --- a/runtime/lua/vim/health.lua +++ b/runtime/lua/vim/health.lua @@ -1,16 +1,16 @@ --- @brief ----
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|
 ---
+---
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' }
 ---
+---

+---
+--- 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
+--- ```
+---
+---
help
 --- --------------------------------------------------------------------------------
 --- 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...
+--- 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
+--- - 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.
+--- 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
+--- Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path with your plugin
+--- name:
 ---
----         local M = {}
+--- ```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
+--- 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
----
+--- return M +--- ``` local M = {} @@ -385,7 +395,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 @@ -463,6 +472,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 index 58634460c8..c22823b747 100644 --- 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' } }