test: improve typing

Author: lewis6991

.github/workflows/ci.yml

@@ -53,7 +53,7 @@ jobs:
       - name: Run Test
         run: make test
 
-  stylua:
+  format:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -62,8 +62,8 @@ jobs:
       - name: Download stylua
         run: make stylua
 
-      - name: Lint
-        run: make stylua-check
+      - name: Format
+        run: make format-check
 
   emmylua:
     runs-on: ubuntu-latest

AGENTS.md

@@ -1,32 +1,29 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-Core Lua modules live in `lua/gitsigns/` (config, handlers, utilities) and should stay pure so specs can require them directly.
-User-facing commands and autocmds are wired in `plugin/gitsigns.vim`, while help files under `doc/` get regenerated by `gen_help.lua`.
-Specs plus fixtures sit in `test/`, relying on helpers in `test/gs_helpers.lua`.
-Tooling binaries (Stylua, nvim-test, EmmyLua) are cached in `deps/`.
+- Core Lua modules live in `lua/gitsigns/` (config, handlers, utilities).
+- User-facing commands are wired in `plugin/gitsigns.vim`
+- Help files under `doc/` get regenerated by `gen_help.lua`.
+- Specs plus fixtures sit in `test/`, relying on helpers in `test/gs_helpers.lua`.
+- Tooling binaries (Stylua, nvim-test, EmmyLua) are cached in `deps/`.
 
 ## Build, Test, and Development Commands
 - `make build`: run Stylua over `lua/` + `test/`, then regenerate help files before committing.
 - `make test [FILTER=pattern]`: execute the functional suite via nvim-test with the default Neovim runner.
 - `make test-010`, `make test-011`, `make test-nightly`: confirm compatibility with multiple Neovim versions.
 - `make doc` / `make doc-check`: regenerate help from `lua/gitsigns/config.lua` and fail if docs drift.
-- `make stylua-check` or `make stylua-run`: lint or autoformat Lua sources.
+- `make format-check` or `make format`: lint or autoformat Lua sources.
 - `make emmylua-check`: run optional static analysis after fetching the analyzer.
 
 ## Coding Style & Naming Conventions
-Stylua enforces 2-space indentation, 100-character columns, Unix line endings, and `auto_prefer_single` quotes (`.stylua.toml`).
-Public modules export tables named after their file (e.g., `require('gitsigns.diff')`); local helpers stay snake_case.
-Keep API naming aligned with existing commands (`setup`, `attach`, `preview_hunk`) and prefer keyed tables over positional args.
-Wrap Neovim APIs in utility functions when tests need to mock them, and run `make stylua-run` before pushing.
+- Lua code must have emmylua/LuaCATS type annotations
+- 2-space indentation, 100-character columns, single quotes for strings.
+- Run `make format` after changing any code
 
 ## Testing Guidelines
-Specs reside in `test/*_spec.lua` and run under the `nvim-test` harness, which provisions a headless Neovim plus RPC helpers.
-Every bug fix must include a spec that reproduces the regression and asserts the desired buffer state, co-located with related modules (for example, `hunk_spec.lua` for hunk logic).
-Use `test/gs_helpers.lua` utilities instead of shelling out to Git, and reset repo fixtures between assertions.
-Keep tests deterministic by guarding optional Git features and running the version matrix (`make test-010 && make test-nightly`) when Neovim internals are touched.
+- Every bug fix must include a spec that reproduces the regression and asserts the desired buffer state, co-located with related modules (for example, `hunk_spec.lua` for hunk logic).
+- Keep tests deterministic by guarding optional Git features and running the version matrix (`make test-010 && make test-nightly`) when Neovim internals are touched.
 
 ## Commit & Pull Request Guidelines
-History follows a lightweight Conventional Commit style: `<type>(<scope>): <verb phrase>` (for instance, `fix(blame): close blame window on bufhidden`), so match that pattern and keep subjects under 72 characters.
-Each PR should recap the bug, list manual or automated verification, link upstream issues, and mention doc help updates when behavior changes.
-Ensure `make build`, the relevant `make test-*`, and `make doc-check` all pass locally.
+- History follows a Conventional Commit style: `<type>(<scope>): <verb phrase>` (for instance, `fix(blame): close blame window on bufhidden`), so match that pattern and keep subjects under 72 characters.
+- Ensure `make build`, the relevant `make test-*`, and `make doc-check` all pass locally.

Makefile

@@ -10,7 +10,7 @@ endif
 .DEFAULT_GOAL := build
 
 .PHONY: build
-build: doc stylua-run
+build: doc format
 
 ################################################################################
 # nvim-test
@@ -99,12 +99,12 @@ $(STYLUA): $(STYLUA_ZIP)
 
 LUA_FILES := $(shell git ls-files lua test)
 
-.PHONY: stylua-check
-stylua-check: $(STYLUA)
+.PHONY: format-check
+format-check: $(STYLUA)
 	$(STYLUA) --check $(LUA_FILES)
 
-.PHONY: stylua-run
-stylua-run: $(STYLUA)
+.PHONY: format
+format: $(STYLUA)
 	$(STYLUA) $(LUA_FILES)
 
 ################################################################################

test/actions_spec.lua

@@ -51,6 +51,7 @@ end
 
 local delay = 10
 
