feat(lua): add basic LuaCATS types for internal lua code

yazi-plugin/preset/components/current.lua

@@ -1,7 +1,11 @@
+---@class yazi.Current
+---@field area? unknown
 Current = {
 	area = ui.Rect.default,
 }
 
+---@param area unknown
+---@return table
 function Current:empty(area)
 	local folder = Folder:by_kind(Folder.CURRENT)
 
@@ -17,6 +21,8 @@ function Current:empty(area)
 	}
 end
 
+---@param area unknown
+---@return table
 function Current:render(area)
 	self.area = area
 

yazi-plugin/preset/components/file.lua

@@ -1,5 +1,8 @@
+---@class yazi.File
 File = {}
 
+---@param file unknown
+---@return table
 function File:icon(file)
 	local icon = file:icon()
 	if not icon then
@@ -11,11 +14,15 @@ function File:icon(file)
 	end
 end
 
+---@param file unknown
+---@return table
 function File:prefix(file)
 	local prefix = file:prefix() or ""
 	return prefix == "" and {} or { ui.Span(prefix .. "/") }
 end
 
+---@param file unknown
+---@return table
 function File:highlights(file)
 	local name = file.name:gsub("\r", "?", 1)
 	local highlights = file:highlights()
@@ -53,6 +60,8 @@ function File:found(file)
 	}
 end
 
+---@param file unknown
+---@return table
 function File:symlink(file)
 	if not MANAGER.show_symlink then
 		return {}
@@ -62,6 +71,8 @@ function File:symlink(file)
 	return to and { ui.Span(" -> " .. tostring(to)):italic() } or {}
 end
 
+---@param file unknown
+---@return table
 function File:full(file)
 	return ya.flat {
 		self:icon(file),
@@ -72,6 +83,8 @@ function File:full(file)
 	}
 end
 
+---@param file unknown
+---@return table
 function File:style(file)
 	local style = file:style()
 	if not file:is_hovered() then
@@ -83,6 +96,8 @@ function File:style(file)
 	end
 end
 
+---@param file unknown
+---@return 0 | 1 | 2 | 3 | 4
 function File:marker(file)
 	local yanked = file:is_yanked()
 	if yanked ~= 0 then

yazi-plugin/preset/components/folder.lua

@@ -1,9 +1,12 @@
+---@class yazi.Folder
 Folder = {
 	PARENT = 0,
 	CURRENT = 1,
 	PREVIEW = 2,
 }
 
+---@param area unknown
+---@param files unknown[]
 function Folder:linemode(area, files)
 	local mode = cx.active.conf.linemode
 	if mode == "none" then
@@ -29,6 +32,9 @@ function Folder:linemode(area, files)
 	return ui.Paragraph(area, lines):align(ui.Paragraph.RIGHT)
 end
 
+---@param area unknown
+---@param markers unknown[]
+---@return table
 function Folder:markers(area, markers)
 	if #markers == 0 or area.w * area.h == 0 then
 		return {}
@@ -73,6 +79,7 @@ function Folder:markers(area, markers)
 	return elements
 end
 
+---@param kind yazi.FolderType
 function Folder:by_kind(kind)
 	if kind == self.PARENT then
 		return cx.active.parent

yazi-plugin/preset/components/header.lua

@@ -1,7 +1,10 @@
+---@class yazi.Header
 Header = {
 	area = ui.Rect.default,
 }
 
+---@param max integer
+---@return table
 function Header:cwd(max)
 	local cwd = cx.active.current.cwd
 	local readable = ya.readable_path(tostring(cwd))
@@ -10,6 +13,7 @@ function Header:cwd(max)
 	return ui.Span(ya.truncate(text, { max = max, rtl = true })):style(THEME.manager.cwd)
 end
 
+---@return table
 function Header:count()
 	local yanked = #cx.yanked
 
@@ -35,6 +39,7 @@ function Header:count()
 	}
 end
 
+---@return table
 function Header:tabs()
 	local tabs = #cx.tabs
 	if tabs == 1 then
@@ -57,6 +62,9 @@ function Header:tabs()
 end
 
 -- TODO: remove this function after v0.2.5 release
+--
+---@param area unknown
+---@return table
 function Header:layout(area)
 	if not ya.deprecated_header_layout then
 		ya.deprecated_header_layout = true
@@ -76,6 +84,8 @@ function Header:layout(area)
 		:split(area)
 end
 
+---@param area unknown
+---@return table
 function Header:render(area)
 	self.area = area
 

yazi-plugin/preset/components/manager.lua

@@ -1,7 +1,10 @@
+---@class yazi.Manager
 Manager = {
 	area = ui.Rect.default,
 }
 
+---@param area unknown
+---@return unknown[]
 function Manager:layout(area)
 	self.area = area
 
@@ -15,6 +18,8 @@ function Manager:layout(area)
 		:split(area)
 end
 
+---@param area unknown
+---@return unknown[]
 function Manager:render(area)
 	local chunks = self:layout(area)
 

yazi-plugin/preset/components/parent.lua

@@ -1,7 +1,10 @@
+---@class yazi.Parent
 Parent = {
 	area = ui.Rect.default,
 }
 
+---@param area unknown
+---@return table
 function Parent:render(area)
 	self.area = area
 

yazi-plugin/preset/components/preview.lua

@@ -1,7 +1,10 @@
+---@class yazi.Preview
 Preview = {
 	area = ui.Rect.default,
 }
 
+---@param area unknown
+---@return table
 function Preview:render(area)
 	self.area = area
 	return {}

yazi-plugin/preset/components/progress.lua

