mirror of
https://github.com/neovim/neovim.git
synced 2026-09-13 01:21:06 +00:00
4cad27fbcf
Problem: :checkhealth blocks as healthchecks perform slow work. Solution: Partially fix it: run Lua healthchecks in vim.async tasks and await vim.health subprocesses. Existing synchronous checks still block until they leverage the new apis.
577 lines
18 KiB
Lua
577 lines
18 KiB
Lua
--- @brief
|
|
---
|
|
--- 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
|
|
--- ```
|
|
--- Plugin authors are encouraged to write new healthchecks. |health-dev|
|
|
---
|
|
---<pre>help
|
|
--- COMMANDS *health-commands*
|
|
---
|
|
--- *:che* *:checkhealth*
|
|
--- :che[ckhealth] Run all healthchecks.
|
|
--- *E5009*
|
|
--- Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to
|
|
--- find the standard "runtime files" for syntax highlighting,
|
|
--- filetype-specific behavior, and standard plugins (including
|
|
--- :checkhealth). If the runtime files cannot be found then
|
|
--- those features will not work.
|
|
---
|
|
--- :che[ckhealth] {plugins}
|
|
--- Run healthcheck(s) for one or more plugins. E.g. to run only
|
|
--- the standard Nvim healthcheck: >vim
|
|
--- :checkhealth vim.health
|
|
--- <
|
|
--- To run the healthchecks for the "foo" and "bar" plugins
|
|
--- (assuming they are on 'runtimepath' and they have implemented
|
|
--- the Lua `require("foo.health").check()` interface): >vim
|
|
--- :checkhealth foo bar
|
|
--- <
|
|
--- To run healthchecks for Lua submodules, use dot notation or
|
|
--- "*" to refer to all submodules. For example Nvim provides
|
|
--- `vim.lsp` and `vim.treesitter`: >vim
|
|
--- :checkhealth vim.lsp vim.treesitter
|
|
--- :checkhealth vim*
|
|
--- <
|
|
---
|
|
--- USAGE *health-usage*
|
|
---
|
|
--- 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
|
|
--- a floating window instead of the default behavior.
|
|
---
|
|
--- 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
|
|
--- ```
|
|
--- Sometimes you might need to suppress filetype warnings if you have specified them dynamically.
|
|
--- For example with the yaml.ansible filetype:
|
|
--- ```vim
|
|
--- autocmd FileType checkhealth :set modifiable | silent! g/Unknown filetype 'yaml\.ansible'/d
|
|
--- ```
|
|
---<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...
|
|
---
|
|
--- 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
|
|
--- ```
|
|
|
|
local M = {}
|
|
local async = require('vim.async') --- @type vim.async._core
|
|
|
|
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)
|
|
path = vim.fs.abspath(vim.fs.normalize(path))
|
|
local name --- @type string
|
|
local func --- @type string
|
|
local filetype --- @type string
|
|
if path:find('vim$') then
|
|
name = vim.fs.basename(path):gsub('%.vim$', '')
|
|
func = 'health#' .. name .. '#check'
|
|
filetype = 'v'
|
|
else
|
|
local rtp_lua = vim
|
|
.iter(vim.api.nvim_get_runtime_file('lua/', true))
|
|
:map(function(dir)
|
|
return vim.fs.abspath(vim.fs.normalize(dir))
|
|
end)
|
|
:find(function(dir)
|
|
return vim.fs.relpath(dir, path)
|
|
end)
|
|
-- "/path/to/rtp/lua/foo/bar/health.lua" => "foo/bar/health.lua"
|
|
-- "/another/rtp/lua/baz/health/init.lua" => "baz/health/init.lua"
|
|
local subpath = path:gsub('^' .. vim.pesc(rtp_lua), ''):gsub('^/+', '')
|
|
if vim.fs.basename(subpath) == 'health.lua' then
|
|
-- */health.lua
|
|
name = vim.fs.dirname(subpath)
|
|
else
|
|
-- */health/init.lua
|
|
name = vim.fs.dirname(vim.fs.dirname(subpath))
|
|
end
|
|
name = assert(name:gsub('/', '.')) --[[@as string]]
|
|
|
|
func = 'require("' .. name .. '.health").check()'
|
|
filetype = 'l'
|
|
end
|
|
return { name, func, filetype }
|
|
end
|
|
|
|
--- @param plugin_names string
|
|
--- @return table<any,string[]> { {name, func, type}, ... } representing healthchecks
|
|
local function get_healthcheck_list(plugin_names)
|
|
local healthchecks = {} --- @type table<any,string[]>
|
|
local plugin_names_list = vim.split(plugin_names, ' ')
|
|
for _, p in pairs(plugin_names_list) do
|
|
-- support vim/lsp/health{/init/}.lua as :checkhealth vim.lsp
|
|
|
|
p = p:gsub('%.', '/')
|
|
p = p:gsub('*', '**')
|
|
|
|
local paths = vim.api.nvim_get_runtime_file('autoload/health/' .. p .. '.vim', true)
|
|
vim.list_extend(
|
|
paths,
|
|
vim.api.nvim_get_runtime_file('lua/**/' .. p .. '/health/init.lua', true)
|
|
)
|
|
vim.list_extend(paths, vim.api.nvim_get_runtime_file('lua/**/' .. p .. '/health.lua', true))
|
|
|
|
if vim.tbl_count(paths) == 0 then
|
|
healthchecks[#healthchecks + 1] = { p, '', '' } -- healthcheck not found
|
|
else
|
|
local unique_paths = {} --- @type table<string, boolean>
|
|
for _, v in pairs(paths) do
|
|
unique_paths[v] = true
|
|
end
|
|
paths = {}
|
|
for k, _ in pairs(unique_paths) do
|
|
paths[#paths + 1] = k
|
|
end
|
|
|
|
for _, v in ipairs(paths) do
|
|
healthchecks[#healthchecks + 1] = filepath_to_healthcheck(v)
|
|
end
|
|
end
|
|
end
|
|
return healthchecks
|
|
end
|
|
|
|
--- @param plugin_names string
|
|
--- @return table<string, string[]> {name: [func, type], ..} representing healthchecks
|
|
local function get_healthcheck(plugin_names)
|
|
local health_list = get_healthcheck_list(plugin_names)
|
|
local healthchecks = {} --- @type table<string, string[]>
|
|
for _, c in pairs(health_list) do
|
|
if c[1] ~= 'vim' then
|
|
healthchecks[c[1]] = { c[2], c[3] }
|
|
end
|
|
end
|
|
|
|
return healthchecks
|
|
end
|
|
|
|
--- Indents lines *except* line 1 of a multiline string.
|
|
---
|
|
--- @param s string
|
|
--- @param columns integer
|
|
--- @return string
|
|
local function indent_after_line1(s, columns)
|
|
return (vim.text.indent(columns, s):gsub('^%s+', ''))
|
|
end
|
|
|
|
--- Changes ':h clipboard' to ':help |clipboard|'.
|
|
---
|
|
--- @param s string
|
|
--- @return string
|
|
local function help_to_link(s)
|
|
return vim.fn.substitute(s, [[\v:h%[elp] ([^|][^"\r\n ]+)]], [[:help |\1|]], [[g]])
|
|
end
|
|
|
|
--- Format a message for a specific report item.
|
|
---
|
|
--- @param status string
|
|
--- @param msg string
|
|
--- @param ... string|string[] Optional advice
|
|
--- @return string
|
|
local function format_report_message(status, msg, ...)
|
|
local output = '- ' .. status
|
|
if status ~= '' then
|
|
output = output .. ' '
|
|
end
|
|
|
|
output = output .. indent_after_line1(msg, 2)
|
|
|
|
local varargs = ...
|
|
|
|
-- Optional parameters
|
|
if varargs then
|
|
if type(varargs) == 'string' then
|
|
varargs = { varargs }
|
|
end
|
|
|
|
output = output .. '\n - ADVICE:'
|
|
|
|
-- Report each suggestion
|
|
for _, v in ipairs(varargs) do
|
|
if v then
|
|
output = output .. '\n - ' .. indent_after_line1(v, 6) --- @type string
|
|
end
|
|
end
|
|
end
|
|
|
|
return help_to_link(output)
|
|
end
|
|
|
|
--- @param output string
|
|
local function collect_output(output)
|
|
vim.list_extend(s_output, vim.split(output, '\n'))
|
|
end
|
|
|
|
--- Starts a new report. Most plugins should call this only once, but if
|
|
--- you want different sections to appear in your report, call this once
|
|
--- per section.
|
|
---
|
|
--- @param name string
|
|
function M.start(name)
|
|
local input = string.format('\n%s ~', name)
|
|
collect_output(input)
|
|
end
|
|
|
|
--- Reports an informational message.
|
|
---
|
|
--- @param msg string
|
|
function M.info(msg)
|
|
local input = format_report_message('', msg)
|
|
collect_output(input)
|
|
end
|
|
|
|
--- Reports a "success" message.
|
|
---
|
|
--- @param msg string
|
|
function M.ok(msg)
|
|
local input = format_report_message('✅ OK', msg)
|
|
collect_output(input)
|
|
end
|
|
|
|
--- Reports a warning.
|
|
---
|
|
--- @param msg string
|
|
--- @param ... string|string[] Optional advice
|
|
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.
|
|
---
|
|
--- @param msg string
|
|
--- @param ... string|string[] Optional advice
|
|
function M.error(msg, ...)
|
|
local input = format_report_message('❌ ERROR', msg, ...)
|
|
collect_output(input)
|
|
check_summary['error'] = check_summary['error'] + 1
|
|
end
|
|
|
|
---@param path string
|
|
---@return string
|
|
local path2name = function(path)
|
|
if vim.fs.ext(path) == 'lua' then
|
|
-- Lua: transform "../lua/vim/lsp/health.lua" into "vim.lsp"
|
|
|
|
-- Get full path, make sure all slashes are '/'
|
|
path = vim.fs.normalize(path)
|
|
|
|
-- Remove everything up to the last /lua/ folder
|
|
path = path:gsub('^.*/lua/', '')
|
|
|
|
-- Remove the filename (health.lua) or (health/init.lua)
|
|
path = vim.fs.dirname(path:gsub('/init%.lua$', ''))
|
|
|
|
-- Change slashes to dots
|
|
path = path:gsub('/', '.')
|
|
|
|
return path
|
|
else
|
|
-- Vim: transform "../autoload/health/provider.vim" into "provider"
|
|
return vim.fn.fnamemodify(path, ':t:r')
|
|
end
|
|
end
|
|
|
|
local PATTERNS = { '/autoload/health/*.vim', '/lua/**/**/health.lua', '/lua/**/**/health/init.lua' }
|
|
--- :checkhealth completion function used by cmdexpand.c get_healthcheck_names()
|
|
M._complete = function()
|
|
---@type table<string,boolean>
|
|
local unique = vim
|
|
.iter(vim.tbl_map(function(pattern)
|
|
return vim.tbl_map(path2name, vim.api.nvim_get_runtime_file(pattern, true))
|
|
end, PATTERNS))
|
|
:flatten()
|
|
:fold({}, function(t, name)
|
|
t[name] = true -- Remove duplicates
|
|
return t
|
|
end)
|
|
-- vim.health is this file, which is not a healthcheck
|
|
unique['vim'] = nil
|
|
local rv = vim.tbl_keys(unique)
|
|
table.sort(rv)
|
|
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
|
|
|
|
---Emit progress messages
|
|
---@param len integer
|
|
---@return fun(status: 'success'|'running', idx: integer?, fmt: string, ...: any): nil
|
|
local function progress_report(len)
|
|
local progress = { kind = 'progress', source = 'vim.health', title = 'checkhealth' }
|
|
|
|
return function(status, idx, fmt, ...)
|
|
progress.status = status
|
|
local progress_percent = idx and math.floor(idx / len * 100) or nil
|
|
progress.percent = status == 'success' and nil or progress_percent
|
|
progress.id = vim.api.nvim_echo({ { fmt:format(...) } }, false, progress)
|
|
vim.cmd.redraw()
|
|
end
|
|
end
|
|
|
|
--- Runs the specified healthchecks, or all discovered healthchecks if eap.args is empty.
|
|
---
|
|
--- Specified healthchecks are given as plugin names, split on whitespace. For example using
|
|
--- `:checkhealth vim.* nvim` will check `vim.lsp`, `vim.treesitter` and `nvim` modules.
|
|
---
|
|
--- @param eap vim._core.ExCmdArgs
|
|
function M._check(eap)
|
|
local plugin_names = eap.args
|
|
local smods = eap.smods
|
|
local healthchecks = plugin_names == '' and get_healthcheck('*') or get_healthcheck(plugin_names)
|
|
|
|
local emptybuf = vim.fn.bufnr('$') == 1 and vim.fn.getline(1) == '' and 1 == vim.fn.line('$')
|
|
|
|
local bufnr ---@type integer
|
|
if vim.tbl_get(vim.g, 'health', 'style') == 'float' then
|
|
local available_lines = vim.o.lines - 12
|
|
local max_height = math.min(math.floor(vim.o.lines * 0.8), available_lines)
|
|
local max_width = 80
|
|
local float_winid
|
|
bufnr, float_winid = vim.lsp.util.open_floating_preview({}, '', {
|
|
height = max_height,
|
|
width = max_width,
|
|
offset_x = math.floor((vim.o.columns - max_width) / 2),
|
|
offset_y = math.floor((available_lines - max_height) / 2),
|
|
relative = 'editor',
|
|
close_events = {},
|
|
})
|
|
vim.api.nvim_set_current_win(float_winid)
|
|
vim.wo[float_winid].list = false
|
|
else
|
|
bufnr = vim.api.nvim_create_buf(true, true)
|
|
-- When no command modifiers are used:
|
|
-- - If the current buffer is empty, open healthcheck directly.
|
|
-- - If not specified otherwise open healthcheck in a tab.
|
|
local has_mods = smods.tab > 0 or smods.split ~= '' or smods.horizontal or smods.vertical
|
|
if has_mods then
|
|
vim.cmd.sbuffer { bufnr, mods = smods }
|
|
elseif emptybuf then
|
|
vim.cmd.buffer(bufnr)
|
|
else
|
|
vim.cmd.sbuffer { bufnr, mods = { tab = vim.api.nvim_tabpage_get_number(0) } }
|
|
end
|
|
end
|
|
vim.bo[bufnr].modifiable = true
|
|
|
|
if vim.fn.bufexists('health://') == 1 then
|
|
vim.cmd.bwipe('health://')
|
|
end
|
|
vim.cmd.file('health://')
|
|
|
|
-- This should only happen when doing `:checkhealth vim`
|
|
if next(healthchecks) == nil then
|
|
vim.fn.setline(1, 'ERROR: No healthchecks found.')
|
|
return
|
|
end
|
|
|
|
-- Show nvim-owned first (`vim.*`, `runtime/lua/vim/**/health.lua`).
|
|
local names = vim.tbl_keys(healthchecks) --- @type string[]
|
|
table.sort(names, function(a, b)
|
|
local a_nvim = vim.startswith(a, 'vim.')
|
|
local b_nvim = vim.startswith(b, 'vim.')
|
|
if a_nvim ~= b_nvim then
|
|
return a_nvim
|
|
end
|
|
return a < b
|
|
end)
|
|
|
|
local task --- @type vim.async.Task<nil>
|
|
|
|
-- Quit with 'q' inside healthcheck buffers.
|
|
vim._with({ buf = bufnr }, function()
|
|
if
|
|
vim.tbl_get(vim.g, 'health', 'style') == 'float'
|
|
or vim.fn.maparg('q', 'n', false, false) == ''
|
|
then
|
|
vim.keymap.set('n', 'q', function()
|
|
task:close()
|
|
if not pcall(vim.cmd.close) then
|
|
vim.cmd.bdelete()
|
|
end
|
|
end, { buf = bufnr, silent = true, noremap = true, nowait = true })
|
|
end
|
|
end)
|
|
|
|
task = async.run('checkhealth', function()
|
|
local total_checks = #names
|
|
local progress_msg = progress_report(total_checks)
|
|
local check_idx = 1
|
|
for _, name in ipairs(names) do
|
|
local value = healthchecks[name]
|
|
progress_msg('running', check_idx, 'checking %s', name)
|
|
local func = value[1]
|
|
local type = value[2]
|
|
s_output = {}
|
|
check_summary = { warn = 0, error = 0 }
|
|
|
|
if func == '' then
|
|
M.error('No healthcheck found for "' .. name .. '" plugin.')
|
|
end
|
|
if type == 'v' then
|
|
vim.fn.call(func, {})
|
|
else
|
|
local f = assert(loadstring(func))
|
|
--- @diagnostic disable-next-line: assign-type-mismatch
|
|
local ok, output = async.pawait(async.run(name, f)) ---@type boolean, string
|
|
async.await(vim.schedule)
|
|
if not ok then
|
|
M.error(
|
|
string.format(
|
|
'Failed to run healthcheck for "%s" plugin. Exception:\n%s\n',
|
|
name,
|
|
output
|
|
)
|
|
)
|
|
end
|
|
end
|
|
-- in the event the healthcheck doesn't return anything
|
|
-- (the plugin author should avoid this possibility)
|
|
if next(s_output) == nil then
|
|
s_output = {}
|
|
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: [ …] 1 ⚠️ 5 ❌`
|
|
('%s: %s%s'):format(name, (' '):rep(76 - name:len() - replen), report),
|
|
'',
|
|
}
|
|
|
|
-- remove empty line after header from report_start
|
|
if s_output[1] == '' then
|
|
local tmp = {} ---@type string[]
|
|
for i = 2, #s_output do
|
|
tmp[#tmp + 1] = s_output[i]
|
|
end
|
|
s_output = {}
|
|
for _, v in ipairs(tmp) do
|
|
s_output[#s_output + 1] = v
|
|
end
|
|
end
|
|
s_output[#s_output + 1] = ''
|
|
s_output = vim.list_extend(header, s_output)
|
|
|
|
if not vim.api.nvim_buf_is_valid(bufnr) then
|
|
return
|
|
end
|
|
vim.api.nvim_buf_set_lines(bufnr, check_idx == 1 and 0 or -1, -1, true, s_output)
|
|
|
|
check_idx = check_idx + 1
|
|
end
|
|
|
|
progress_msg('success', nil, 'checks done')
|
|
|
|
if not vim.api.nvim_buf_is_valid(bufnr) then
|
|
return
|
|
end
|
|
-- Once we're done writing checks, set nomodifiable.
|
|
vim.bo[bufnr].modifiable = false
|
|
vim._with({ buf = bufnr }, function()
|
|
vim.cmd.setfiletype('checkhealth')
|
|
end)
|
|
end)
|
|
|
|
local cancel_autocmd = vim.api.nvim_create_autocmd('BufUnload', {
|
|
buffer = bufnr,
|
|
once = true,
|
|
callback = function()
|
|
task:close()
|
|
end,
|
|
})
|
|
task:on_complete(function(err)
|
|
pcall(vim.api.nvim_del_autocmd, cancel_autocmd)
|
|
if err and err ~= 'closed' then
|
|
error(task:traceback(err), 0)
|
|
end
|
|
end)
|
|
end
|
|
|
|
return M
|