feat: various logging improvements

## Details

Related issue: #165

It is currently difficult to figure out why a user is experiencing
problems with this plugin just not working. To improve this we need to
make some pretty large changes to how the logger works, since it
currently it only runs at a per render level. Meaning most information
is lost, i.e. we overwrite the file and we don't log anything until
we're attempting to render a file, which will not help figure out
something not working in general.

To imrove this:

- log information when attempting to attach to a buffer along with
  reasons for any skipped buffers
- doing the previous items requires updating when items are flushed to
  disk since there is no longer a convenient start and end, so instead:
  - When 1000 items have been added without being written
  - When neovim is closed
  - If the `log` command is triggered by the user
- logger is now additive, meaning we keep appending logs to the same file
- logic to prevent file from getting too large, currently hard coded to
  5 MB, after which the file is cleared
- adds `log` subcommand to quickly open log file in a new tab, similar to
  `MasonLog` and `LspLog`
- input to log is now a `vararg` of messages rather than a single item

Unrelated changes:

- renames `logger` module to `log`
- Moves `RenderMarkdown` command creation logic out of plugin directory
  and into its own module
- Small change to `in_section` logic for nodes

Author: MeanderingProgrammer

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -48,13 +48,15 @@ body:
   - type: textarea
     attributes:
       label: Plugin error log
-      description: Error log stored in vim.fn.stdpath(state)/render-markdown.log, typically ~/.local/state/nvim/render-markdown.log, if file is missing put N/A.
+      description: Error log (:RenderMarkdown log) if empty put N/A.
     validations:
       required: true
   - type: checkboxes
     attributes:
       label: Confirmations
       options:
+      - label: I have updated this plugin to the latest version using my plugin manager
+        required: true
       - label: I have provided text for all screenshots & understand that my issue will be closed if I have not
         required: true
   - type: textarea

README.md

