fix(lua): enable nil-safety diagnostics in runtime code

Enable EmmyLua's need-check-nil diagnostic and resolve nullable values
through more precise types, explicit invariants, and guards for missing
runtime state. Keep analyzer-specific workarounds local and update the
affected API documentation.

Exclude the bundled re.lua from analysis so its nil-check warnings do
not fail CI.

AI-assisted

1 files changed, 13 insertions, 4 deletions

diff --git a/runtime/lua/vim/hl.lua b/runtime/lua/vim/hl.lua
index c02986b28e..304c73a4b2 100644
--- a/runtime/lua/vim/hl.lua
+++ b/runtime/lua/vim/hl.lua
@@ -60,20 +60,29 @@ function M.range(buf, ns, hlgroup, start, finish, opts)
 
   local v_maxcol = vim.v.maxcol
 
-  local pos1 = type(start) == 'string' and vim.fn.getpos(start)
-    or {
+  local pos1 --- @type [integer, integer, integer, integer]
+  if type(start) == 'string' then
+    pos1 = vim.fn.getpos(start)
+  else
+    pos1 = {
       buf,
       start[1] + 1,
       start[2] ~= -1 and start[2] ~= v_maxcol and start[2] + 1 or v_maxcol,
       0,
     }
-  local pos2 = type(finish) == 'string' and vim.fn.getpos(finish)
-    or {
+  end
+
+  local pos2 ---@type [integer, integer, integer, integer]
+  if type(finish) == 'string' then
+    pos2 = vim.fn.getpos(finish)
+  else
+    pos2 = {
       buf,
       finish[1] + 1,
       finish[2] ~= -1 and finish[2] ~= v_maxcol and finish[2] + 1 or v_maxcol,
       0,
     }
+  end
 
   local buf_line_count = api.nvim_buf_line_count(buf)
   pos1[2] = math.min(pos1[2], buf_line_count)