ref: workspace diagnostics

lua/libmodal/init.lua

@@ -5,8 +5,8 @@ return setmetatable(
 		{
 			--- enter a new layer.
 			--- @param keymap table the keymaps (e.g. `{n = {gg = {rhs = 'G', silent = true}}}`)
-			--- @param exit_char nil|string a character which can be used to exit the layer from normal mode.
-			--- @return function|nil exit a function to exit the layer, or `nil` if `exit_char` is passed
+			--- @param exit_char? string a character which can be used to exit the layer from normal mode.
+			--- @return fun()|nil exit a function to exit the layer, or `nil` if `exit_char` is passed
 			enter = function(keymap, exit_char)
 				local layer = require('libmodal/src/Layer').new(keymap)
 				layer:enter()
@@ -30,7 +30,7 @@ return setmetatable(
 		{
 			--- enter a mode.
 			--- @param name string the name of the mode.
-			--- @param instruction function|string|table a Lua function, keymap dictionary, Vimscript command.
+			--- @param instruction fun()|string|table a Lua function, keymap dictionary, Vimscript command.
 			enter = function(name, instruction, supress_exit)
 				require('libmodal/src/Mode').new(name, instruction, supress_exit):enter()
 			end
@@ -40,8 +40,8 @@ return setmetatable(
 		{
 			--- enter a prompt.
 			--- @param name string the name of the prompt
-			--- @param instruction function|table<string, function|string> what to do with user input
-			--- @param user_completions table<string>|nil a list of possible inputs, provided by the user
+			--- @param instruction fun()|{[string]: fun()|string} what to do with user input
+			--- @param user_completions? string[] a list of possible inputs, provided by the user
 			enter = function(name, instruction, user_completions)
 				require('libmodal/src/Prompt').new(name, instruction, user_completions):enter()
 			end

lua/libmodal/src/Layer.lua

@@ -11,6 +11,7 @@ local function normalize_buffer(buffer)
 		return nil
 	end
 
+	--- @diagnostic disable-next-line:return-type-mismatch `true` and `false are already checked
 	return buffer
 end
 
@@ -42,7 +43,7 @@ end
 
 --- remove and return the right-hand side of a `keymap`.
 --- @param keymap table the keymap to unpack
---- @return function|string rhs, table options
+--- @return fun()|string rhs, table options
 local function unpack_keymap_rhs(keymap)
 	local rhs = keymap.rhs
 	keymap.rhs = nil
@@ -106,9 +107,9 @@ end
 --- add a keymap to the mode.
 --- @param mode string the mode that this keymap for.
 --- @param lhs string the left hand side of the keymap.
---- @param rhs function|string the right hand side of the keymap.
+--- @param rhs fun()|string the right hand side of the keymap.
 --- @param options table options for the keymap.
---- @see `vim.keymap.set`
+--- @see vim.keymap.set
 function Layer:map(mode, lhs, rhs, options)
 	lhs = utils.api.replace_termcodes(lhs)
 	options.buffer = normalize_buffer(options.buffer)
@@ -143,10 +144,10 @@ function Layer:map(mode, lhs, rhs, options)
 end
 
 --- restore one keymapping to its original state.
---- @param buffer nil|number the buffer to unmap from (`nil` if it is not buffer-local)
+--- @param buffer? number the buffer to unmap from (`nil` if it is not buffer-local)
 --- @param mode string the mode of the keymap.
 --- @param lhs string the keys which invoke the keymap.
---- @see `vim.api.nvim_del_keymap`
+--- @see vim.api.nvim_del_keymap
 function Layer:unmap(buffer, mode, lhs)
 	lhs = utils.api.replace_termcodes(lhs)
 	if self.existing_keymaps_by_mode then
@@ -155,7 +156,7 @@ function Layer:unmap(buffer, mode, lhs)
 			-- WARN: nvim can fail to restore the original keybinding here unless schedule
 			vim.schedule(function() vim.keymap.set(mode, lhs, rhs, options) end)
 		else -- there was no older keymap; just delete the one set by this layer
-			local no_errors, err = pcall(function()
+			local ok, err = pcall(function()
 				if buffer then
 					vim.api.nvim_buf_del_keymap(buffer, mode, lhs)
 				else
@@ -163,7 +164,7 @@ function Layer:unmap(buffer, mode, lhs)
 				end
 			end)
 
-			if not (no_errors or err:match 'E31: No such mapping') then
+			if not ok and err:match 'E31: No such mapping' then
 				require('libmodal/src/utils').notify_error('nvim-libmodal encountered an error while unmapping from layer', err)
 				return
 			end

lua/libmodal/src/Mode.lua

@@ -5,10 +5,10 @@ local utils      = require 'libmodal/src/utils'
 --- @class libmodal.Mode
 --- @field private exit libmodal.utils.Vars
 --- @field private flush_input_timer unknown
---- @field private help libmodal.utils.Help|nil
+--- @field private help? libmodal.utils.Help
 --- @field private indicator libmodal.utils.Indicator
 --- @field private input libmodal.utils.Vars
---- @field private instruction function|table<string, function|string>
+--- @field private instruction fun()|{[string]: fun()|string}
 --- @field private mappings libmodal.collections.ParseTable
 --- @field private name string
 --- @field private popups libmodal.collections.Stack
@@ -35,7 +35,7 @@ local TIMEOUT =
 TIMEOUT.CHAR_NUMBER = string.byte(TIMEOUT.CHAR)
 
 --- execute the `instruction`.
---- @param instruction function|string a Lua function or Vimscript command.
+--- @param instruction fun()|string a Lua function or Vimscript command.
 function Mode.execute_instruction(instruction)
 	if type(instruction) == globals.TYPE_FUNC then
 		instruction()
@@ -106,10 +106,10 @@ function Mode:enter()
 	local continue_mode = true
 	while continue_mode do
 		-- try (using pcall) to use the mode.
-		local no_errors, mode_result = pcall(self.get_user_input, self)
+		local ok, mode_result = pcall(self.get_user_input, self)
 
 		-- if there were errors, handle them.
-		if not no_errors then
+		if not ok then
 			utils.notify_error('Error during nvim-libmodal mode', mode_result)
 			continue_mode = false
 		else
@@ -185,7 +185,7 @@ return
 {
 	--- create a new mode.
 	--- @param name string the name of the mode.
-	--- @param instruction function|string|table a Lua function, keymap dictionary, Vimscript command.
+	--- @param instruction fun()|string|table a Lua function, keymap dictionary, Vimscript command.
 	--- @return libmodal.Mode
 	new = function(name, instruction, supress_exit)
 		name = vim.trim(name)

lua/libmodal/src/Prompt.lua

@@ -2,12 +2,12 @@ local globals = require 'libmodal/src/globals'
 local utils = require 'libmodal/src/utils'
 
 --- @class libmodal.Prompt
---- @field private completions table<string>|nil
+--- @field private completions? string[]
 --- @field private exit libmodal.utils.Vars
---- @field private help libmodal.utils.Help|nil
+--- @field private help? libmodal.utils.Help
 --- @field private indicator libmodal.utils.Indicator
 --- @field private input libmodal.utils.Vars
---- @field private instruction function|table<string, function|string>
+--- @field private instruction fun()|{[string]: fun()|string}
 --- @field private name string
 local Prompt = utils.classes.new(nil)
 
@@ -91,10 +91,10 @@ function Prompt:enter()
 	-- enter the mode using a loop.
 	local continue_mode = true
 	while continue_mode do
-		local no_errors, prompt_result = pcall(self.get_user_input, self)
+		local ok, prompt_result = pcall(self.get_user_input, self)
 
 		-- if there were errors.
-		if not no_errors then
+		if not ok then
 			utils.notify_error('Error during nvim-libmodal mode', prompt_result)
 			continue_mode = false
 		else
@@ -107,8 +107,8 @@ return
 {
 	--- enter a prompt.
 	--- @param name string the name of the prompt
-	--- @param instruction function|table<string, function|string> what to do with user input
-	--- @param user_completions table<string>|nil a list of possible inputs, provided by the user
+	--- @param instruction fun()|{[string]: fun()|string} what to do with user input
+	--- @param user_completions? string[] a list of possible inputs, provided by the user
 	--- @return libmodal.Prompt
 	new = function(name, instruction, user_completions)
 		name = vim.trim(name)
@@ -130,6 +130,7 @@ return
 			local completions   = {}
 			local contained_help = false
 
+			--- @diagnostic disable-next-line:param-type-mismatch we check `instruction` is `table`
 			for command, _ in pairs(instruction) do
 				completions[#completions + 1] = command
 				if command == HELP then

lua/libmodal/src/collections/ParseTable.lua

@@ -18,15 +18,15 @@ local function table_reverse(tbl)
 end
 
 --- @param str string
---- @return table<string> chars of `str`
+--- @return string[] chars of `str`
 local function chars(str)
 	return vim.split(str, '')
 end
 
 --- retrieve the mapping of `lhs_reversed_bytes`
 --- @param parse_table libmodal.collections.ParseTable the table to fetch `lhs_reversed_bytes` from.
---- @param lhs_reversed_bytes table<string> the characters of the left-hand side of the mapping reversed passed to `string.byte`
---- @return false|function|string|table match a string/func when fully matched; a table when partially matched; false when no match.
+--- @param lhs_reversed_bytes string[] the characters of the left-hand side of the mapping reversed passed to `string.byte`
+--- @return false|fun()|nil|string|table match a string/func when fully matched; a table when partially matched; false when no match.
 local function get(parse_table, lhs_reversed_bytes)
 	--[[ Get the next character in the keymap string. ]]
 
@@ -54,12 +54,13 @@ local function get(parse_table, lhs_reversed_bytes)
 			return val
 		end
 	end
+
 	return nil
 end
 
 --- insert a `value` into `parse_table` at the position indicated by `lhs_reversed_bytes`
---- @param lhs_reversed_bytes table<string> the characters of the left-hand side of the mapping reversed passed to `string.byte`
---- @param value function|string the right-hand-side of the mapping
+--- @param lhs_reversed_bytes string[] the characters of the left-hand side of the mapping reversed passed to `string.byte`
+--- @param value fun()|string the right-hand-side of the mapping
 local function put(parse_table, lhs_reversed_bytes, value)
 	--[[ Get the next character in the table. ]]
 	local byte = string.byte(table.remove(lhs_reversed_bytes))
@@ -87,15 +88,16 @@ end
 
 --- retrieve the mapping of `lhs_reversed_bytes`
 --- @param key_dict table a list of characters (most recent input first)
---- @return false|function|string|table match a string/func when fully matched; a table when partially matched; false when no match.
+--- @return false|fun()|nil|string|table match a string/func when fully matched; a table when partially matched; false when no match.
 function ParseTable:get(key_dict)
 	return get(self, table_reverse(key_dict))
 end
 
 --- parse `key` and retrieve its value
 --- @param key string the left-hand-side of the mapping to retrieve
---- @return false|function|string|table match a string/func when fully found; a table when partially found; false when not found.
+--- @return false|fun()|nil|string|table match a string/func when fully found; a table when partially found; false when not found.
 function ParseTable:parse_get(key)
+	--- @type table<number|string>
 	local parsed_table = chars(string.reverse(key))
 
 	-- convert all of the strings to bytes.
@@ -108,13 +110,13 @@ end
 
 --- parse `key` and assign it to `value`.
 --- @param key string the left-hand-side of the mapping
---- @param value function|string the right-hand-side of the mapping
+--- @param value fun()|string the right-hand-side of the mapping
 function ParseTable:parse_put(key, value)
 	put(self, chars(string.reverse(key)), value)
 end
 
 --- `:parse_put` all `{key, value}` pairs in `keys_and_values`.
---- @param keys_and_values table<string, function|string>
+--- @param keys_and_values {[string]: fun()|string}
 function ParseTable:parse_put_all(keys_and_values)
 	for k, v in pairs(keys_and_values) do
 		self:parse_put(k, v)

lua/libmodal/src/utils/Help.lua

@@ -40,7 +40,7 @@ end
 return
 {
 	--- create a default help table with `commands_or_maps` and vim expressions.
-	--- @param commands_or_maps table<string, function|string> commands or mappings to vim expressions.
+	--- @param commands_or_maps {[string]: fun()|string} commands or mappings to vim expressions.
 	--- @param title string
 	--- @return libmodal.utils.Help
 	new = function(commands_or_maps, title)
@@ -53,19 +53,12 @@ return
 			end
 		end
 
-		-- define the separator for the help table.
-		local help_separator = {}
-		for i = 1, string.len(title) do
-			help_separator[i] = '-'
-		end
-		help_separator = table.concat(help_separator)
-
 		-- create a new `Help`.
 		return setmetatable(
 			{
 				[1] = ' ',
 				[2] = table.concat(align_columns({[title] = 'VIM EXPRESSION'}, longest_key_maps)),
-				[3] = table.concat(align_columns({[help_separator] = '--------------'}, longest_key_maps)),
+				[3] = table.concat(align_columns({[string.rep('-', string.len(title))] = '--------------'}, longest_key_maps)),
 				[4] = table.concat(align_columns(commands_or_maps, longest_key_maps)),
 			},
 			Help

lua/libmodal/src/utils/Popup.lua

@@ -1,6 +1,6 @@
 --- @class libmodal.utils.Popup
 --- @field private buffer number the number of the window which this popup is rendered on.
---- @field private input_chars table<string> the characters input by the user.
+--- @field private input_chars string[] the characters input by the user.
 --- @field private window number the number of the window which this popup is rendered on.
 local Popup = require('libmodal/src/utils/classes').new(nil)
 
@@ -51,7 +51,7 @@ function Popup:open(config)
 end
 
 --- display `input_bytes` in `self.buffer`
---- @param input_bytes table<number> a list of character codes to display
+--- @param input_bytes number[] a list of character codes to display
 function Popup:refresh(input_bytes)
 	-- the user simply typed one more character onto the last one.
 	if #input_bytes == #self.input_chars + 1 then

lua/libmodal/src/utils/api.lua

@@ -4,7 +4,7 @@ local globals = require 'libmodal/src/globals'
 local api = {}
 
 --- echo a list of `Indicator`s with their associated highlighting.
---- @param indicators libmodal.utils.Indicator|table<libmodal.utils.Indicator> the indicators to echo
+--- @param indicators libmodal.utils.Indicator|libmodal.utils.Indicator[] the indicators to echo
 function api.hi_echo(indicators)
 	if indicators.hl then -- wrap the single indicator in a table to form a list of indicators
 		indicators = {indicators}
@@ -20,12 +20,16 @@ function api.hi_echo(indicators)
 end
 
 --- send a character to exit a mode.
---- @param exit_char string the character used to exit the mode, or ESCAPE if none was provided.
+--- @param exit_char? number|string the character used to exit the mode, or ESCAPE if none was provided.
 function api.mode_exit(exit_char)
 	-- if there was no provided `exit_char`, or it is a character code.
-	if not exit_char or type(exit_char) == globals.TYPE_NUM then
+	if type(exit_char) == globals.TYPE_NUM then
 		-- translate the character code or default to escape.
-		exit_char = string.char(exit_char or globals.ESC_NR)
+		--- @diagnostic disable-next-line:param-type-mismatch we just checked `exit_char` == `number`
+		exit_char = string.char(exit_char)
+	elseif not exit_char then
+		-- translate the character code or default to escape.
+		exit_char = string.char(globals.ESC_NR)
 	end
 
 	-- exit the prompt by sending an escape key.

lua/libmodal/src/utils/classes.lua

@@ -2,7 +2,7 @@
 return
 {
 	--- define a metatable.
-	--- @param template nil|table the default value
+	--- @param template? table the default value
 	new = function(template)
 		-- set self to `template`, or `{}` if nil.
 		local self = template or {}