docs(lua): add LuaCATS type annotations across core modules

lua/cp/cache.lua

@@ -266,6 +266,7 @@ end
 ---@param memory_mb number
 ---@param interactive boolean
 ---@param multi_test boolean
+---@param precision number?
 function M.set_test_cases(
   platform,
   contest_id,
@@ -467,6 +468,7 @@ function M.clear_credentials(platform)
   M.save()
 end
 
+---@return nil
 function M.clear_all()
   cache_data = {}
   M.save()
@@ -488,6 +490,7 @@ function M.get_data_pretty()
   return vim.inspect(cache_data)
 end
 
+---@return table
 function M.get_raw_cache()
   return cache_data
 end

lua/cp/config.lua

@@ -531,10 +531,12 @@ end
 
 local current_config = nil
 
+---@param config cp.Config
 function M.set_current_config(config)
   current_config = config
 end
 
+---@return cp.Config
 function M.get_config()
   return current_config or M.defaults
 end

lua/cp/credentials.lua

@@ -11,6 +11,7 @@ local STATUS_MESSAGES = {
   installing_browser = 'Installing browser...',
 }
 
+---@param platform string?
 function M.login(platform)
   platform = platform or state.get_platform()
   if not platform then
@@ -68,6 +69,7 @@ function M.login(platform)
   end)
 end
 
+---@param platform string?
 function M.logout(platform)
   platform = platform or state.get_platform()
   if not platform then

lua/cp/health.lua

@@ -66,6 +66,7 @@ local function check()
   end
 end
 
+---@return nil
 function M.check()
   local version = require('cp.version')
   vim.health.start('cp.nvim health check ~')

lua/cp/init.lua

@@ -38,11 +38,13 @@ function M.handle_command(opts)
   commands.handle_command(opts)
 end
 
+---@return boolean
 function M.is_initialized()
   return initialized
 end
 
 ---@deprecated Use `vim.g.cp` instead
+---@param user_config table?
 function M.setup(user_config)
   vim.deprecate('require("cp").setup()', 'vim.g.cp', 'v0.7.7', 'cp.nvim', false)
 

lua/cp/race.lua

@@ -134,6 +134,9 @@ local function race_try_setup(platform, contest_id, language, attempt, token)
   )
 end
 
+---@param platform string
+---@param contest_id string
+---@param language? string
 function M.start(platform, contest_id, language)
   if not platform or not vim.tbl_contains(constants.PLATFORMS, platform) then
     logger.log('Invalid platform', { level = vim.log.levels.ERROR })
@@ -252,6 +255,7 @@ function M.start(platform, contest_id, language)
   )
 end
 
+---@return nil
 function M.stop()
   local timer = race_state.timer
   if not timer then
@@ -276,6 +280,7 @@ function M.stop()
   )
 end
 
+---@return { active: boolean, platform?: string, contest_id?: string, remaining_seconds?: integer }
 function M.status()
   if not race_state.timer or not race_state.start_time then
     return { active = false }

lua/cp/runner/execute.lua

@@ -33,6 +33,9 @@ local function substitute_template(cmd_template, substitutions)
   return out
 end
 
+---@param cmd_template string[]
+---@param substitutions SubstitutableCommand
+---@return string[]
 function M.build_command(cmd_template, substitutions)
   return substitute_template(cmd_template, substitutions)
 end

lua/cp/runner/run_render.lua

@@ -376,6 +376,7 @@ function M.get_highlight_groups()
   }
 end
 
+---@return nil
 function M.setup_highlights()
   local groups = M.get_highlight_groups()
   for name, opts in pairs(groups) do

lua/cp/scraper.lua

@@ -216,6 +216,10 @@ local function run_scraper(platform, subcommand, args, opts)
   end
 end
 
+---@param platform string
+---@param contest_id string
+---@param callback fun(data: table)?
+---@param on_error fun()?
 function M.scrape_contest_metadata(platform, contest_id, callback, on_error)
   run_scraper(platform, 'metadata', { contest_id }, {
     on_exit = function(result)
@@ -253,6 +257,8 @@ function M.scrape_contest_metadata(platform, contest_id, callback, on_error)
   })
 end
 
+---@param platform string
+---@return { contests: ContestSummary[], supports_countdown: boolean }?
 function M.scrape_contest_list(platform)
   local result = run_scraper(platform, 'contests', {}, { sync = true })
   if not result or not result.success or not (result.data and result.data.contests) then
@@ -330,6 +336,10 @@ function M.scrape_all_tests(platform, contest_id, callback, on_done)
   })
 end
 
+---@param platform string
+---@param credentials table
+---@param on_status fun(ev: table)?
+---@param callback fun(result: table)?
 function M.login(platform, credentials, on_status, callback)
   local done = false
   run_scraper(platform, 'login', {}, {
@@ -361,6 +371,14 @@ function M.login(platform, credentials, on_status, callback)
   })
 end
 
