From cbc4450a6c238114362e3c2fbca355166c2a2202 Mon Sep 17 00:00:00 2001
From: PFiS <pfis1737@gmail.com>
Date: Sat, 5 Jul 2025 19:01:07 +0800
Subject: [PATCH] chore: add type hints for `git.yazi` (#111)

Co-authored-by: sxyazi <sxyazi@gmail.com>
---
 git.yazi/main.lua  | 27 +++++++++++++++++++++++++--
 git.yazi/types.lua | 12 ++++++++++++
 2 files changed, 37 insertions(+), 2 deletions(-)
 create mode 100644 git.yazi/types.lua

diff --git a/git.yazi/main.lua b/git.yazi/main.lua
index aa402e5..e6b3a36 100644
--- a/git.yazi/main.lua
+++ b/git.yazi/main.lua
@@ -5,6 +5,7 @@ local WINDOWS = ya.target_family() == "windows"
 -- The code of supported git status,
 -- also used to determine which status to show for directories when they contain different statuses
 -- see `bubble_up`
+---@enum CODES
 local CODES = {
 	excluded = 100, -- ignored directory
 	ignored = 6, -- ignored file
@@ -26,6 +27,8 @@ local PATTERNS = {
 	{ "[AD][AD]", CODES.updated },
 }
 
+---@param line string
+---@return CODES, string
 local function match(line)
 	local signs = line:sub(1, 2)
 	for _, p in ipairs(PATTERNS) do
@@ -41,9 +44,12 @@ local function match(line)
 		else
 			return code, path
 		end
+		---@diagnostic disable-next-line: missing-return
 	end
 end
 
+---@param cwd Url
+---@return string?
 local function root(cwd)
 	local is_worktree = function(url)
 		local file, head = io.open(tostring(url)), nil
@@ -64,6 +70,8 @@ local function root(cwd)
 	until not cwd
 end
 
+---@param changed Changes
+---@return Changes
 local function bubble_up(changed)
 	local new, empty = {}, Url("")
 	for path, code in pairs(changed) do
@@ -79,6 +87,10 @@ local function bubble_up(changed)
 	return new
 end
 
+---@param excluded string[]
+---@param cwd Url
+---@param repo Url
+---@return Changes
 local function propagate_down(excluded, cwd, repo)
 	local new, rel = {}, cwd:strip_prefix(repo)
 	for _, path in ipairs(excluded) do
@@ -95,7 +107,12 @@ local function propagate_down(excluded, cwd, repo)
 	return new
 end
 
+---@param cwd string
+---@param repo string
+---@param changed Changes
 local add = ya.sync(function(st, cwd, repo, changed)
+	---@cast st State
+
 	st.dirs[cwd] = repo
 	st.repos[repo] = st.repos[repo] or {}
 	for path, code in pairs(changed) do
@@ -116,7 +133,10 @@ local add = ya.sync(function(st, cwd, repo, changed)
 	end
 end)
 
+---@param cwd string
 local remove = ya.sync(function(st, cwd)
+	---@cast st State
+
 	local repo = st.dirs[cwd]
 	if not repo then
 		return
@@ -141,9 +161,11 @@ local remove = ya.sync(function(st, cwd)
 	st.repos[repo] = nil
 end)
 
+---@param st State
+---@param opts Options
 local function setup(st, opts)
-	st.dirs = {} -- Mapping between a directory and its corresponding repository
-	st.repos = {} -- Mapping between a repository and the status of each of its files
+	st.dirs = {}
+	st.repos = {}
 
 	opts = opts or {}
 	opts.order = opts.order or 1500
@@ -184,6 +206,7 @@ local function setup(st, opts)
 	end, opts.order)
 end
 
+---@type UnstableFetcher
 local function fetch(_, job)
 	local cwd = job.files[1].url.base
 	local repo = root(cwd)
diff --git a/git.yazi/types.lua b/git.yazi/types.lua
new file mode 100644
index 0000000..dc4e77b
--- /dev/null
+++ b/git.yazi/types.lua
@@ -0,0 +1,12 @@
+---@class State
+---@field dirs table<string, string|CODES> Mapping between a directory and its corresponding repository
+---@field repos table<string, Changes> Mapping between a repository and the status of each of its files
+
+---@class Options
+---@field order number The order in which the status is displayed
+---@field renamed boolean Whether to include renamed files in the status (or treat them as modified)
+
+-- TODO: move this to `types.yazi` once it's get stable
+---@alias UnstableFetcher fun(self: unknown, job: { files: File[] })
+
+---@alias Changes table<string, CODES>