@@ -101,6 +101,8 @@ use({
   - Can also be accessed directly through `require('render-markdown').disable()`
 - `:RenderMarkdown toggle` - Switch between enabling & disabling this plugin
   - Can also be accessed directly through `require('render-markdown').toggle()`
+- `:RenderMarkdown log` - Opens the log file for this plugin
+  - Can also be accessed directly through `require('render-markdown').log()`
 - `:RenderMarkdown expand` - Increase anti-conceal margin above and below by 1
   - Can also be accessed directly through `require('render-markdown').expand()`
 - `:RenderMarkdown contract` - Decrease anti-conceal margin above and below by 1

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*         For 0.10.0        Last change: 2024 September 13
+*render-markdown.txt*         For 0.10.0        Last change: 2024 September 14
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -132,6 +132,8 @@ PACKER.NVIM                              *render-markdown-install-packer.nvim*
     - Can also be accessed directly through `require('render-markdown').disable()`
 - `:RenderMarkdown toggle` - Switch between enabling & disabling this plugin
     - Can also be accessed directly through `require('render-markdown').toggle()`
+- `:RenderMarkdown log` - Opens the log file for this plugin
+    - Can also be accessed directly through `require('render-markdown').log()`
 - `:RenderMarkdown expand` - Increase anti-conceal margin above and below by 1
     - Can also be accessed directly through `require('render-markdown').expand()`
 - `:RenderMarkdown contract` - Decrease anti-conceal margin above and below by 1

lua/render-markdown/api.lua

@@ -1,3 +1,4 @@
+local log = require('render-markdown.core.log')
 local manager = require('render-markdown.manager')
 local state = require('render-markdown.state')
 
@@ -16,6 +17,11 @@ function M.toggle()
     manager.set_all(not state.enabled)
 end
 
+function M.log()
+    log.flush()
+    vim.cmd.tabnew(log.file)
+end
+
 function M.expand()
     state.modify_anti_conceal(1)
     M.enable()

lua/render-markdown/colors.lua

@@ -5,7 +5,6 @@ local cache = {}
 local M = {}
 
 ---@private
----@type string
 M.prefix = 'RenderMarkdown'
 
 -- stylua: ignore

lua/render-markdown/command.lua

@@ -0,0 +1,48 @@
+local api = require('render-markdown.api')
+
+---@class render.md.Command
+local M = {}
+
+---@private
+M.name = 'RenderMarkdown'
+
+---@private
+M.plugin = 'render-markdown.nvim'
+
+---Should only be called from plugin directory
+function M.setup()
+    vim.api.nvim_create_user_command(M.name, M.command, {
+        nargs = '*',
+        desc = M.plugin .. ' commands',
+        complete = function(_, cmdline)
+            if cmdline:find(M.name .. '%s+%S+%s+.*') then
+                return {}
+            elseif cmdline:find(M.name .. '%s+') then
+                return vim.tbl_keys(api)
+            else
+                return {}
+            end
+        end,
+    })
+end
+
+---@private
+---@param opts { fargs: string[] }
+function M.command(opts)
+    local args, error_message = opts.fargs, nil
+    if #args == 0 or #args == 1 then
+        local command = #args == 0 and api.enable or api[args[1]]
+        if command ~= nil then
+            command()
+        else
+            error_message = string.format('unexpected command: %s', args[1])
+        end
+    else
+        error_message = string.format('unexpected # arguments: %d', #args)
+    end
+    if error_message ~= nil then
+        vim.notify(string.format('%s: %s', M.plugin, error_message), vim.log.levels.ERROR)
+    end
+end
+
+return M

lua/render-markdown/core/context.lua

@@ -1,5 +1,5 @@
 local NodeInfo = require('render-markdown.core.node_info')
-local logger = require('render-markdown.core.logger')
+local log = require('render-markdown.core.log')
 local str = require('render-markdown.core.str')
 local util = require('render-markdown.core.util')
 
@@ -133,7 +133,7 @@ function Context:query(root, query, callback)
     for id, node in query:iter_captures(root, self.buf, self.top, self.bottom) do
         local capture = query.captures[id]
         local info = NodeInfo.new(self.buf, node)
-        logger.debug_node_info(capture, info)
+        log.debug_node_info(capture, info)
         callback(capture, info)
     end
 end

lua/render-markdown/core/list.lua

@@ -1,4 +1,4 @@
-local logger = require('render-markdown.core.logger')
+local log = require('render-markdown.core.log')
 local util = require('render-markdown.core.util')
 
 ---@class render.md.Marks
@@ -32,14 +32,14 @@ function Marks:add(conceal, start_row, start_col, opts)
         opts = opts,
     }
     if opts.virt_text_pos == 'inline' and not util.has_10 then
-        logger.error('inline marks require neovim >= 0.10.0', mark)
+        log.error('inline marks require neovim >= 0.10.0', mark)
         return false
     end
     if opts.virt_text_repeat_linebreak ~= nil and not util.has_10 then
-        logger.error('repeat linebreak marks require neovim >= 0.10.0', mark)
+        log.error('repeat linebreak marks require neovim >= 0.10.0', mark)
         return false
     end
-    logger.debug('mark', mark)
+    log.debug('mark', mark)
     table.insert(self.marks, mark)
     return true
 end

lua/render-markdown/core/log.lua

@@ -0,0 +1,107 @@
+local util = require('render-markdown.core.util')
+
+---@class render.md.log.Entry
+---@field date string
+---@field level string
+---@field name string
+---@field message string
+
+---@class render.md.Log
+---@field private level render.md.config.LogLevel
+---@field private entries render.md.log.Entry[]
+---@field file string
+local M = {}
+
+---@param level render.md.config.LogLevel
+function M.setup(level)
+    M.level = level
+    M.entries = {}
+    -- Typically resolves to ~/.local/state/nvim/render-markdown.log
+    M.file = vim.fn.stdpath('state') .. '/render-markdown.log'
+    -- Clear the file contents if it is too big
+    if util.file_size_mb(M.file) > 5 then
+        assert(io.open(M.file, 'w')):close()
+    end
+end
+
+---@param capture string
+---@param info render.md.NodeInfo
+function M.debug_node_info(capture, info)
+    M.debug('node info', {
+        capture = capture,
+        text = info.text,
+        rows = { info.start_row, info.end_row },
+        cols = { info.start_col, info.end_col },
+    })
+end
+
+---Encountered if user provides custom capture
+---@param group string
+---@param capture string
+function M.unhandled_capture(group, capture)
+    M.error('unhandled capture', string.format('%s -> %s', group, capture))
+end
+
+---Encountered if new type is seen for a particular group
+---@param language string
+---@param group string
+---@param value string
+function M.unhandled_type(language, group, value)
+    M.error('unhandled type', string.format('%s -> %s -> %s', language, group, value))
+end
+
+---@param name string
+---@param ... any
+function M.debug(name, ...)
+    if vim.tbl_contains({ 'debug' }, M.level) then
+        M.add('debug', name, ...)
+    end
+end
+
+---@param name string
+---@param ... any
+function M.error(name, ...)
+    if vim.tbl_contains({ 'debug', 'error' }, M.level) then
+        M.add('error', name, ...)
+    end
+end
+
+---@private
+---@param level render.md.config.LogLevel
+---@param name string
+---@param ... any
+function M.add(level, name, ...)
+    local messages = {}
+    local args = vim.F.pack_len(...)
+    for i = 1, args.n do
+        local message = type(args[i]) == 'string' and args[i] or vim.inspect(args[i])
+        table.insert(messages, message)
+    end
+    ---@type render.md.log.Entry
+    local entry = {
+        date = vim.fn.strftime('%Y-%m-%d %H:%M:%S'),
+        level = string.upper(level),
+        name = name,
+        message = table.concat(messages, ' | '),
+    }
+    table.insert(M.entries, entry)
+    -- Periodically flush logs to disk
+    if #M.entries > 1000 then
+        M.flush()
+    end
+end
+
+function M.flush()
+    if #M.entries == 0 then
+        return
+    end
+    local file = assert(io.open(M.file, 'a'))
+    for _, entry in ipairs(M.entries) do
+        local line = string.format('%s %s [%s] - %s', entry.date, entry.level, entry.name, entry.message)
+        file:write(line .. '\n')
+    end
+    file:close()
+    M.entries = {}
+end
+
+return M