feat: enhance luacats annotations

lua/cp/execute.lua

@@ -1,3 +1,10 @@
+---@class ExecuteResult
+---@field stdout string
+---@field stderr string
+---@field code integer
+---@field time_ms number
+---@field timed_out boolean
+
 local M = {}
 local logger = require("cp.log")
 
@@ -10,14 +17,30 @@ local filetype_to_language = {
 	py3 = "python",
 }
 
-local function get_language_from_file(source_file)
+---@param source_file string
+---@param contest_config table
+---@return string
+local function get_language_from_file(source_file, contest_config)
+	vim.validate({
+		source_file = { source_file, "string" },
+		contest_config = { contest_config, "table" },
+	})
+
 	local extension = vim.fn.fnamemodify(source_file, ":e")
-	local language = filetype_to_language[extension] or "cpp"
+	local language = filetype_to_language[extension] or contest_config.default_language
 	logger.log(("detected language: %s (extension: %s)"):format(language, extension))
 	return language
 end
 
+---@param cmd_template string[]
+---@param substitutions table<string, string>
+---@return string[]
 local function substitute_template(cmd_template, substitutions)
+	vim.validate({
+		cmd_template = { cmd_template, "table" },
+		substitutions = { substitutions, "table" },
+	})
+
 	local result = {}
 	for _, arg in ipairs(cmd_template) do
 		local substituted = arg
@@ -29,7 +52,17 @@ local function substitute_template(cmd_template, substitutions)
 	return result
 end
 
+---@param cmd_template string[]
+---@param executable? string
+---@param substitutions table<string, string>
+---@return string[]
 local function build_command(cmd_template, executable, substitutions)
+	vim.validate({
+		cmd_template = { cmd_template, "table" },
+		executable = { executable, { "string", "nil" }, true },
+		substitutions = { substitutions, "table" },
+	})
+
 	local cmd = substitute_template(cmd_template, substitutions)
 	if executable then
 		table.insert(cmd, 1, executable)
@@ -59,7 +92,15 @@ local function ensure_directories()
 	vim.system({ "mkdir", "-p", "build", "io" }):wait()
 end
 
+---@param language_config table
+---@param substitutions table<string, string>
+---@return {code: integer, stderr: string}
 local function compile_generic(language_config, substitutions)
+	vim.validate({
+		language_config = { language_config, "table" },
+		substitutions = { substitutions, "table" },
+	})
+
 	if not language_config.compile then
 		logger.log("no compilation step required")
 		return { code = 0, stderr = "" }
@@ -81,7 +122,17 @@ local function compile_generic(language_config, substitutions)
 	return result
 end
 
+---@param cmd string[]
+---@param input_data string
+---@param timeout_ms integer
+---@return ExecuteResult
 local function execute_command(cmd, input_data, timeout_ms)
+	vim.validate({
+		cmd = { cmd, "table" },
+		input_data = { input_data, "string" },
+		timeout_ms = { timeout_ms, "number" },
+	})
+
 	logger.log(("executing: %s"):format(table.concat(cmd, " ")))
 
 	local start_time = vim.loop.hrtime()
@@ -114,7 +165,17 @@ local function execute_command(cmd, input_data, timeout_ms)
 	}
 end
 
+---@param exec_result ExecuteResult
+---@param expected_file string
+---@param is_debug boolean
+---@return string
 local function format_output(exec_result, expected_file, is_debug)
+	vim.validate({
+		exec_result = { exec_result, "table" },
+		expected_file = { expected_file, "string" },
+		is_debug = { is_debug, "boolean" },
+	})
+
 	local output_lines = { exec_result.stdout }
 	local metadata_lines = {}
 
@@ -158,9 +219,15 @@ end
 ---@param contest_config table
 ---@param is_debug boolean
 function M.run_problem(ctx, contest_config, is_debug)
+	vim.validate({
+		ctx = { ctx, "table" },
+		contest_config = { contest_config, "table" },
+		is_debug = { is_debug, "boolean" },
+	})
+
 	ensure_directories()
 
-	local language = get_language_from_file(ctx.source_file)
+	local language = get_language_from_file(ctx.source_file, contest_config)
 	local language_config = contest_config[language]
 
 	if not language_config then
@@ -171,7 +238,7 @@ function M.run_problem(ctx, contest_config, is_debug)
 	local substitutions = {
 		source = ctx.source_file,
 		binary = ctx.binary_file,
-		version = tostring(language_config.version or ""),
+		version = tostring(language_config.version),
 	}
 
 	local compile_cmd = is_debug and language_config.debug or language_config.compile