chore: add LuaCATS type annotations

2 files changed, 42 insertions, 2 deletions

diff --git a/lua/muwiki/links.lua b/lua/muwiki/links.lua
index 17fed65..2972973 100644
--- a/lua/muwiki/links.lua
+++ b/lua/muwiki/links.lua
@@ -3,6 +3,16 @@ local config = require('muwiki.config')
 
 local M = {}
 
+---@class Link
+---@field text string Display text of the link
+---@field target string Link destination (URL or path)
+---@field type 'web'|'file'|'wiki' Type of link
+
+---@class Handler
+---@field name string Display name of the handler
+---@field cmd string|function Command or function to handle the URL
+---@field exts string[]? Optional list of file extensions this handler supports
+
 local function is_text_extension(ext)
   local text_exts = config.options.text_extensions or {}
   ext = ext:gsub("^%.", "")
@@ -25,6 +35,8 @@ local function get_link_type(target)
   return 'wiki'
 end
 
+---Get link information at cursor position
+---@return Link|nil link_info Table with text, target, and type, or nil if no link found
 function M.get_link()
   local cursor = vim.api.nvim_win_get_cursor(0)
 
@@ -70,6 +82,10 @@ function M.get_link()
   }
 end
 
+---Open the link under cursor
+---Uses xdg-open for web links and unmatched file:// links
+---Opens matching text_extensions in Neovim buffer
+---Wiki links always open in Neovim
 function M.open_link()
   local link = M.get_link()
   if not link then
@@ -97,6 +113,9 @@ function M.open_link()
   utils.open_in_buffer(file_path)
 end
 
+---Open link with a selectable handler from a menu
+---@param handlers Handler[] List of handler tables with name, cmd, and optional exts
+---@param link Link? Optional pre-fetched link info, will get from cursor if not provided
 function M.open_with_menu(handlers, link)
   link = link or M.get_link()
   if not link then
@@ -150,6 +169,9 @@ function M.open_with_menu(handlers, link)
   end)
 end
 
+---Create a link from visual selection
+---Converts selected text to [text](normalized_text.md)
+---Must be called in visual mode
 function M.create_link()
   local mode = vim.fn.mode()
   if mode ~= 'v' and mode ~= 'V' then
@@ -209,6 +231,8 @@ function M.create_link()
   utils.open_in_buffer(target_path)
 end
 
+---Jump to next or previous markdown link in buffer
+---@param direction 'next'|'prev' Direction to search
 function M.jump_link(direction)
   local flags = direction == 'next' and 'w' or 'bw'
   local msg = direction == 'next' and 'No more links' or 'No previous links'
diff --git a/lua/muwiki/utils.lua b/lua/muwiki/utils.lua
index c3da4eb..5330e41 100644
--- a/lua/muwiki/utils.lua
+++ b/lua/muwiki/utils.lua
@@ -2,11 +2,15 @@ local config = require('muwiki.config')
 
 local M = {}
 
+---Open a file in Neovim buffer
+---@param filepath string Absolute path to file
 function M.open_in_buffer(filepath)
   vim.cmd.edit(vim.fn.fnameescape(filepath))
 end
 
--- Lookup wiki path by name (e.g., "default" -> "~/wiki/")
+---Lookup wiki path by name
+---@param name string? Wiki name (uses first configured wiki if nil)
+---@return string|nil path Absolute path to wiki directory, or nil if not configured
 function M.wiki_path(name)
   if not config.options.dirs or #config.options.dirs == 0 then
     vim.notify('MuWiki: No dirs configured. See :help muwiki-configuration', vim.log.levels.ERROR)
@@ -25,7 +29,9 @@ function M.wiki_path(name)
   return config.options.dirs[1].path
 end
 
--- Find which wiki contains this buffer's file (cached per-buffer)
+---Find which wiki contains this buffer's file (cached per-buffer)
+---@param bufnr integer? Buffer number (defaults to 0 for current buffer)
+---@return string|nil path Absolute path to wiki root, or nil if buffer is not in a wiki
 function M.wiki_root(bufnr)
   bufnr = bufnr or 0
 
@@ -47,6 +53,8 @@ function M.wiki_root(bufnr)
   return nil
 end
 
+---Open the index file of a wiki
+---@param name string? Wiki name (uses first configured wiki if nil)
 function M.open_index(name)
   local wiki_path = M.wiki_path(name)
   if not wiki_path then
@@ -57,6 +65,10 @@ function M.open_index(name)
   M.open_in_buffer(index_path)
 end
 
+---Resolve a path to absolute normalized form
+---Strips file:// prefix and resolves relative paths against current buffer
+---@param filepath string Path to resolve (can include file://, be relative, absolute, or ~)
+---@return string Absolute normalized path
 function M.resolve(filepath)
   local path = filepath:gsub('^file://', '')
 
@@ -70,6 +82,10 @@ function M.resolve(filepath)
   return vim.fs.normalize(vim.fs.joinpath(current_dir, path))
 end
 
+---Normalize text for use as filename
+---Converts to lowercase, spaces to underscores, removes special chars
+---@param text string Text to normalize
+---@return string Normalized filename-safe text
 function M.normalize_filename(text)
   local normalized = text:lower()
   normalized = normalized:gsub('%s+', '_')