chore: add annotations to resolve unknown types

MeanderingProgrammer · MeanderingProgrammer · commit 9e51b7711c61 · 2025-07-28T12:14:19.000-07:00
diff --git a/doc/render-markdown.txt b/doc/render-markdown.txt
@@ -1,4 +1,4 @@
-*render-markdown.txt*        For NVIM v0.11.3        Last change: 2025 July 23
+*render-markdown.txt*        For NVIM v0.11.3        Last change: 2025 July 28
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
diff --git a/lua/render-markdown/core/command.lua b/lua/render-markdown/core/command.lua
@@ -21,6 +21,9 @@ function M.init()
     vim.api.nvim_create_user_command(M.name, M.command, {
         nargs = '*',
         desc = M.plugin .. ' commands',
+        ---@param cmdline string
+        ---@param col integer
+        ---@return string[]
         complete = function(_, cmdline, col)
             local line = cmdline:sub(1, col):match('^' .. M.name .. '%s+(.*)$')
             if line then
@@ -44,7 +47,7 @@ end
 ---@param values string[]
 ---@return string[]
 function M.matches(prefix, values)
-    local result = {}
+    local result = {} ---@type string[]
     for _, value in ipairs(values) do
         if vim.startswith(value, prefix) then
             result[#result + 1] = value
@@ -70,7 +73,7 @@ function M.run(fargs)
         return ('invalid # arguments - %d'):format(#fargs)
     end
     local name = fargs[1] or 'enable'
-    local command = api[name]
+    local command = api[name] --[[@as fun(enable?: boolean)?]]
     if not command then
         return ('invalid command - %s'):format(name)
     end
diff --git a/lua/render-markdown/core/log.lua b/lua/render-markdown/core/log.lua
@@ -125,7 +125,7 @@ function M.add(level, name, ...)
     if M.level(level) < M.level(M.config.level) then
         return
     end
-    local messages = {}
+    local messages = {} ---@type string[]
     for i = 1, select('#', ...) do
         local value = select(i, ...)
         local message = type(value) == 'string' and value or vim.inspect(value)
diff --git a/lua/render-markdown/core/ts.lua b/lua/render-markdown/core/ts.lua
@@ -62,11 +62,10 @@ function M.inject(language)
     else
         local files = vim.treesitter.query.get_files(language, 'injections')
         for _, file in ipairs(files) do
-            local f = io.open(file, 'r')
-            if f then
-                query = query .. f:read('*all') .. '\n'
-                f:close()
-            end
+            local f = assert(io.open(file, 'r'))
+            local body = f:read('*a') --[[@as string]]
+            f:close()
+            query = query .. body .. '\n'
         end
     end
     query = query .. injection.query
diff --git a/lua/render-markdown/debug/diff.lua b/lua/render-markdown/debug/diff.lua
@@ -7,15 +7,15 @@ local M = {}
 ---@param t2 table<render.md.debug.Key, any>
 ---@return table<render.md.debug.Key, any>?
 function M.get(t1, t2)
-    local keys = vim.tbl_keys(t1)
+    local keys = vim.tbl_keys(t1) ---@type render.md.debug.Key[]
     for key in pairs(t2) do
         if not vim.tbl_contains(keys, key) then
             keys[#keys + 1] = key
         end
     end
-    local result = {}
+    local result = {} ---@type table<render.md.debug.Key, any>
     for _, key in ipairs(keys) do
-        local difference
+        local difference ---@type any
         local v1, v2 = t1[key], t2[key]
         if type(v1) == 'table' and type(v2) == 'table' then
             difference = M.get(v1, v2)
diff --git a/lua/render-markdown/debug/marks.lua b/lua/render-markdown/debug/marks.lua
@@ -55,7 +55,7 @@ end
 
 ---@return string
 function Mark:__tostring()
-    local lines = {}
+    local lines = {} ---@type string[]
     lines[#lines + 1] = ('='):rep(vim.o.columns - 1)
     lines[#lines + 1] = ('row: %s'):format(Mark.collapse(self.row))
     lines[#lines + 1] = ('column: %s'):format(Mark.collapse(self.col))
@@ -64,7 +64,7 @@ function Mark:__tostring()
     ---@param name string
     ---@param f fun(value: any): string
     local function add(name, f)
-        local value = self.opts[name]
+        local value = self.opts[name] ---@type any
         if value ~= nil then
             lines[#lines + 1] = ('  %s: %s'):format(name, f(value))
         end
@@ -106,7 +106,7 @@ end
 ---@param line render.md.mark.Line
 ---@return string
 function Mark.line(line)
-    local result = {}
+    local result = {} ---@type string[]
     for _, text in ipairs(line) do
         result[#result + 1] = ('(%s, %s)'):format(
             Mark.text(text[1]),
@@ -120,7 +120,7 @@ end
 ---@param text string
 ---@return string
 function Mark.text(text)
-    local chars = vim.fn.str2list(text)
+    local chars = vim.fn.str2list(text) ---@type integer[]
     local first, same = chars[1], true
     for _, char in ipairs(chars) do
         same = same and (first == char)
diff --git a/lua/render-markdown/debug/validator.lua b/lua/render-markdown/debug/validator.lua
@@ -93,6 +93,7 @@ function Spec:list(keys, t, ts)
         if vim.tbl_contains(types, type(value)) then
             return true
         elseif type(value) == 'table' then
+            ---@cast value any[]
             for i, item in ipairs(value) do
                 if type(item) ~= t then
                     return false, ('[%d] is %s'):format(i, type(item))
@@ -114,8 +115,10 @@ function Spec:nested_list(keys, t, ts)
         if type(value) == t or vim.tbl_contains(types, type(value)) then
             return true
         elseif type(value) == 'table' then
+            ---@cast value any[]
             for i, item in ipairs(value) do
                 if type(item) == 'table' then
+                    ---@cast item any[]
                     for j, nested in ipairs(item) do
                         if type(nested) ~= t then
                             local info = ('[%d][%d] is %s'):format(
@@ -150,6 +153,7 @@ function Spec:one_or_list_of(keys, values, ts)
         elseif type(value) ~= 'table' then
             return vim.tbl_contains(values, value)
         else
+            ---@cast value any[]
             for i, item in ipairs(value) do
                 if not vim.tbl_contains(values, item) then
                     return false, ('[%d] is %s'):format(i, item)
@@ -165,7 +169,7 @@ end
 ---@param ts? type|type[]
 ---@return type[], string
 function Spec:handle_types(custom, ts)
-    local types
+    local types ---@type type[]
     if not ts then
         types = {}
     elseif type(ts) == 'string' then
@@ -186,7 +190,7 @@ end
 ---@param validation fun(v: any): boolean, string?
 function Spec:add(keys, kind, message, validation)
     if self.config then
-        keys = type(keys) == 'table' and keys or { keys }
+        keys = type(keys) == 'table' and keys or { keys } ---@type string[]
         for _, key in ipairs(keys) do
             self.specs[key] = {
                 kind = kind,
@@ -223,12 +227,12 @@ Validator.spec = Spec.new
 ---@param specs table<string, render.md.debug.Spec>
 function Validator:check(path, config, specs)
     for key, spec in pairs(specs) do
-        local root = vim.list_extend({}, path)
+        local root = vim.list_extend({}, path) ---@type string[]
         root[#root + 1] = tostring(key)
         local value = config[key]
         local ok, info = spec.validation(value)
         if not ok then
-            local actual
+            local actual ---@type string
             if spec.kind == Kind.data then
                 actual = vim.inspect(value)
             elseif spec.kind == Kind.type then
@@ -245,7 +249,7 @@ function Validator:check(path, config, specs)
         end
     end
     for key in pairs(config) do
-        local root = vim.list_extend({}, path)
+        local root = vim.list_extend({}, path) ---@type string[]
         root[#root + 1] = tostring(key)
         if not specs[key] then
             local message = ('%s - invalid key'):format(table.concat(root, '.'))
diff --git a/lua/render-markdown/handler/latex.lua b/lua/render-markdown/handler/latex.lua
@@ -41,7 +41,7 @@ function Handler:run(root)
 
     local indent = self:indent(node.start_row, node.start_col)
     local lines = iter.list.map(self:expressions(node), function(expression)
-        local line = vim.list_extend({}, indent)
+        local line = vim.list_extend({}, indent) ---@type render.md.mark.Line
         line[#line + 1] = { expression, self.config.highlight }
         return line
     end)
diff --git a/lua/render-markdown/health.lua b/lua/render-markdown/health.lua
@@ -5,7 +5,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '8.6.8'
+M.version = '8.6.9'
 
 function M.check()
     M.start('version')
@@ -153,7 +153,7 @@ end
 ---@param name string
 ---@param validate? fun(plugin: any): string[]?
 function M.plugin(name, validate)
-    local has_plugin, plugin = pcall(require, name)
+    local has_plugin, plugin = pcall(require, name) ---@type boolean, any
     if not has_plugin then
         vim.health.ok(name .. ': not installed')
     elseif not validate then
diff --git a/lua/render-markdown/lib/compat.lua b/lua/render-markdown/lib/compat.lua
@@ -21,7 +21,7 @@ function M.fix_lsp_window(buf, win, extmarks)
     local str = require('render-markdown.lib.str')
 
     -- account for conceal lines marks allowing us to reduce window height
-    local height = vim.api.nvim_win_text_height(win, {}).all
+    local height = vim.api.nvim_win_text_height(win, {}).all ---@type integer
     for _, extmark in ipairs(extmarks) do
         if extmark:get().opts.conceal_lines then
             height = height - 1
diff --git a/lua/render-markdown/lib/config.lua b/lua/render-markdown/lib/config.lua
@@ -42,7 +42,7 @@ function Config.new(root, enabled, buf)
     config = vim.deepcopy(config)
     for _, name in ipairs({ 'buflisted', 'buftype', 'filetype' }) do
         local value = env.buf.get(buf, name)
-        local override = root.overrides[name][value]
+        local override = root.overrides[name][value] ---@type render.md.partial.UserConfig?
         if override then
             config = vim.tbl_deep_extend('force', config, override)
         end
diff --git a/lua/render-markdown/lib/converter.lua b/lua/render-markdown/lib/converter.lua
@@ -76,7 +76,7 @@ M.superscripts = {
 ---@param s string
 ---@return string?
 function M.superscript(s)
-    local chars = {}
+    local chars = {} ---@type string[]
     for char in s:gmatch('.') do
         char = M.superscripts[char]
         if not char then
diff --git a/lua/render-markdown/lib/node.lua b/lua/render-markdown/lib/node.lua
@@ -214,7 +214,7 @@ end
 ---@param by integer
 ---@return integer, string?
 function Node:line(position, by)
-    local row
+    local row ---@type integer
     local single = self.start_row == self.end_row
     if position == Position.above then
         row = self.start_row - by
diff --git a/lua/render-markdown/render/markdown/heading.lua b/lua/render-markdown/render/markdown/heading.lua
@@ -40,7 +40,9 @@ function Render:setup()
     if self.context.conceal:hidden(self.node) then
         return false
     end
-    local atx, marker, level
+    local atx ---@type boolean
+    local marker ---@type render.md.Node
+    local level ---@type integer
     if self.node.type == 'atx_heading' and self.config.atx then
         atx = true
         marker = assert(self.node:child_at(0), 'atx heading missing marker')
diff --git a/tests/custom_handler_spec.lua b/tests/custom_handler_spec.lua
@@ -5,7 +5,7 @@ local util = require('tests.util')
 ---@param ctx render.md.handler.Context
 ---@return render.md.Mark[]
 local function conceal_escape(ctx)
-    local marks = {}
+    local marks = {} ---@type render.md.Mark[]
     local query = vim.treesitter.query.parse(
         'markdown_inline',
         '(backslash_escape) @escape'
diff --git a/tests/helpers/details.lua b/tests/helpers/details.lua
@@ -90,11 +90,11 @@ function MarkDetails:priorities()
     local win_col = self.virt_text_win_col or 0
     local width = 0
     for _, text in ipairs(self.virt_text or {}) do
-        width = width + #text[1]
+        width = width + #text[1] ---@type number
     end
     for _, line in ipairs(self.virt_lines or {}) do
         for _, text in ipairs(line) do
-            width = width + #text[1]
+            width = width + #text[1] ---@type number
         end
     end
     ---@type number[]
diff --git a/tests/util.lua b/tests/util.lua
@@ -74,7 +74,7 @@ end
 ---@param kind 'code'|'inline'|'link'
 ---@return vim.api.keyset.set_extmark
 function M.highlight(kind)
-    local highlight
+    local highlight ---@type string
     if kind == 'code' then
         highlight = 'RmCodeInline'
     elseif kind == 'inline' then
@@ -185,7 +185,7 @@ end
 ---@param lengths integer[]
 ---@return render.md.mark.Line
 function M.indent.line(lengths)
-    local result = {}
+    local result = {} ---@type render.md.mark.Line
     for _, length in ipairs(lengths) do
         if length == 1 then
             result[#result + 1] = { '▎', 'RmIndent' }
@@ -254,7 +254,7 @@ function M.code.border(border, full, ...)
     local parts = { ... }
     parts[#parts + 1] = full and vim.o.columns or nil
 
-    local line = {}
+    local line = {} ---@type render.md.mark.Line
     for _, part in ipairs(parts) do
         if type(part) == 'string' then
             local icon = M.code.icon(part)
@@ -427,7 +427,8 @@ function M.actual_marks()
     })
     local actual = {} ---@type render.md.test.MarkDetails[]
     for _, mark in ipairs(marks) do
-        local _, row, col, details = unpack(mark)
+        local row, col = mark[2], mark[3]
+        local details = assert(mark[4], 'missing details')
         local info = require('tests.helpers.details').new(row, col, details)
         actual[#actual + 1] = info
     end
@@ -446,7 +447,7 @@ end
 function M.actual_screen()
     vim.cmd('redraw')
 
-    local actual = {}
+    local actual = {} ---@type string[]
     for row = 1, vim.o.lines do
         local line = ''
         for col = 1, vim.o.columns do

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-render-markdown.txt For NVIM v0.11.3 Last change: 2025 July 23`
	`1`	`+render-markdown.txt For NVIM v0.11.3 Last change: 2025 July 28`
`2`	`2`
`3`	`3`	`==============================================================================`
`4`	`4`	`Table of Contents render-markdown-table-of-contents`