@@ -1,7 +1,11 @@
+---@class yazi.Progress
 Progress = {
 	area = ui.Rect.default,
 }
 
+---@param area unknown
+---@param offset integer
+---@return table
 function Progress:render(area, offset)
 	self.area = ui.Rect {
 		x = math.max(0, area.w - offset - 21),
@@ -18,6 +22,7 @@ end
 --
 -- However, at this time, we can only access `cx.tasks`. If you need certain data from the complete `cx`,
 -- just cache it to `self` during `render()`, and read it in `partial_render()` - this process is referred to as "composition".
+---@return table
 function Progress:partial_render()
 	local progress = cx.tasks.progress
 	if progress.total == 0 then

yazi-plugin/preset/components/status.lua

@@ -1,7 +1,9 @@
+---@class yazi.Status
 Status = {
 	area = ui.Rect.default,
 }
 
+---@return unknown
 function Status.style()
 	if cx.active.mode.is_select then
 		return THEME.status.mode_select
@@ -12,6 +14,7 @@ function Status.style()
 	end
 end
 
+---@return table
 function Status:mode()
 	local mode = tostring(cx.active.mode):upper()
 	if mode == "UNSET" then
@@ -25,6 +28,7 @@ function Status:mode()
 	}
 end
 
+---@return table
 function Status:size()
 	local h = cx.active.current.hovered
 	if not h then
@@ -38,6 +42,7 @@ function Status:size()
 	}
 end
 
+---@return table
 function Status:name()
 	local h = cx.active.current.hovered
 	if not h then
@@ -47,6 +52,7 @@ function Status:name()
 	return ui.Span(" " .. h.name)
 end
 
+---@return table
 function Status:permissions()
 	local h = cx.active.current.hovered
 	if not h then
@@ -76,6 +82,7 @@ function Status:permissions()
 	return ui.Line(spans)
 end
 
+---@return table
 function Status:percentage()
 	local percent = 0
 	local cursor = cx.active.current.cursor
@@ -99,6 +106,7 @@ function Status:percentage()
 	}
 end
 
+---@return table
 function Status:position()
 	local cursor = cx.active.current.cursor
 	local length = #cx.active.current.files
@@ -110,6 +118,8 @@ function Status:position()
 	}
 end
 
+---@param area unknown
+---@return table
 function Status:render(area)
 	self.area = area
 

yazi-plugin/preset/plugins/archive.lua

@@ -1,12 +1,14 @@
 local M = {}
 
+---@return nil
 function M:peek()
 	local _, bound = ya.preview_archive(self)
 	if bound then
 		ya.manager_emit("peek", { bound, only_if = self.file.url, upper_bound = true })
 	end
 end
 
+---@param units number
 function M:seek(units)
 	local h = cx.active.current.hovered
 	if h and h.url == self.file.url then

yazi-plugin/preset/plugins/code.lua

@@ -1,12 +1,14 @@
 local M = {}
 
+---@return nil
 function M:peek()
 	local _, bound = ya.preview_code(self)
 	if bound then
 		ya.manager_emit("peek", { bound, only_if = self.file.url, upper_bound = true })
 	end
 end
 
+---@param units number
 function M:seek(units)
 	local h = cx.active.current.hovered
 	if h and h.url == self.file.url then

yazi-plugin/preset/plugins/dds.lua

@@ -1,5 +1,6 @@
 local M = {}
 
+---@return nil
 function M:setup()
 	ps.sub_remote("dds-cd", function(url) ya.manager_emit("cd", { url }) end)
 end

yazi-plugin/preset/plugins/file.lua

@@ -1,5 +1,6 @@
 local M = {}
 
+---@return nil
 function M:peek()
 	local cmd = os.getenv("YAZI_FILE_ONE") or "file"
 	local output, code = Command(cmd):args({ "-bL", tostring(self.file.url) }):stdout(Command.PIPED):output()
@@ -16,6 +17,7 @@ function M:peek()
 	ya.preview_widgets(self, { p:wrap(ui.Paragraph.WRAP) })
 end
 
+---@return nil
 function M:seek() end
 
 return M

yazi-plugin/preset/plugins/folder.lua

@@ -1,5 +1,6 @@
 local M = {}
 
+---@return nil
 function M:peek()
 	local folder = Folder:by_kind(Folder.PREVIEW)
 	if not folder or folder.cwd ~= self.file.url then
@@ -38,6 +39,7 @@ function M:peek()
 	)
 end
 
+---@return nil
 function M:seek(units)
 	local folder = Folder:by_kind(Folder.PREVIEW)
 	if folder and folder.cwd == self.file.url then

yazi-plugin/preset/plugins/fzf.lua

@@ -1,7 +1,9 @@
 local state = ya.sync(function() return cx.active.current.cwd end)
 
+---@return nil
 local function fail(s, ...) ya.notify { title = "Fzf", content = string.format(s, ...), timeout = 5, level = "error" } end
 
+---@return nil
 local function entry()
 	local _permit = ya.hide()
 	local cwd = tostring(state())

yazi-plugin/preset/plugins/image.lua

@@ -1,5 +1,6 @@
 local M = {}
 
+---@return nil
 function M:peek()
 	local url = ya.file_cache(self)
 	if not url or not fs.cha(url) then
@@ -10,8 +11,10 @@ function M:peek()
 	ya.preview_widgets(self, {})
 end
 
+---@return nil
 function M:seek() end
 
+---@return yazi.PreloaderReturnValue
 function M:preload()
 	local cache = ya.file_cache(self)
 	if not cache or fs.cha(cache) then