mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-05 19:08:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #33680 from justinmk/release

Browse Source
This commit is contained in:
Justin M. Keyes
2025-04-27 15:32:22 -07:00
committed by GitHub
parent 95ee908c40 f25f6c8d13
commit bc66a5ff6f
4 changed files with 173 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
runtime/doc/health.txt
View File

@@ -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()*

3
runtime/doc/news.txt
View File

@@ -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
@@ -437,6 +439,7 @@ UI
• |ui-messages| content chunks now also contain the highlight group ID.
• |:checkhealth| can display in a floating window, controlled by the
|g:health| variable.
• |:checkhealth| shows a summary in the header for every healthcheck.
VIMSCRIPT

126
runtime/lua/vim/health.lua
View File

@@ -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,57 +54,69 @@
--- 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
--- - 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
---</pre>
--- return M
--- ```
local M = {}
local s_output = {} ---@type string[]
local check_summary = { warn = 0, error = 0 }
-- From a path return a list [{name}, {func}, {type}] representing a healthcheck
local function filepath_to_healthcheck(path)
@@ -286,6 +297,7 @@ end
function M.warn(msg, ...)
local input = format_report_message('⚠️ WARNING', msg, ...)
collect_output(input)
check_summary['warn'] = check_summary['warn'] + 1
end
--- Reports an error.
@@ -295,6 +307,7 @@ end
function M.error(msg, ...)
local input = format_report_message('❌ ERROR', msg, ...)
collect_output(input)
check_summary['error'] = check_summary['error'] + 1
end
local path2name = function(path)
@@ -341,6 +354,23 @@ M._complete = function()
return rv
end
--- Gets the results heading for the current report section.
---
---@return string
local function get_summary()
local s = ''
local errors = check_summary['error']
local warns = check_summary['warn']
s = s .. (warns > 0 and (' %2d ⚠️'):format(warns) or '')
s = s .. (errors > 0 and (' %2d ❌'):format(errors) or '')
if errors == 0 and warns == 0 then
s = s .. '✅'
end
return s
end
--- Runs the specified healthchecks.
--- Runs all discovered healthchecks if plugin_names is empty.
---
@@ -385,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
@@ -399,9 +428,9 @@ function M._check(mods, plugin_names)
local func = value[1]
local type = value[2]
s_output = {}
check_summary = { warn = 0, error = 0 }
if func == '' then
s_output = {}
M.error('No healthcheck found for "' .. name .. '" plugin.')
end
if type == 'v' then
@@ -422,10 +451,12 @@ function M._check(mods, plugin_names)
M.error('The healthcheck report for "' .. name .. '" plugin is empty.')
end
local report = get_summary()
local replen = vim.fn.strwidth(report)
local header = {
string.rep('=', 78),
-- Example: `foo.health: [ …] require("foo.health").check()`
('%s: %s%s'):format(name, (' '):rep(76 - name:len() - func:len()), func),
-- Example: `foo.health: [ …] 1 ⚠️ 5 ❌`
('%s: %s%s'):format(name, (' '):rep(76 - name:len() - replen), report),
'',
}
@@ -463,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

83
test/functional/plugin/health_spec.lua
View File

@@ -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()
@@ -91,7 +100,7 @@ describe('vim.health', function()
n.expect([[
==============================================================================
test_plug.full_render: require("test_plug.full_render.health").check()
test_plug.full_render: 1 ⚠️ 1 ❌
report 1 ~
- ✅ OK life is fine
@@ -109,12 +118,39 @@ 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([[
==============================================================================
test_plug: require("test_plug.health").check()
test_plug: ✅
report 1 ~
- ✅ OK everything is fine
@@ -123,7 +159,7 @@ describe('vim.health', function()
- ✅ OK nothing to see here
==============================================================================
test_plug.success1: require("test_plug.success1.health").check()
test_plug.success1: ✅
report 1 ~
- ✅ OK everything is fine
@@ -132,7 +168,7 @@ describe('vim.health', function()
- ✅ OK nothing to see here
==============================================================================
test_plug.success2: require("test_plug.success2.health").check()
test_plug.success2: ✅
another 1 ~
- ✅ OK ok
@@ -144,7 +180,7 @@ describe('vim.health', function()
n.expect([[
==============================================================================
test_plug.submodule: require("test_plug.submodule.health").check()
test_plug.submodule: ✅
report 1 ~
- ✅ OK everything is fine
@@ -159,7 +195,7 @@ describe('vim.health', function()
n.expect([[
==============================================================================
test_plug.submodule_empty: require("test_plug.submodule_empty.health").check()
test_plug.submodule_empty: 1 ❌
- ❌ ERROR The healthcheck report for "test_plug.submodule_empty" plugin is empty.
]])
@@ -185,7 +221,7 @@ describe('vim.health', function()
- ❌ {Error:ERROR} No healthcheck found for "foo" plugin. |
|
{Bar: }|
{h1:test_plug.success1: require("test_pl}|
{h1:test_plug.success1: }|
|
{h2:report 1} |
- ✅ {Ok:OK} everything is fine |
@@ -200,7 +236,7 @@ describe('vim.health', function()
n.expect([[
==============================================================================
non_existent_healthcheck:
non_existent_healthcheck: 1 ❌
- ❌ ERROR No healthcheck found for "non_existent_healthcheck" plugin.
]])
@@ -218,7 +254,7 @@ describe('vim.health', function()
n.expect([[
==============================================================================
test_plug.lua: require("test_plug.lua.health").check()
test_plug.lua: ✅
nested lua/ directory ~
- ✅ OK everything is ok
@@ -236,7 +272,7 @@ describe('vim.health', function()
n.expect([[
==============================================================================
nest: require("nest.health").check()
nest: ✅
healthy pack ~
- ✅ OK healthy ok
@@ -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' } }
@@ -281,14 +306,14 @@ describe(':checkhealth window', function()
^ |
{14: }|
{14: } |
{h1:test_plug.success1: }|
{h1:require("test_plug.success1.health").check()} |
{h1:test_plug. }|
{h1:success1: }|
{h1: ✅} |
|
{h2:report 1} |
- ✅ {32:OK} everything is fine |
|
{h2:report 2} |
- ✅ {32:OK} nothing to see here |
## grid 3
|
]],
@@ -324,8 +349,8 @@ describe(':checkhealth window', function()
{14: } |
{h1:test_plug. }|
{h1:success1: }|
{h1:require("test_plug. }|
{h1:success1.health").check()}|
{h1: }|
{h1: ✅} |
|
{h2:report 1} |
- ✅ {32:OK} everything is |
@@ -383,15 +408,15 @@ describe(':checkhealth window', function()
^ |
|
|
test_plug.success1: |
require("test_plug.success1.health").check() |
test_plug. |
success1: |
✅ |
|
report 1 |
- ✅ OK everything is fine |
|
report 2 |
- ✅ OK nothing to see here |
|
]]):format(
top
and [[