+--- @param cmd string
 local function command(cmd)
   helpers.sleep(delay)
   helpers.api.nvim_command(cmd)
@@ -72,7 +73,7 @@ local function retry(f)
     if ok then
       return
     end
-    delay = delay * 1.6
+    delay = math.ceil(delay * 1.6)
     print('failed, retrying with delay', delay)
   end
 

test/gitsigns_spec.lua

@@ -33,7 +33,7 @@ helpers.env()
 
 ---@param bufnr? integer
 local function wait_for_attach(bufnr)
-  helpers.expectf(function()
+  expectf(function()
     return exec_lua(function(bufnr0)
       return vim.b[bufnr0 or 0].gitsigns_status_dict.gitdir ~= nil
     end, bufnr)
@@ -770,7 +770,12 @@ describe('gitsigns (with screen)', function()
           signs = { changed = 1, added = 4 },
         })
 
-        exec_lua('require("gitsigns.actions").stage_hunk()')
+        -- Minor delay to avoid the test being flaky
+        helpers.sleep(50)
+
+        exec_lua(function()
+          require('gitsigns.actions').stage_hunk()
+        end)
 
         check({
           status = { head = 'HEAD(rebasing)', added = 0, changed = 0, removed = 0 },
@@ -1038,7 +1043,7 @@ describe('gitsigns attach', function()
     eq('gitsigns://' .. scratch .. '/.git//:0:sub/test', api.nvim_buf_get_name(0))
 
     local gfile, toplevel, gitdir, abbrev_head = exec_lua(function()
-      local git_obj = require('gitsigns.cache').cache[1].git_obj
+      local git_obj = assert(require('gitsigns.cache').cache[1]).git_obj
       return git_obj.file, git_obj.repo.toplevel, git_obj.repo.gitdir, git_obj.repo.abbrev_head
     end)
 

test/gs_helpers.lua

@@ -113,7 +113,6 @@ function M.expectf(cond, interval)
   local duration = 0
   interval = interval or 1
   while duration < timeout do
-    --- @type boolean, boolean?
     local ok, ret = pcall(cond)
     if ok and (ret == nil or ret == true) then
       return
@@ -286,7 +285,7 @@ local function check_signs(signs, bufnr)
   local buf_signs = {} --- @type string[]
   local buf_marks = helpers.api.nvim_buf_get_extmarks(bufnr, -1, 0, -1, { details = true })
   for _, s in ipairs(buf_marks) do
-    buf_signs[#buf_signs + 1] = s[4].sign_hl_group
+    buf_signs[#buf_signs + 1] = assert(s[4]).sign_hl_group
   end
 
   --- @type table<string,integer>

test/highlights_spec.lua

@@ -56,11 +56,6 @@ describe('highlights', function()
   it('get set up correctly', function()
     command('set termguicolors')
 
-    config.signs.add.hl = nil
-    config.signs.change.hl = nil
-    config.signs.delete.hl = nil
-    config.signs.changedelete.hl = nil
-    config.signs.topdelete.hl = nil
     config.numhl = true
     config.linehl = true
     config._test_mode = true
@@ -84,14 +79,7 @@ describe('highlights', function()
 
   it('update when colorscheme changes', function()
     command('set termguicolors')
-
-    config.signs.add.hl = nil
-    config.signs.change.hl = nil
-    config.signs.delete.hl = nil
-    config.signs.changedelete.hl = nil
-    config.signs.topdelete.hl = nil
     config.linehl = true
-
     setup_gitsigns(config)
   end)
 end)

test/hunk_spec.lua

@@ -6,35 +6,32 @@ local eq = helpers.eq
 helpers.env()
 
 --- @param hunks [string,integer,integer,integer,integer][]
---- @return [string,integer,integer][]
+--- @return [string,integer,integer?][]
 local function calc_signs(hunks)
+  local hunks1 = {} --- @type Gitsigns.Hunk.Hunk[]
   for i, hunk in ipairs(hunks) do
-    if hunk[1] then
-      hunks[i] = {
-        added = { count = hunk[4], start = hunk[5] },
-        removed = { count = hunk[2], start = hunk[3] },
-        type = hunk[1],
-      }
-    end
+    hunks1[i] = {
+      added = { count = hunk[4], start = hunk[5] },
+      removed = { count = hunk[2], start = hunk[3] },
+      type = hunk[1],
+    }
   end
 
-  --- @type Gitsigns.Sign[]
   local signs = exec_lua(
     --- @param hunks0 Gitsigns.Hunk.Hunk[]
-    --- @return Gitsigns.Sign[]
     function(hunks0)
       local Hunks = require('gitsigns.hunks')
-      local signs = {}
+      local signs0 = {} --- @type Gitsigns.Sign[]
       for i, hunk in ipairs(hunks0) do
         local prev_hunk, next_hunk = hunks0[i - 1], hunks0[i + 1]
-        vim.list_extend(signs, Hunks.calc_signs(prev_hunk, hunk, next_hunk))
+        vim.list_extend(signs0, Hunks.calc_signs(prev_hunk, hunk, next_hunk))
       end
-      return signs
+      return signs0
     end,
-    hunks
+    hunks1
   )
 
-  local r = {} --- @type [string,integer,integer][]
+  local r = {} --- @type [string,integer,integer?][]
   for i, s in ipairs(signs) do
     r[i] = { s.type, s.lnum, s.count }
   end