refactor: organize config, improve logging/debugging(#164)

Moved config.lua to separate dir and modularized config code some

BREAKING CHANGE: Removes `use_buffer` opts from `config.log`. Will just write to log file if `use_file` is enabled and when logging meets `level` threshold. This update does make `use_file` enabled by default with a log level of `warn` so that users can at least send in debug info if problems occur. Default log file is at `vim.fn.stdpath("log")` with filename "checkmate.log" (this can be modified with `file_path` opt).

Release-As: 0.10.1

Author: bngarren

README.md

@@ -238,7 +238,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---
 ---The states that a todo item may have
 ---Default: "unchecked" and "checked"
----Note that Github-flavored Markdown specification only includes "checked" and "unchecked".
+---Note that Gith[118;1:3uub-flavored Markdown specification only includes "checked" and "unchecked".
 ---
 ---If you add additional states here, they may not work in other Markdown apps without special configuration.
 ---@field todo_states table<string, checkmate.TodoStateDefinition>
@@ -260,7 +260,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---
 ---When you change a todo's state, it can automatically update related todos based on their
 ---hierarchical relationship. Only "checked" and "unchecked" states are propagated - custom
----states remain unchanged but influence the propagation logic based on their behavior type.
+---states remain unchanged but influence the propagation logic based on their type.
 ---@field smart_toggle checkmate.SmartToggleSettings
 ---
 ---Enable/disable the todo count indicator (shows number of child todo items incomplete vs complete)
@@ -314,12 +314,13 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---@field use_file boolean
 ---
 --- The default path on-disk where log files will be written to.
---- Defaults to `~/.local/share/nvim/checkmate/current.log` (Unix) or `C:\Users\USERNAME\AppData\Local\nvim-data\checkmate\current.log` (Windows)
+--- Defaults to `vim.fn.stdpath("log") .. "checkmate.log"`
 ---@field file_path string?
 ---
---- Should print log output to a scratch buffer
---- Open with `:Checkate debug log` or `require("checkmate").debug_log()`
----@field use_buffer boolean
+--- Max file size (kilobytes)
+--- When file size exceeds max, a new file will be overwritten
+--- Default: 5120 kb (5 mb)
+---@field max_file_size? number
 
 -----------------------------------------------------
 
@@ -415,7 +416,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---When a parent should become checked
 ---i.e, how a checked child affects its parent
 ---
----Note: Custom states with "complete" behavior count as done, "incomplete" as not done,
+---Note: Custom states with "complete" type count as done, "incomplete" as not done,
 ---and "inactive" states are ignored (as if they don't exist for completion purposes).
 ---
 ---  - "all_children": When ALL descendants are complete or inactive, including nested
@@ -550,7 +551,6 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---
 ---Map of issues to diagnostic severity level
 ---@field severity table<string, vim.diagnostic.Severity>?
---- TODO: @field auto_fix boolean Auto fix on buffer write
 ---
 ---Whether to use verbose linter/diagnostic messages
 ---Default: false
@@ -562,7 +562,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ### Defaults
 ```lua
 ---@type checkmate.Config
-local defaults = {
+return {
   enabled = true,
   notify = true,
   -- Default file matching:
@@ -578,9 +578,8 @@ local defaults = {
     "*.todo.md",
   },
   log = {
-    level = "info",
-    use_file = false,
-    use_buffer = false,
+    level = "warn",
+    use_file = true,
   },
   -- Default keymappings
   keys = {

doc/checkmate.txt

@@ -1,4 +1,4 @@
-*checkmate.txt*         For Neovim >= 0.10.0         Last change: 2025 July 26
+*checkmate.txt*         For Neovim >= 0.10.0         Last change: 2025 July 28
 
 ==============================================================================
 Table of Contents                                *checkmate-table-of-contents*
@@ -300,7 +300,7 @@ Config definitions/annotations ~
     ---
     ---The states that a todo item may have
     ---Default: "unchecked" and "checked"
-    ---Note that Github-flavored Markdown specification only includes "checked" and "unchecked".
+    ---Note that Gith[118;1:3uub-flavored Markdown specification only includes "checked" and "unchecked".
     ---
     ---If you add additional states here, they may not work in other Markdown apps without special configuration.
     ---@field todo_states table<string, checkmate.TodoStateDefinition>
@@ -322,7 +322,7 @@ Config definitions/annotations ~
     ---
     ---When you change a todo's state, it can automatically update related todos based on their
     ---hierarchical relationship. Only "checked" and "unchecked" states are propagated - custom
-    ---states remain unchanged but influence the propagation logic based on their behavior type.
+    ---states remain unchanged but influence the propagation logic based on their type.
     ---@field smart_toggle checkmate.SmartToggleSettings
     ---
     ---Enable/disable the todo count indicator (shows number of child todo items incomplete vs complete)
@@ -376,12 +376,13 @@ Config definitions/annotations ~
     ---@field use_file boolean
     ---
     --- The default path on-disk where log files will be written to.
-    --- Defaults to `~/.local/share/nvim/checkmate/current.log` (Unix) or `C:\Users\USERNAME\AppData\Local\nvim-data\checkmate\current.log` (Windows)
+    --- Defaults to `vim.fn.stdpath("log") .. "checkmate.log"`
     ---@field file_path string?
     ---
-    --- Should print log output to a scratch buffer
-    --- Open with `:Checkate debug log` or `require("checkmate").debug_log()`
-    ---@field use_buffer boolean
+    --- Max file size (kilobytes)
+    --- When file size exceeds max, a new file will be overwritten
+    --- Default: 5120 kb (5 mb)
+    ---@field max_file_size? number
 
     -----------------------------------------------------
 
@@ -477,7 +478,7 @@ Config definitions/annotations ~
     ---When a parent should become checked
     ---i.e, how a checked child affects its parent
     ---
-    ---Note: Custom states with "complete" behavior count as done, "incomplete" as not done,
+    ---Note: Custom states with "complete" type count as done, "incomplete" as not done,
     ---and "inactive" states are ignored (as if they don't exist for completion purposes).
     ---
     ---  - "all_children": When ALL descendants are complete or inactive, including nested
@@ -612,7 +613,6 @@ Config definitions/annotations ~
     ---
     ---Map of issues to diagnostic severity level
     ---@field severity table<string, vim.diagnostic.Severity>?
-    --- TODO: @field auto_fix boolean Auto fix on buffer write
     ---
     ---Whether to use verbose linter/diagnostic messages
     ---Default: false
@@ -624,7 +624,7 @@ DEFAULTS ~
 
 >lua
     ---@type checkmate.Config
-    local defaults = {
+    return {
       enabled = true,
       notify = true,
       -- Default file matching:
@@ -640,9 +640,8 @@ DEFAULTS ~
         "*.todo.md",
       },
       log = {
-        level = "info",
-        use_file = false,
-        use_buffer = false,
+        level = "warn",
+        use_file = true,
       },
       -- Default keymappings
       keys = {

lua/checkmate/api.lua

@@ -42,6 +42,7 @@ function M.is_valid_buffer(bufnr)
   local ok, is_valid = pcall(vim.api.nvim_buf_is_valid, bufnr)
   if not ok or not is_valid then
     vim.notify("Checkmate: Invalid buffer", vim.log.levels.ERROR)
+    log.fmt_error("[api] Invalid buffer %d", bufnr)
     return false
   end
 
@@ -63,6 +64,7 @@ function M.setup_buffer(bufnr)
 
   -- bail early if we're not running
   if not checkmate.is_running() then
+    log.fmt_error("[api] Call to setup_buffer %d but Checkmate is NOT running", bufnr)
     return false
   end
 
@@ -76,7 +78,6 @@ function M.setup_buffer(bufnr)
 
   if config.options.linter and config.options.linter.enabled ~= false then
     local linter = require("checkmate.linter")
-    linter.setup(config.options.linter)
     linter.lint_buffer(bufnr)
   end
 
@@ -97,6 +98,8 @@ function M.setup_buffer(bufnr)
   vim.b[bufnr].checkmate_setup_complete = true
   vim.b[bufnr].checkmate_cleaned_up = false
 
+  log.fmt_debug("[api] Setup complete for bufnr %d", bufnr)
+
   return true
 end
 
@@ -154,7 +157,6 @@ function M.setup_keymaps(bufnr)
           mapping_config = vim.deepcopy(value)
         end
       else
-        log.warn(string.format("Invalid value type for key '%s'", key), { module = "api" })
       end
 
       if mapping_config and mapping_config.rhs then
@@ -201,8 +203,6 @@ function M.setup_keymaps(bufnr)
             require("checkmate").toggle_metadata(meta_name)
           end
 
-          log.debug("Mapping " .. mode .. " mode key " .. key .. " to metadata." .. meta_name, { module = "api" })
-
           buffer_map(bufnr, mode, key, rhs, desc)
           table.insert(buffer_local_keys[bufnr], { mode, key })
         end
@@ -252,7 +252,6 @@ function M.setup_autocmds(bufnr)
 
         local success = parser.convert_unicode_to_markdown(temp_bufnr)
         if not success then
-          log.error("Failed to convert Unicode to Markdown", { module = "api" })
           vim.api.nvim_buf_delete(temp_bufnr, { force = true })
           vim.notify("Checkmate: Failed to save when attemping to convert to Markdown", vim.log.levels.ERROR)
           vim.b[bufnr]._checkmate_writing = false
@@ -285,7 +284,6 @@ function M.setup_autocmds(bufnr)
             pcall(function()
               uv.fs_unlink(temp_filename)
             end)
-            log.error("Failed to rename temp file: " .. (rename_err or "unknown error"), { module = "api" })
             vim.notify("Checkmate: Failed to save file", vim.log.levels.ERROR)
             vim.bo[bufnr].modified = was_modified
             vim.b[bufnr]._checkmate_writing = false
@@ -386,7 +384,6 @@ function M.process_buffer(bufnr, process_type, reason)
   process_type = process_type or "full"
   local process_config = M.PROCESS_CONFIGS[process_type]
   if not process_config then
-    log.error("Unknown process type: " .. process_type, { module = "api" })
     return
   end
 
@@ -422,11 +419,6 @@ function M.process_buffer(bufnr, process_type, reason)
 
       local end_time = vim.uv.hrtime() / 1000000
       local elapsed = end_time - start_time
-
-      log.debug(
-        ("Buffer processed (%s) in %d ms, reason: %s"):format(process_type, elapsed, reason or "unknown"),
-        { module = "api" }
-      )
     end
 
     M._debounced_processors[bufnr][process_type] = util.debounce(process_impl, {
@@ -435,11 +427,6 @@ function M.process_buffer(bufnr, process_type, reason)
   end
 
   M._debounced_processors[bufnr][process_type]()
-
-  log.debug(
-    ("Process (%s) scheduled for buffer %d, reason: %s"):format(process_type, bufnr, reason or "unknown"),
-    { module = "api" }
-  )
 end
 
 -- Cleans up all checkmate state associated with a buffer
@@ -1115,7 +1102,6 @@ end
 function M.compute_diff_add_metadata(items, meta_name, meta_value)
   local meta_props = meta_module.get_meta_props(meta_name)
   if not meta_props then
-    log.error("Metadata type '" .. meta_name .. "' is not configured", { module = "api" })
     return {}, {}
   end
 
@@ -1727,7 +1713,6 @@ function M.archive_todos(opts)
             break
           end
         end
-        log.debug(("Found existing archive section: lines %d-%d"):format(archive_start_row + 1, archive_end_row + 1))
         break
       end
     end
@@ -1775,7 +1760,6 @@ function M.archive_todos(opts)
     util.notify("No completed todo items to archive", vim.log.levels.INFO)
     return false
   end
-  log.debug(("Found %d root todos to archive"):format(archived_root_cnt))
 
   table.sort(archived_ranges, function(a, b)
     return a.start_row < b.start_row

lua/checkmate/commands.lua

@@ -1,3 +1,5 @@
+local log = require("checkmate.log")
+
 local Commands = {}
 
 ---@class checkmate.CommandDefinition
@@ -326,6 +328,7 @@ function Commands.dispatch(opts)
         ("Usage: Checkmate %s <%s>"):format(path, table.concat(vim.tbl_keys(entry.subcommands), "|")),
         vim.log.levels.INFO
       )
+      log.fmt_warn("[commands] `%s %s` is not a valid Checkmate command", opts.name, opts.args)
       return
     end
     entry = entry.subcommands[name]