Merge pull request #39 from joshuadanpeterson/codex/create-tests-folder-and-add-tests

Add logging and config tests

Author: joshuadanpeterson

.luacheckrc

@@ -0,0 +1,2 @@
+std = 'luajit'
+read_globals = { 'vim' }

CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [v0.6.28](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.28) (2025-06-16)
+- feat: extract regex escaping to shared helper
+- test: add utils and command specs for broader coverage
+
+## [v0.6.26](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.26) (2025-06-15)
+- refactor: limit helper function scope to avoid global pollution
+
+## [v0.6.27](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.27) (2025-06-15)
+- fix: ensure search helpers remain local
+- test: verify no global leakage
+
+
+## [v0.6.25](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.25) (2025-06-15)
+- feat: allow custom log file path and document usage
+- test: cover startup, fallback, and shutdown logging
+
+[Full Changelog](https://github.com/joshuadanpeterson/typewriter.nvim/compare/v0.6.24...v0.6.25)
+
+
+## [v0.6.24](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.24) (2025-06-15)
+- feat: add warning log level and use it for regex fallback
+- test: ensure warning messages are written
+
+[Full Changelog](https://github.com/joshuadanpeterson/typewriter.nvim/compare/v0.6.23...v0.6.24)
+
+## [v0.6.23](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.23) (2025-06-15)
+- fix: ensure log directory exists and timestamp entries
+- test: cover vim.tbl_extend behaviour
+
+[Full Changelog](https://github.com/joshuadanpeterson/typewriter.nvim/compare/v0.6.22...v0.6.23)
+
+## [v0.6.22](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.22) (2025-06-15)
+- feat: log plugin shutdown on VimLeavePre
+- test: add logger specs
+
+[Full Changelog](https://github.com/joshuadanpeterson/typewriter.nvim/compare/v0.6.21...v0.6.22)
+
+## [v0.6.21](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.21) (2025-06-15)
+- feat: add logging utilities and tests
+- docs: document logging feature
+
+[Full Changelog](https://github.com/joshuadanpeterson/typewriter.nvim/compare/v0.6.20...v0.6.21)
+
 ## [v0.6.20](https://github.com/joshuadanpeterson/typewriter.nvim/tree/v0.6.20) (2025-06-14)
 - fix: restore cursor correctly when using TWTop or TWBottom
 

README.md

@@ -67,6 +67,9 @@ A Neovim plugin that emulates a typewriter, keeping the cursor centered on the s
 - Enable horizontal scrolling in Typewriter mode and center the cursor by setting `enable_horizontal_scroll` to `true` in the plugin configuration. ↔️
 - Robust state tracking with `is_typewriter_active()`, `set_typewriter_active()`, and `toggle_typewriter_active()` functions for programmatic control. 🎛️
 - `TypewriterStateChanged` event for reacting to Typewriter mode state changes in your own scripts or plugins. 🔄
+- Basic logging to `stdpath('data')/typewriter.log` for startup, shutdown, and info, warning, and error events. The log directory is created automatically, and the log path can be overridden for testing. 📝
+- Shared helper to escape regex search patterns used by Treesitter and fallback logic, avoiding duplication. 🔍
+- Search helper functions are scoped locally to keep the global namespace clean (v0.6.27). 🔒
 - Comprehensive in-editor help documentation accessible via `:help typewriter`. 📚
 
 <div align=center>

doc/typewriter.txt

@@ -369,6 +369,28 @@ local utils = require("typewriter.utils")
 local new_state = utils.toggle_typewriter_active()
 print("Typewriter mode is now: " .. (new_state and "active" or "inactive"))
 
+------------------------------------------------------------------------------
+                                                     *typewriter-logger*
+Logging utilities
+
+Typewriter.nvim writes log messages to a file located at
+`stdpath('data')/typewriter.log`. The logger provides `info`, `warning`, and `error`
+functions for debugging. The log directory is created automatically if needed,
+so messages are recorded even on first use. The log file path can be overridden
+via `require('typewriter.logger').set_log_file()` for tests or custom setups.
+
+Startup and shutdown events are logged when the plugin is loaded and when Vim
+exits, allowing you to trace the plugin lifecycle.
+Fallbacks from Treesitter or LSP to regex search are logged as warnings to
+highlight non-critical downgrades in functionality.
+Internal search helper functions are local to avoid global namespace pollution (v0.6.27).
+The regex search pattern is generated with a shared helper to ensure proper escaping.
+
+@module typewriter.logger
+@file lua/typewriter/logger.lua
+@tag typewriter-logger
+
+------------------------------------------------------------------------------
 
  vim:tw=78:ts=8:noet:ft=help:norl:
 

lua/typewriter/autocommands.lua

@@ -9,6 +9,7 @@ local commands = require("typewriter.commands")
 local ts_utils = require('nvim-treesitter.ts_utils')
 local ts_parsers = require('nvim-treesitter.parsers')
 local utils = require('typewriter.utils')
+local logger = require('typewriter.logger')
 
 local M = {}
 
@@ -22,6 +23,11 @@ local State = {
 local current_state = State.NORMAL
 local target_col = nil
 local last_line = nil
+-- Forward declare local helpers to avoid polluting the global namespace
+local move_cursor_to_combined_match
+local get_treesitter_match
+local validate_position_with_lsp
+local move_cursor_to_regex_match
 
 -- Helper function to set state
 local function set_state(new_state)
@@ -72,7 +78,7 @@ end
 --- Move cursor to the best match found using Treesitter and LSP
 ---
 --- @param search_pattern string The search pattern to match against symbols and nodes
-local function move_cursor_to_combined_match(search_pattern)
+move_cursor_to_combined_match = function(search_pattern)
 	local bufnr = vim.api.nvim_get_current_buf()
 
 	-- Treesitter Phase
@@ -89,16 +95,18 @@ local function move_cursor_to_combined_match(search_pattern)
 		end
 	end
 
-	-- Fallback to regex if both Treesitter and LSP fail
-	move_cursor_to_regex_match(bufnr, search_pattern)
+        -- Fallback to regex if both Treesitter and LSP fail. This is not a
+        -- critical error, just an alternative search path.
+        logger.warning("Falling back to regex search for pattern: " .. search_pattern)
+        move_cursor_to_regex_match(bufnr, search_pattern)
 end
 
 --- Get match position using Treesitter
 ---
 --- @param bufnr number Buffer number
 --- @param search_pattern string Search pattern
 --- @return table|nil Cursor position
-local function get_treesitter_match(bufnr, search_pattern)
+get_treesitter_match = function(bufnr, search_pattern)
 	local lang = ts_parsers.get_buf_lang(bufnr)
 	if not lang then
 		return nil
@@ -125,8 +133,8 @@ local function get_treesitter_match(bufnr, search_pattern)
 		return nil
 	end
 
-	-- Preprocess the search pattern to handle special characters and word boundaries
-	local regex_pattern = string.format("\\b%s\\b", search_pattern:gsub("[%^%$%(%)%%%.%[%]%*%+%-%?]", "%%%0"))
+        -- Preprocess the search pattern to handle special characters and word boundaries
+        local regex_pattern = utils.create_escaped_regex_pattern(search_pattern)
 
 	-- Iterate over captures and match against the search pattern
 	local cursor_position
@@ -175,7 +183,7 @@ local function validate_lsp_symbols(position, search_pattern, symbols)
         return nil
 end
 
-local function validate_position_with_lsp(position, search_pattern)
+validate_position_with_lsp = function(position, search_pattern)
         local bufnr = vim.api.nvim_get_current_buf()
         local params = { textDocument = vim.lsp.util.make_text_document_params() }
 
@@ -200,9 +208,9 @@ end
 ---
 --- @param bufnr number Buffer number
 --- @param search_pattern string Search pattern
-local function move_cursor_to_regex_match(bufnr, search_pattern)
-	local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
-	local regex_pattern = string.format("\\b%s\\b", search_pattern:gsub("[%^%$%(%)%%%.%[%]%*%+%-%?]", "%%%0"))
+move_cursor_to_regex_match = function(bufnr, search_pattern)
+        local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
+        local regex_pattern = utils.create_escaped_regex_pattern(search_pattern)
 
 	for line_num, line in ipairs(lines) do
 		local start_pos = line:find(regex_pattern)
@@ -330,22 +338,29 @@ function M.autocmd_setup()
 	end
 
 	-- Autocommands for True Zen integration
-	if config.config.enable_with_true_zen then
-		vim.api.nvim_create_autocmd("User", {
-			pattern = "TZWoon",
-			callback = function()
-				commands.enable_typewriter_mode()
-			end,
-			desc = "Enable Typewriter mode when entering True Zen",
-		})
-		vim.api.nvim_create_autocmd("User", {
-			pattern = "TZOff",
-			callback = function()
-				commands.disable_typewriter_mode()
-			end,
-			desc = "Disable Typewriter mode when leaving True Zen",
-		})
-	end
+        if config.config.enable_with_true_zen then
+                vim.api.nvim_create_autocmd("User", {
+                        pattern = "TZWoon",
+                        callback = function()
+                                commands.enable_typewriter_mode()
+                        end,
+                        desc = "Enable Typewriter mode when entering True Zen",
+                })
+                vim.api.nvim_create_autocmd("User", {
+                        pattern = "TZOff",
+                        callback = function()
+                                commands.disable_typewriter_mode()
+                        end,
+                        desc = "Disable Typewriter mode when leaving True Zen",
+                })
+        end
+
+        -- Log plugin shutdown
+        vim.api.nvim_create_autocmd("VimLeavePre", {
+                callback = function()
+                        logger.info("Typewriter.nvim shutdown")
+                end,
+        })
 end
 
 return M

lua/typewriter/commands.lua

@@ -12,6 +12,7 @@ local ts_utils = require("nvim-treesitter.ts_utils")
 local utils = require("typewriter.utils")
 local config = require("typewriter.config")
 local center_block_config = require("typewriter.utils.center_block_config")
+local logger = require("typewriter.logger")
 
 local M = {}
 local typewriter_active = false
@@ -74,7 +75,8 @@ function M.enable_typewriter_mode()
 				utils.center_cursor_horizontally()
 			end,
 		})
-		utils.notify("Typewriter mode enabled")
+                utils.notify("Typewriter mode enabled")
+                logger.info("Typewriter mode enabled")
 	end
 end
 
@@ -92,6 +94,7 @@ function M.disable_typewriter_mode()
                 vim.fn.winrestview({ leftcol = 0 })
 		--- Notify the user that typewriter mode is disabled
                 utils.notify("Typewriter mode disabled")
+                logger.info("Typewriter mode disabled")
         end
 end
 

lua/typewriter/init.lua

@@ -18,6 +18,7 @@
 --- Import required modules
 --- local config = require("typewriter.config")
 --- local autocommands = require("typewriter.autocommands")
+local logger = require("typewriter.logger")
 local M = {}
 
 --- Setup the Typewriter.nvim plugin
@@ -40,6 +41,7 @@ M.setup = function(user_config)
         config.config_setup(user_config or {})
         autocommands.autocmd_setup()
         require("typewriter.utils").notify("Typewriter.nvim started")
+        logger.info("Typewriter.nvim started")
 end
 
 return M

lua/typewriter/logger.lua

@@ -0,0 +1,55 @@
+--- Simple file-based logger for Typewriter.nvim
+---
+--- Provides basic functions to log info, warning, and error messages
+--- to a file located in Neovim's stdpath('data') directory.
+
+local log_file = vim.fn.stdpath('data') .. '/typewriter.log'
+
+local M = {}
+
+--- Set a custom log file path
+--
+-- Allows tests or users to override the default location.
+-- The directory of the provided path will be created automatically
+-- when writing messages.
+-- @param path string new log file path
+function M.set_log_file(path)
+  log_file = path
+end
+
+--- Get the current log file path
+-- @return string
+function M.get_log_file()
+  return log_file
+end
+
+
+--- Append a log message to the log file, creating the directory if needed.
+-- @param level string log level label
+-- @param msg string message to write
+local function write(level, msg)
+  local dir = vim.fn.fnamemodify(log_file, ':h')
+  -- Ensure the log directory exists to prevent failures on first run
+  vim.fn.mkdir(dir, 'p')
+
+  local ok, file = pcall(io.open, log_file, 'a')
+  if ok and file then
+    local line = string.format('%s [%s] %s\n', os.date('%Y-%m-%d %H:%M:%S'), level, msg)
+    file:write(line)
+    file:close()
+  end
+end
+
+function M.info(msg)
+  write('INFO', msg)
+end
+
+function M.warning(msg)
+  write('WARNING', msg)
+end
+
+function M.error(msg)
+  write('ERROR', msg)
+end
+
+return M

lua/typewriter/utils.lua

@@ -15,6 +15,19 @@ local typewriter_active = false
 
 local M = {}
 
+--- Create a Lua pattern escaped for regex search
+--
+-- This helper escapes special characters in a search pattern and wraps
+-- it with word boundaries so it can be used safely in Lua pattern
+-- matching.
+--
+-- @param pattern string search text provided by the user
+-- @return string escaped Lua pattern wrapped with %b
+function M.create_escaped_regex_pattern(pattern)
+        local escaped = pattern:gsub('[%^%$%(%)%%%.%[%]%*%+%-%?]', '%%%0')
+        return string.format('\\b%s\\b', escaped)
+end
+
 --- Notify the user with a message if notifications are enabled
 ---
 --- This function displays a notification to the user using Neovim's built-in

spec/spec_helper.lua

@@ -3,11 +3,43 @@ package.path = package.path .. ';./lua/?.lua;./lua/?/init.lua'
 -- Minimal vim stub for tests running outside Neovim
 _G.vim = _G.vim or {}
 vim.api = vim.api or {}
+vim.fn = vim.fn or {}
 vim.api.nvim_exec_autocmds = vim.api.nvim_exec_autocmds or function() end
 vim.api.nvim_win_set_cursor = vim.api.nvim_win_set_cursor or function() end
 vim.api.nvim_win_get_cursor = vim.api.nvim_win_get_cursor or function() return {1,0} end
+vim.api.nvim_create_autocmd = vim.api.nvim_create_autocmd or function() end
+vim.api.nvim_create_augroup = vim.api.nvim_create_augroup or function() return 1 end
+vim.api.nvim_clear_autocmds = vim.api.nvim_clear_autocmds or function() end
+vim.api.nvim_win_set_option = vim.api.nvim_win_set_option or function() end
+vim.api.nvim_win_get_width = vim.api.nvim_win_get_width or function() return 80 end
+vim.api.nvim_command = vim.api.nvim_command or function() end
+vim.api.nvim_create_user_command = vim.api.nvim_create_user_command or function() end
 vim.cmd = vim.cmd or function() end
 vim.schedule = vim.schedule or function(fn) fn() end
 vim.log = vim.log or { levels = { INFO = 1 } }
 vim.notify = vim.notify or function() end
+vim.v = vim.v or {}
+vim.fn.stdpath = vim.fn.stdpath or function() return '/tmp' end
+vim.fn.fnamemodify = vim.fn.fnamemodify or function(path, mod)
+  if mod == ':h' then
+    return path:match('(.+)/[^/]*$') or '.'
+  end
+  return path
+end
+vim.fn.mkdir = vim.fn.mkdir or function() end
+vim.fn.virtcol = vim.fn.virtcol or function() return 1 end
+vim.fn.winrestview = vim.fn.winrestview or function() end
+vim.tbl_extend = vim.tbl_extend or function(_, ...)
+  local result = {}
+  -- Use pairs to iterate over the provided tables so keys of any type
+  -- are copied, matching the behaviour of real vim.tbl_extend.
+  for _, t in pairs{...} do
+    if type(t) == "table" then
+      for k, v in pairs(t) do
+        result[k] = v
+      end
+    end
+  end
+  return result
+end
 return {}