+---@param platform string
+---@param contest_id string
+---@param problem_id string
+---@param language string
+---@param source_file string
+---@param credentials table
+---@param on_status fun(ev: table)?
+---@param callback fun(result: table)?
 function M.submit(
   platform,
   contest_id,

lua/cp/stress.lua

@@ -58,6 +58,8 @@ local function build_run_cmd(file)
   return './' .. file
 end
 
+---@param generator_cmd? string
+---@param brute_cmd? string
 function M.toggle(generator_cmd, brute_cmd)
   if state.get_active_panel() == 'stress' then
     if state.stress_buf and vim.api.nvim_buf_is_valid(state.stress_buf) then
@@ -239,6 +241,7 @@ function M.toggle(generator_cmd, brute_cmd)
   end)
 end
 
+---@return nil
 function M.cancel()
   if state.stress_buf and vim.api.nvim_buf_is_valid(state.stress_buf) then
     local job = vim.b[state.stress_buf].terminal_job_id

lua/cp/submit.lua

@@ -38,6 +38,7 @@ local function prompt_credentials(platform, callback)
   end)
 end
 
+---@param opts { language?: string }?
 function M.submit(opts)
   local platform = state.get_platform()
   local contest_id = state.get_contest_id()

lua/cp/ui/edit.lua

@@ -331,6 +331,7 @@ setup_keybindings = function(buf)
   })
 end
 
+---@param test_index? integer
 function M.toggle_edit(test_index)
   if edit_state then
     save_all_tests()

lua/cp/ui/layouts.lua

@@ -1,3 +1,9 @@
+---@class DiffLayout
+---@field buffers integer[]
+---@field windows integer[]
+---@field mode string
+---@field cleanup fun()
+
 local M = {}
 
 local helpers = require('cp.helpers')
@@ -171,6 +177,11 @@ local function create_single_layout(parent_win, content)
   }
 end
 
+---@param mode string
+---@param parent_win integer
+---@param expected_content string
+---@param actual_content string
+---@return DiffLayout
 function M.create_diff_layout(mode, parent_win, expected_content, actual_content)
   if mode == 'single' then
     return create_single_layout(parent_win, actual_content)
@@ -185,6 +196,13 @@ function M.create_diff_layout(mode, parent_win, expected_content, actual_content
   end
 end
 
+---@param current_diff_layout DiffLayout?
+---@param current_mode string?
+---@param main_win integer
+---@param run table
+---@param config cp.Config
+---@param setup_keybindings_for_buffer fun(buf: integer)
+---@return DiffLayout?, string?
 function M.update_diff_panes(
   current_diff_layout,
   current_mode,

lua/cp/ui/views.lua

@@ -16,6 +16,7 @@ local current_diff_layout = nil
 local current_mode = nil
 local _run_gen = 0
 
+---@return nil
 function M.disable()
   local active_panel = state.get_active_panel()
   if not active_panel then
@@ -351,6 +352,7 @@ local function create_window_layout(output_buf, input_buf)
   vim.api.nvim_set_current_win(solution_win)
 end
 
+---@return nil
 function M.ensure_io_view()
   local platform, contest_id, problem_id =
     state.get_platform(), state.get_contest_id(), state.get_problem_id()
@@ -598,6 +600,9 @@ local function render_io_view_results(io_state, test_indices, mode, combined_res
   utils.update_buffer_content(io_state.output_buf, output_lines, final_highlights, output_ns)
 end
 
+---@param test_indices_arg integer[]?
+---@param debug boolean?
+---@param mode? string
 function M.run_io_view(test_indices_arg, debug, mode)
   _run_gen = _run_gen + 1
   local gen = _run_gen
@@ -754,10 +759,12 @@ function M.run_io_view(test_indices_arg, debug, mode)
   end)
 end
 
+---@return nil
 function M.cancel_io_view()
   _run_gen = _run_gen + 1
 end
 
+---@return nil
 function M.cancel_interactive()
   if state.interactive_buf and vim.api.nvim_buf_is_valid(state.interactive_buf) then
     local job = vim.b[state.interactive_buf].terminal_job_id

lua/cp/utils.lua

@@ -314,6 +314,7 @@ end
 
 --- Configure the buffer with good defaults
 ---@param filetype? string
+---@return integer
 function M.create_buffer_with_options(filetype)
   local buf = vim.api.nvim_create_buf(false, true)
   vim.api.nvim_set_option_value('bufhidden', 'hide', { buf = buf })
@@ -345,6 +346,7 @@ function M.update_buffer_content(bufnr, lines, highlights, namespace)
   end
 end
 
+---@return boolean, string?
 function M.check_required_runtime()
   if is_windows() then
     return false, 'Windows is not supported'
@@ -419,16 +421,19 @@ local function find_gnu_timeout()
   return _timeout_path, _timeout_reason
 end
 
+---@return string?
 function M.timeout_path()
   local path = find_gnu_timeout()
   return path
 end
 
+---@return { ok: boolean, path: string|nil, reason: string|nil }
 function M.timeout_capability()
   local path, reason = find_gnu_timeout()
   return { ok = path ~= nil, path = path, reason = reason }
 end
 
+---@return string[]
 function M.cwd_executables()
   local uv = vim.uv
   local req = uv.fs_scandir('.')
@@ -452,6 +457,7 @@ function M.cwd_executables()
   return out
 end
 
+---@return nil
 function M.ensure_dirs()
   vim.system({ 'mkdir', '-p', 'build', 'io' }):wait()
 end