feat(utils): add type annotations and inline documentation to various utility modules

lua/data/init.lua

@@ -1,13 +1,25 @@
+---@module "data"
+--- This module aggregates various utility modules used throughout the configuration.
+--- It provides a centralized way to access keymaps, data types, utility functions, commands, and dashboard utilities.
+
 local keys = require("data.keys")
 local types = require("data.types")
 local func = require("data.func")
 local cmd = require("data.cmd")
+local deps = require("data.deps")
 local dash = require("data.dash")
 
-return {
+---@alias DataModule
+---| { keys: table, types: table, func: table, cmd: table, deps: table, dash: table }
+
+---@type DataModule
+local data = {
   keys = keys,
   types = types,
   func = func,
   cmd = cmd,
+  deps = deps,
   dash = dash,
 }
+
+return data

lua/utils/blinky.lua

@@ -1,13 +1,24 @@
 local M = {}
 
--- Function to set up blinky cursor
+--- Function to set up blinky cursor
+---@return boolean state true if the cursor is enabled, false otherwise
 function M.enable()
+  -- Set the cursor to a blinking state
   vim.opt.guicursor = {
     "n-v-c:block-Cursor/lCursor", -- Block cursor in normal, visual, and command modes
     "i:ver25-blinkwait700-blinkoff400-blinkon250-Cursor/lCursor", -- Blinking vertical line in insert mode
     "r-cr-o:hor20-Cursor/lCursor", -- Horizontal line cursor in replace, command-line replace, and operator-pending modes
     "a:blinkwait700-blinkoff400-blinkon250", -- Global blinking settings for all modes
   }
+  return true
+end
+
+--- Function to disable blinky cursor
+---@return boolean state true if the cursor is enabled, false otherwise
+function M.disable()
+  -- Set the cursor to a non-blinking state
+  vim.opt.guicursor = "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20"
+  return false
 end
 
 return M

lua/utils/cache_stats.lua

@@ -5,14 +5,14 @@
 local M = {}
 
 -- Path to the cache script
-local config_dir = vim.fn.stdpath("config")
+local config_dir = vim.fn.stdpath("config") --[[@as string]]
----@diagnostic disable-next-line: param-type-mismatch
+local cache_script = vim.fs.joinpath(config_dir, "scripts", "update_cache.sh")
-local cache_script = vim.fs.joinpath(config_dir, "/scripts/update_cache.sh")
 
 -- Flag to check if the script has already been run
 local script_run_once = false
 
--- Function to run the cache update script using vim.system
+--- Function to run the cache script
+---@return nil
 function M.setup_script()
   if not script_run_once then
     -- Run the cache script

lua/utils/git.lua

@@ -1,7 +1,13 @@
+---@module "utils.git"
+--- This module provides functions to interact with GitGraph within Neovim.
+--- It includes functions to draw, close, and toggle the GitGraph tab.
+
 local M = {}
 
+--- Opens the GitGraph in a new tab if it's not already open.
+--- @return nil
 function M.gitgraph_draw()
-  -- open gitgraph in a seperate tab
+  -- Open gitgraph in a separate tab
   if vim.bo.filetype == "gitgraph" then
     return
   end
@@ -9,8 +15,10 @@ function M.gitgraph_draw()
   require("gitgraph").draw({}, { all = true, max_count = 5000 })
 end
 
+--- Closes the tab page if it is a GitGraph page.
+--- @return nil
 function M.gitgraph_close()
-  --- close the tab page if it is a gitgraph page
+  -- Close the tab page if it is a gitgraph page
   if vim.bo.filetype == "gitgraph" then
     vim.cmd("tabclose")
   else
@@ -18,8 +26,10 @@ function M.gitgraph_close()
   end
 end
 
+--- Toggles the GitGraph tab. Opens it if not already open, and closes it if it is.
+--- @return nil
 function M.gitgraph_toggle()
-  -- toggle gitgraph
+  -- Toggle gitgraph
   if vim.bo.filetype == "gitgraph" then
     M.gitgraph_close()
   else

lua/utils/highlight.lua

@@ -1,18 +1,23 @@
 --          ╭─────────────────────────────────────────────────────────╮
 --          │                        Highlight                        │
 --          ╰─────────────────────────────────────────────────────────╯
+---@module "utils.highlight"
+--- This module provides functions to apply highlights to the statusline and other components.
+
 local M = {}
 
 -- Load utils
-local utils = require("utils.rootiest")
 local data = require("data")
+local funcs = data.func
 -- Readability functions
-local get_bg_color = utils.get_bg_color
+local get_bg_color = funcs.get_bg_color
-local get_fg_color = utils.get_fg_color
+local get_fg_color = funcs.get_fg_color
 local set_hl = vim.api.nvim_set_hl
 local sign_def = vim.fn.sign_define
 
--- Function to apply the todo highlights
+--- Function to apply the todo highlights
+---@param status_string string The todo status string
+---@return string The updated status string with the todo highlights
 function M.apply_todo_highlights(status_string)
   -- Define patterns and associated highlight groups
   local patterns = {
@@ -37,7 +42,8 @@ function M.apply_todo_highlights(status_string)
   return status_string
 end
 
--- Function to set up indent highlights
+--- Function to set up indent highlights
+---@return nil
 function M.setup_indent_highlight()
   -- Get the background color of CursorLine
   local cursorline_bg_hex = get_bg_color("CursorLine")
@@ -114,7 +120,8 @@ function M.setup_indent_highlight()
   vim.cmd(":set colorcolumn=120")
 end
 
--- Function to set up mode highlights
+--- Function to set up smooth cursor mode highlights
+---@return nil
 function M.setup_mode_highlight()
   local current_mode = vim.fn.mode()
   local bg_color -- Define bg_color variable
@@ -145,7 +152,8 @@ function M.setup_mode_highlight()
   end
 end
 
--- Function to set up dashboard header highlight
+--- Function to set up dashboard header highlight
+---@return nil
 function M.setup_dashboard_highlight()
   if not vim.g.DashboardHeaderColor then
     local dash_color = get_fg_color("Error")
@@ -155,7 +163,8 @@ function M.setup_dashboard_highlight()
   end
 end
 
--- Set up transparency
+--- Function to set up transparency of the editor
+---@return nil
 function M.setup_transparency()
   if data.func.is_kitty() and not vim.g.disable_transparency then
     vim.cmd("TransparentEnable")
@@ -164,7 +173,8 @@ function M.setup_transparency()
   end
 end
 
--- Setup autocommands to update on InsertEnter and ColorScheme events
+--- Function to set up autocommands
+---@return nil
 function M.setup_autocommands()
   local autogrp = vim.api.nvim_create_augroup
   local autocmd = vim.api.nvim_create_autocmd

lua/utils/indentor.lua

@@ -1,5 +1,10 @@
+---@module "utils.indentor"
+--- This module provides functions to insert indentation at the start of a line.
+
 local M = {}
 
+--- Get the indentation level from the previous line
+---@return integer level The indentation level
 local function get_previous_line_indentation()
   -- Get the current cursor position
   local current_line, _ = unpack(vim.api.nvim_win_get_cursor(0))
@@ -20,6 +25,8 @@ local function get_previous_line_indentation()
   return #indentation
 end
 
+--- Insert the previous line's indentation at the start of the current line
+---@return boolean inserted true if the indentation was inserted, false otherwise
 function M.insert_previous_line_indentation()
   -- Get the cursor column position
   local _, col = unpack(vim.api.nvim_win_get_cursor(0))
@@ -31,6 +38,7 @@ function M.insert_previous_line_indentation()
 
     -- Insert the same number of spaces at the start of the current line
     vim.api.nvim_put({ string.rep(" ", indentation_level) }, "c", true, true)
+    return true
   else
     -- Insert a tab (or spaces if 'expandtab' is set)
     vim.api.nvim_feedkeys(
@@ -38,13 +46,19 @@ function M.insert_previous_line_indentation()
       "n",
       true
     )
+    return false
   end
 end
 
--- Create a keymap to trigger the function
+--- Create keymaps for the module
-local data = require("data")
+---@return nil
-for _, map in ipairs(data.keys.indentor) do
+function M.setup()
-  data.func.add_keymap(map[1], map[2], map[3], map[4])
+  -- Load the data module
+  local data = require("data")
+  -- Create keymaps
+  for _, map in ipairs(data.keys.indentor) do
+    data.func.add_keymap(map[1], map[2], map[3], map[4])
+  end
 end
 
 return M

lua/utils/init.lua

@@ -1,17 +1,25 @@
+---@module "utils"
+--- This module aggregates various utility functions used across the configuration.
+--- It provides access to caching mechanisms, Git utilities, WakaTime statistics, music status, highlighting utilities, and a blinking effect utility.
+
 local cache = require("utils.cache_stats")
 local git = require("utils.git")
 local wakatime = require("utils.wakatime_stats")
 local music = require("utils.music_stats")
 local highlight = require("utils.highlight")
-local rootiest = require("utils.rootiest")
 local blinky = require("utils.blinky")
 
-return {
+---@alias UtilsModule
+---| { cache_stats: table, git: table, wakatime_stats: table, music_stats: table, highlight: table, blinky: table }
+
+---@type UtilsModule
+local utils = {
   cache_stats = cache,
   git = git,
   wakatime_stats = wakatime,
   music_stats = music,
   highlight = highlight,
-  rootiest = rootiest,
   blinky = blinky,
 }
+
+return utils

lua/utils/music_stats.lua

@@ -9,7 +9,8 @@ local cache_file = os.getenv("HOME") .. "/.cache/music_cache.txt"
 local separator = "␟"
 local last_known_value = ""
 
--- Function to read the cache file
+--- Function to read the cache file
+---@return string content The content of the cache file
 local function read_cache()
   local file = io.open(cache_file, "r")
   if file then
@@ -21,7 +22,14 @@ local function read_cache()
   return last_known_value -- Return last known value if file cannot be read
 end
 
--- Parse the cached music data
+--- Function to parse the cache file
+---@return string artist The artist
+---@return string title The title
+---@return string album The album
+---@return string status The play status
+---@return string volume The volume level
+---@return string loop The loop state
+---@return string shuffle The shuffle state
 local function parse_cache()
   local content = read_cache()
   if
@@ -55,6 +63,8 @@ local function parse_cache()
     shuffle or ""
 end
 
+--- Function to get the play status
+---@return string status The play status
 function M.get_status()
   local _, _, _, status = parse_cache()
   if status:match("Playing") then
@@ -66,10 +76,20 @@ function M.get_status()
   end
 end
 
+--- --- Function to get the current stats
+---@return string artist The artist
+---@return string title The title
+---@return string album The album
+---@return string status The play status
+---@return string volume The volume level
+---@return string loop The loop state
+---@return string shuffle The shuffle state
 function M.get_current()
   return parse_cache()
 end
 
+--- Function to get the music icon
+---@return string icon The music icon
 function M.get_icon()
   local _, _, _, status = parse_cache()
   if status == "Playing" then
@@ -81,42 +101,59 @@ function M.get_icon()
   end
 end
 
+--- Function to get the music title
+---@return string title The music title
 function M.get_title()
   local _, title = parse_cache()
   return title
 end
 
+--- Function to get the music artist
+---@return string artist The music artist
 function M.get_artist()
   local artist = parse_cache()
   return artist
 end
 
+--- Function to get the music album
+---@return string album The music album
 function M.get_album()
   local _, _, album = parse_cache()
   return album
 end
 
+--- Function to get the music volume
+---@return number volume The music volume
 function M.get_volume()
   local _, _, _, _, volume = parse_cache()
   return tonumber(volume) or 0.0
 end
 
+--- Function to get the music shuffle state
+---@return boolean shuffle The music shuffle state
 function M.is_shuffle()
   local _, _, _, _, _, _, shuffle = parse_cache()
   return shuffle == "On"
 end
 
+--- Function to get the music loop state
+---@return boolean loop The music loop state
 function M.is_loop()
   local _, _, _, _, _, loop = parse_cache()
   return loop ~= "None" and loop ~= "false"
 end
 
--- Function to remove text inside parentheses, including the parentheses themselves
+--- Function to remove parentheses and their contents
+---@param text string The text to remove parentheses from
+---@return string text The text with parentheses removed
+---@return integer count The number of parentheses removed
 local function remove_parentheses(text)
   return text:gsub("%b()", "")
 end
 
--- Function to abbreviate common words or phrases
+--- Function to abbreviate common words or phrases
+---@param text string The text to abbreviate
+---@return string text The abbreviated text
 local function abbreviate(text)
   local replacements = {
     ["feat%.?%s"] = "ft. ",
@@ -130,7 +167,10 @@ local function abbreviate(text)
   return text
 end
 
--- Function to strip unnecessary words or phrases
+--- Function to strip unnecessary words or phrases
+---@param text string The text to strip
+---@return string text The stripped text
+---@return integer count The number of instances removed
 local function strip_redundant(text)
   local redundant_phrases =
     { "Radio Edit", "Extended Version", "Remix", "Instrumental", "Live" }
@@ -140,7 +180,10 @@ local function strip_redundant(text)
   return text:gsub("%s+", " "):gsub("^%s*(.-)%s*$", "%1") -- Clean up any extra spaces
 end
 
--- Function to limit the number of words in the text
+--- Function to limit the number of words in the text
+---@param text string The text to limit
+---@param max_words integer The maximum number of words
+---@return string text The limited text
 local function limit_words(text, max_words)
   local words = vim.split(text, "%s+")
   if #words > max_words then
@@ -149,7 +192,9 @@ local function limit_words(text, max_words)
   return text
 end
 
--- Function to remove duplicate words
+--- Function to remove duplicate words
+---@param text string The text to remove duplicates from
+---@return string text The text with duplicates removed
 local function remove_duplicates(text)
   local seen = {}
   local result = {}
@@ -162,12 +207,13 @@ local function remove_duplicates(text)
   return table.concat(result, " ")
 end
 
--- Function to shorten text based on delimiters
+--- Function to shorten the text
+---@param text string The text to shorten
+---@return string text The shortened text
 local function shorten_text(text)
   if #text <= 25 then
     return text
   end
-
   local delimiters = { ",", "-", ":" }
   for _, delimiter in ipairs(delimiters) do
     local parts = vim.split(text, delimiter)
@@ -185,7 +231,9 @@ local function shorten_text(text)
   return text
 end
 
--- Combine all simplification functions
+--- Function to simplify text
+---@param text string The text to simplify
+---@return string text The simplified text
 local function simplify_text(text)
   text = remove_parentheses(text)
   text = strip_redundant(text)
@@ -196,6 +244,11 @@ local function simplify_text(text)
   return text
 end
 
+--- Function to format the icon with text
+---@param icon string The icon
+---@param artist string The artist
+---@param title string The title
+---@return string formatted_icon_with_text The formatted icon and text
 local function format_icon_with_text(icon, artist, title)
   if artist and #artist > 25 then
     return icon .. " " .. title
@@ -208,6 +261,8 @@ local function format_icon_with_text(icon, artist, title)
   end
 end
 
+--- Function to get the icon with text
+---@return string icon_with_text The icon and text
 function M.get_icon_with_text()
   local icon = M.get_icon()
   local title = M.get_title()

lua/utils/wakatime_stats.lua

@@ -6,8 +6,11 @@ local M = {}
 require("utils.cache_stats")
 local cache_file = os.getenv("HOME") .. "/.cache/wakatime_cache.txt"
 
+-- Local variable to store the last known value
 local last_known_value = ""
 
+--- Function to read the cache file
+---@return string content The content of the cache file
 local function read_cache()
   local file = io.open(cache_file, "r")
   if file then
@@ -19,26 +22,30 @@ local function read_cache()
   return last_known_value
 end
 
+--- Function to get the wakatime today cache
+---@return string status The wakatime today cache
 local function get_wakatime_today()
   local result = read_cache()
   if not result or result:match("^%s*$") then
     return last_known_value
   end
-
   if
     result:match("command not found")
     or result:match("No such file or directory")
   then
     return last_known_value
   end
-
   return result:match("^%s*(.-)%s*$") -- Trim any whitespace
 end
 
+--- Function to get the wakatime today status
+---@return string status The wakatime today status
 function M.get_today()
   return get_wakatime_today()
 end
 
+--- Function to get the wakatime today icon
+---@return string icon The wakatime today icon
 function M.get_icon()
   local text = M.get_today()
   if text ~= "" then
@@ -48,6 +55,8 @@ function M.get_icon()
   end
 end
 
+--- Function to get the wakatime today icon and text
+---@return string icon_and_text The wakatime today icon and text
 function M.get_icon_with_text()
   local icon = M.get_icon()
   local text = M.get_today()
@@ -58,28 +67,30 @@ function M.get_icon_with_text()
   end
 end
 
+--- Function to get the total minutes
+---@return number total_minutes The total minutes
 function M.get_total_minutes()
   local wakatime_string = M.get_today()
   if wakatime_string == "" then
     return 0 -- Return 0 if there's no data
   end
-
+  -- Extract hours and minutes from the wakatime string
   local hours, mins = wakatime_string:match("(%d+)%s*hrs?%s*(%d+)%s*mins?")
   if not hours then
     mins = wakatime_string:match("(%d+)%s*mins?")
     hours = 0
   end
-
+  -- Convert hours and minutes to total minutes
   hours = tonumber(hours) or 0
   mins = tonumber(mins) or 0
-
   return (hours * 60) + mins
 end
 
+--- Function to get the color based on the total minutes
+---@return table color The color based on the total minutes
 function M.get_color()
   local total_minutes = M.get_total_minutes()
-  local utils = require("utils.rootiest") -- Adjust according to your actual setup
+  local utils = require("data").func
-
   if total_minutes >= 60 then
     return { fg = utils.get_fg_color("GitSignsAdd") }
   elseif total_minutes >= 30 then