fix: typing

gen_help.lua

@@ -144,7 +144,11 @@ end
 --- @param line string
 --- @return string
 local function parse_func_header(line)
-  local func = line:match('%w+%.([%w_]+)')
+  -- match:
+  --   prefix.name = ...
+  --   function prefix.name(...
+  local func = line:match('^%w+%.([%w_]+) =')
+    or line:match('^function %w+%.([%w_]+)%(')
   if not func then
     error('Unable to parse: ' .. line)
   end

lua/gitsigns/actions.lua

@@ -149,8 +149,8 @@ M.toggle_deleted = function(value)
   return config.show_deleted
 end
 
----@param bufnr integer
----@param hunks Gitsigns.Hunk.Hunk[]?
+---@param bufnr? integer
+---@param hunks? Gitsigns.Hunk.Hunk[]?
 ---@return Gitsigns.Hunk.Hunk?
 local function get_cursor_hunk(bufnr, hunks)
   bufnr = bufnr or current_buf()
@@ -221,11 +221,11 @@ end
 --- @param range? {[1]: integer, [2]: integer}
 --- @param greedy? boolean
 --- @param staged? boolean
---- @return Gitsigns.Hunk.Hunk
+--- @return Gitsigns.Hunk.Hunk?
 local function get_hunk(bufnr, range, greedy, staged)
   local bcache = cache[bufnr]
   local hunks = get_hunks(bufnr, bcache, greedy, staged)
-  local hunk --- @type Gitsigns.Hunk.Hunk
+  local hunk --- @type Gitsigns.Hunk.Hunk?
   if range then
     table.sort(range)
     local top, bot = range[1], range[2]
@@ -896,14 +896,13 @@ M.blame_line = async.void(function(opts)
   local blame_fmt = create_blame_fmt(is_committed, opts.full)
 
   if is_committed and opts.full then
-    result.body = bcache.git_obj:command({ 'show', '-s', '--format=%B', result.sha })
-
-    local hunk --- @type Gitsigns.Hunk.Hunk?
-
-    hunk, result.hunk_no, result.num_hunks = get_blame_hunk(bcache.git_obj.repo, result)
-
-    assert(hunk)
+    local body = bcache.git_obj:command({ 'show', '-s', '--format=%B', result.sha })
+    local hunk, hunk_no, num_hunks = get_blame_hunk(bcache.git_obj.repo, result)
+    assert(hunk and hunk_no and num_hunks)
 
+    result.hunk_no = hunk_no
+    result.body = body
+    result.num_hunks = num_hunks
     result.hunk = Hunks.patch_lines(hunk, fileformat)
     result.hunk_head = hunk.head
     insert_hunk_hlmarks(blame_fmt, hunk)

lua/gitsigns/attach.lua

@@ -219,11 +219,11 @@ end
 --- @field commit string
 --- @field base string
 
--- Ensure attaches cannot be interleaved.
--- Since attaches are asynchronous we need to make sure an attach isn't
--- performed whilst another one is in progress.
+--- Ensure attaches cannot be interleaved.
+--- Since attaches are asynchronous we need to make sure an attach isn't
+--- performed whilst another one is in progress.
 --- @param cbuf integer
---- @param ctx Gitsigns.GitContext
+--- @param ctx? Gitsigns.GitContext
 --- @param aucmd? string
 local attach_throttled = throttle_by_id(function(cbuf, ctx, aucmd)
   local __FUNC__ = 'attach'

lua/gitsigns/cache.lua

@@ -17,7 +17,7 @@ local M = {
 --- @field hunks_staged?      Gitsigns.Hunk.Hunk[]
 ---
 --- @field staged_diffs       Gitsigns.Hunk.Hunk[]
---- @field gitdir_watcher?    uv_fs_event_t
+--- @field gitdir_watcher?    uv.uv_fs_event_t
 --- @field git_obj            Gitsigns.GitObj
 --- @field commit?            string
 local CacheEntry = M.CacheEntry

lua/gitsigns/cli.lua

@@ -69,14 +69,16 @@ local function print_nonnil(x)
   end
 end
 
+local select = async.wrap(vim.ui.select, 3)
+
 M.run = void(function(params)
   local __FUNC__ = 'cli.run'
   local pos_args_raw, named_args_raw = parse_args(params.args)
 
   local func = pos_args_raw[1]
 
   if not func then
-    func = async.wrap(vim.ui.select, 3)(M.complete('', 'Gitsigns '), {})
+    func = select(M.complete('', 'Gitsigns '), {}) --[[@as string]]
   end
 
   local pos_args = vim.tbl_map(parse_to_lua, vim.list_slice(pos_args_raw, 2))

lua/gitsigns/config.lua

@@ -1,12 +1,3 @@
-local warn
-do
-  -- this is included in gen_help.lua so don't error if requires fail
-  local ok, ret = pcall(require, 'gitsigns.message')
-  if ok then
-    warn = ret.warn
-  end
-end
-
 --- @class Gitsigns.SchemaElem
 --- @field type string|string[]
 --- @field deep_extend? boolean
@@ -395,7 +386,8 @@ M.schema = {
         vertical = true,
         linematch = nil,
       }
-      for _, o in ipairs(vim.opt.diffopt:get()) do
+      local diffopt = vim.opt.diffopt:get() --[[@as string[] ]]
+      for _, o in ipairs(diffopt) do
         if o == 'indent-heuristic' then
           r.indent_heuristic = true
         elseif o == 'internal' then
@@ -474,6 +466,8 @@ M.schema = {
 
   status_formatter = {
     type = 'function',
+    --- @param status Gitsigns.StatusObj
+    --- @return string
     default = function(status)
       local added, changed, removed = status.added, status.changed, status.removed
       local status_txt = {}
@@ -807,7 +801,7 @@ M.schema = {
   },
 }
 
-warn = function(s, ...)
+local function warn(s, ...)
   vim.notify(s:format(...), vim.log.levels.WARN, { title = 'gitsigns' })
 end
 
@@ -828,6 +822,7 @@ local function validate_config(config)
   end
 end
 
+--- @param cfg table<any, any>
 local function handle_deprecated(cfg)
   for k, v in pairs(M.schema) do
     local dep = v.deprecated
@@ -837,7 +832,7 @@ local function handle_deprecated(cfg)
           local opts_key, field = dep.new_field:match('(.*)%.(.*)')
           if opts_key and field then
             -- Field moved to an options table
-            local opts = (cfg[opts_key] or {})
+            local opts = (cfg[opts_key] or {}) --[[@as table<any,any>]]
             opts[field] = cfg[k]
             cfg[opts_key] = opts
           else

lua/gitsigns/diffthis.lua

@@ -15,7 +15,7 @@ local M = {}
 
 --- @param bufnr integer
 --- @param dbufnr integer
---- @param base string
+--- @param base string?
 local bufread = async.void(function(bufnr, dbufnr, base)
   local bcache = cache[bufnr]
   local comp_rev = bcache:get_compare_rev(util.calc_base(base))
@@ -43,7 +43,7 @@ end)
 
 --- @param bufnr integer
 --- @param dbufnr integer
---- @param base string
+--- @param base string?
 local bufwrite = async.void(function(bufnr, dbufnr, base)
   local bcache = cache[bufnr]
   local buftext = util.buf_lines(dbufnr)
@@ -60,7 +60,7 @@ end)
 
 --- Create a gitsigns buffer for a certain revision of a file
 --- @param bufnr integer
---- @param base string
+--- @param base string?
 --- @return string? buf Buffer name
 local function create_show_buf(bufnr, base)
   local bcache = assert(cache[bufnr])
@@ -114,7 +114,7 @@ end
 --- @field vertical boolean
 --- @field split string
 
---- @param base string
+--- @param base string?
 --- @param opts? Gitsigns.DiffthisOpts
 local function diffthis_rev(base, opts)
   local bufnr = api.nvim_get_current_buf()
@@ -135,7 +135,7 @@ local function diffthis_rev(base, opts)
   }, ' '))
 end
 
---- @param base string
+--- @param base string?
 --- @param opts Gitsigns.DiffthisOpts
 M.diffthis = async.void(function(base, opts)
   if vim.wo.diff then

lua/gitsigns/git.lua

@@ -128,6 +128,7 @@ end
 --- @field writer? string[] | string
 --- @field suppress_stderr? boolean
 --- @field raw? boolean Do not strip trailing newlines from stdout
+--- @field args? string[]
 
 --- @param args string[]
 --- @param spec? Gitsigns.Git.JobSpec
@@ -583,6 +584,13 @@ end
 --- @field previous_filename string
 --- @field previous_sha string
 --- @field filename string
+---
+--- Custom fields
+--- @field body? string[]
+--- @field hunk_no? integer
+--- @field num_hunks? integer
+--- @field hunk? string[]
+--- @field hunk_head? string
 
 --- @param lines string[]
 --- @param lnum integer

lua/gitsigns/highlight.lua

@@ -245,11 +245,18 @@ M.hls = {
   },
 }
 
+---@param name string
+---@return table<string, any>
+local function get_hl(name)
+  --- @diagnostic disable-next-line:deprecated
+  return api.nvim_get_hl_by_name(name, true)
+end
+
 --- @param hl_name string
 --- @return boolean
 local function is_hl_set(hl_name)
   -- TODO: this only works with `set termguicolors`
-  local exists, hl = pcall(api.nvim_get_hl_by_name, hl_name, true)
+  local exists, hl = pcall(get_hl, hl_name)
   if not exists then
     return false
   end
@@ -287,7 +294,7 @@ local function derive(hl, hldef)
       if hldef.fg_factor or hldef.bg_factor then
         hldef.fg_factor = hldef.fg_factor or 1
         hldef.bg_factor = hldef.bg_factor or 1
-        local dh = api.nvim_get_hl_by_name(d, true)
+        local dh = get_hl(d)
         api.nvim_set_hl(0, hl, {
           default = true,
           fg = cmul(dh.foreground, hldef.fg_factor),

lua/gitsigns/signs.lua

@@ -7,13 +7,8 @@ local dprint = require('gitsigns.debug.log').dprint
 --- @field count? integer
 --- @field lnum integer
 
---- @class Gitsigns.HlDef
---- @field hl string
---- @field numhl string
---- @field linehl string
-
 --- @class Gitsigns.Signs
---- @field hls table<Gitsigns.SignType,Gitsigns.HlDef>
+--- @field hls table<Gitsigns.SignType,Gitsigns.SignConfig>
 --- @field name string
 --- @field group string
 --- @field config table<string,Gitsigns.SignConfig>
@@ -22,7 +17,7 @@ local dprint = require('gitsigns.debug.log').dprint
 --- Used by signs/vimfn.tl
 --- @field placed table<integer,table<integer,Gitsigns.Sign>>
 --- @field new      fun(cfg: Gitsigns.SignConfig, name: string): Gitsigns.Signs
---- @field _new     fun(cfg: Gitsigns.SignConfig, hls: {SignType:Gitsigns.HlDef}, name: string): Gitsigns.Signs
+--- @field _new     fun(cfg: Gitsigns.SignConfig, hls: {SignType:Gitsigns.SignConfig}, name: string): Gitsigns.Signs
 --- @field remove   fun(self: Gitsigns.Signs, bufnr: integer, start_lnum?: integer, end_lnum?: integer)
 --- @field add      fun(self: Gitsigns.Signs, bufnr: integer, signs: Gitsigns.Sign[])
 --- @field contains fun(self: Gitsigns.Signs, bufnr: integer, start: integer, last: integer): boolean
@@ -49,7 +44,7 @@ function B.new(cfg, name)
     C = require('gitsigns.signs.vimfn')
   end
 
-  local hls = (name == 'staged' and config._signs_staged or config.signs)
+  local hls = name == 'staged' and config._signs_staged or config.signs
   -- Add when config.signs.*.[hl,numhl,linehl] are removed
   -- for _, t in ipairs {
   --    'add',

lua/gitsigns/signs/extmarks.lua

@@ -8,7 +8,7 @@ local M = {}
 local group_base = 'gitsigns_extmark_signs_'
 
 --- @param cfg Gitsigns.SignConfig
---- @param hls table<Gitsigns.SignType,Gitsigns.HlDef>
+--- @param hls table<Gitsigns.SignType,Gitsigns.SignConfig>
 --- @param name string
 --- @return Gitsigns.ExmarkSigns
 function M._new(cfg, hls, name)

lua/gitsigns/signs/vimfn.lua

@@ -82,7 +82,7 @@ end
 local group_base = 'gitsigns_vimfn_signs_'
 
 --- @param cfg Gitsigns.SignConfig
---- @param hls table<Gitsigns.SignType,Gitsigns.HlDef>
+--- @param hls table<Gitsigns.SignType,Gitsigns.SignConfig>
 --- @param name string
 --- @return Gitsigns.VimFnSigns
 function M._new(cfg, hls, name)

lua/gitsigns/status.lua

@@ -1,9 +1,12 @@
 local api = vim.api
 
---- @class Gitsigns.StatusObj
---- @field added integer
---- @field removed integer
---- @field changed integer
+--- @class (exact) Gitsigns.StatusObj
+--- @field added? integer
+--- @field removed? integer
+--- @field changed? integer
+--- @field head? string
+--- @field root? string
+--- @field gitdir? string
 
 local M = {}
 

lua/gitsigns/subprocess.lua

@@ -11,7 +11,7 @@ M.job_cnt = 0
 --- @field cwd string
 --- @field writer string[] | string
 
---- @param ... uv_pipe_t
+--- @param ... uv.uv_pipe_t
 local function try_close(...)
   for i = 1, select('#', ...) do
     local pipe = select(i, ...)
@@ -21,7 +21,7 @@ local function try_close(...)
   end
 end
 
---- @param pipe uv_pipe_t
+--- @param pipe uv.uv_pipe_t
 --- @param x string[]|string
 local function handle_writer(pipe, x)
   if type(x) == 'table' then
@@ -43,7 +43,7 @@ local function handle_writer(pipe, x)
   end
 end
 
---- @param pipe uv_pipe_t
+--- @param pipe uv.uv_pipe_t
 --- @param output string[]
 local function handle_reader(pipe, output)
   pipe:read_start(function(err, data)
@@ -72,13 +72,14 @@ function M.run_job(obj, callback)
 
   local stdout = assert(uv.new_pipe(false))
   local stderr = assert(uv.new_pipe(false))
-  local stdin --- @type uv_pipe_t?
+  local stdin --- @type uv.uv_pipe_t?
   if obj.writer then
     stdin = assert(uv.new_pipe(false))
   end
 
-  --- @type uv_process_t?, integer|string
+  --- @type uv.uv_process_t?, integer|string
   local handle, _pid
+  --- @diagnostic disable-next-line:missing-fields
   handle, _pid = uv.spawn(obj.command, {
     args = obj.args,
     stdio = { stdin, stdout, stderr },