feat: Improve debug logging

## Details

After all the recent changes the current logging approach does not
capture all the necessary information at the right time.

To get all the necessary information in addition to logging nodes we'll
need to also log the marks that we produce. Doing this around the same
time as node will make it easier to understand what produced what. There
is already a function we call as we encounter new marks our own list.add.
Rename this method to add_mark and add a logging statement, now we will
be logging marks as they are generated right around the same time as
the node producing the marks, sweet.

To run at the right time we need to use the fact that most refresh cycles
are due to cursor movements so all that would get logged are option value
changes. To fix this change where the logger starts and ends to only
occur on a parse refresh. Remove logging from setting options since
this now happens outside of this cycle.

Other minor changes include:

- Add a name attribute to all log entries and change the format slightly
- Always making the name of parameters optional instead of sometimes doing
  it to the type and other times the name

Author: MeanderingProgrammer

CHANGELOG.md

@@ -40,6 +40,8 @@
 - Improve lazy.nvim instructions [#80](https://github.com/MeanderingProgrammer/markdown.nvim/pull/80)
 - Improve LaTeX compatibility [#90](https://github.com/MeanderingProgrammer/markdown.nvim/pull/90)
   [695501b](https://github.com/MeanderingProgrammer/markdown.nvim/commit/695501bd98b1f2ec052889fc4faef24dedd7091b)
+- Heading block width: [#94](https://github.com/MeanderingProgrammer/markdown.nvim/pull/94)
+  [426b135](https://github.com/MeanderingProgrammer/markdown.nvim/commit/426b13574c8264636e5660e5f5a3b4f5e3d5a937)
 
 ### Bug Fixes
 

justfile

@@ -48,6 +48,9 @@ update:
     --input-file README.md \
     --vim-version 0.10.0
 
+cat-log:
+  cat ~/.local/state/nvim/render-markdown.log
+
 gen-medium:
   just gen-file "1000" > medium.md
 

lua/render-markdown/handler/latex.lua

@@ -22,7 +22,7 @@ function M.parse(root, buf)
         return {}
     end
     if vim.fn.executable(latex.converter) ~= 1 then
-        logger.debug('Executable not found: ' .. latex.converter)
+        logger.debug('executable not found', latex.converter)
         return {}
     end
 
@@ -58,6 +58,7 @@ function M.parse(root, buf)
             virt_lines_above = true,
         },
     }
+    logger.debug('mark', latex_mark)
     return { latex_mark }
 end
 

lua/render-markdown/handler/markdown.lua

@@ -25,23 +25,23 @@ function M.parse(root, buf)
         if capture == 'heading' then
             vim.list_extend(marks, M.render_heading(buf, info))
         elseif capture == 'dash' then
-            list.add(marks, M.render_dash(buf, info))
+            list.add_mark(marks, M.render_dash(buf, info))
         elseif capture == 'code' then
             vim.list_extend(marks, M.render_code(buf, info))
         elseif capture == 'list_marker' then
             vim.list_extend(marks, M.render_list_marker(buf, info))
         elseif capture == 'checkbox_unchecked' then
-            list.add(marks, M.render_checkbox(info, state.config.checkbox.unchecked))
+            list.add_mark(marks, M.render_checkbox(info, state.config.checkbox.unchecked))
         elseif capture == 'checkbox_checked' then
-            list.add(marks, M.render_checkbox(info, state.config.checkbox.checked))
+            list.add_mark(marks, M.render_checkbox(info, state.config.checkbox.checked))
         elseif capture == 'quote' then
             local quote_query = state.markdown_quote_query
             for nested_id, nested_node in quote_query:iter_captures(info.node, buf) do
                 local nested_capture = quote_query.captures[nested_id]
                 local nested_info = ts.info(nested_node, buf)
                 logger.debug_node_info(nested_capture, nested_info)
                 if nested_capture == 'quote_marker' then
-                    list.add(marks, M.render_quote_marker(nested_info, info))
+                    list.add_mark(marks, M.render_quote_marker(nested_info, info))
                 else
                     logger.unhandled_capture('markdown quote', nested_capture)
                 end
@@ -83,10 +83,10 @@ function M.render_heading(buf, info)
             hl_eol = heading.width == 'full',
         },
     }
-    list.add(marks, background_mark)
+    list.add_mark(marks, background_mark)
 
     if heading.sign then
-        list.add(marks, M.render_sign(buf, info, list.cycle(heading.signs, level), foreground))
+        list.add_mark(marks, M.render_sign(buf, info, list.cycle(heading.signs, level), foreground))
     end
 
     if icon == nil then
@@ -112,7 +112,7 @@ function M.render_heading(buf, info)
                     conceal = '',
                 },
             }
-            list.add(marks, icon_mark)
+            list.add_mark(marks, icon_mark)
         end
     else
         ---@type render.md.Mark
@@ -127,7 +127,7 @@ function M.render_heading(buf, info)
                 virt_text_pos = 'overlay',
             },
         }
-        list.add(marks, icon_mark)
+        list.add_mark(marks, icon_mark)
     end
     return marks
 end
@@ -212,7 +212,7 @@ function M.render_code(buf, info)
                     virt_text_pos = 'overlay',
                 },
             }
-            list.add(marks, start_mark)
+            list.add_mark(marks, start_mark)
         end
         local code_end = ts.child(buf, info, 'fenced_code_block_delimiter', info.end_row - 1)
         if ts.hidden(buf, code_end) then
@@ -227,7 +227,7 @@ function M.render_code(buf, info)
                     virt_text_pos = 'overlay',
                 },
             }
-            list.add(marks, end_mark)
+            list.add_mark(marks, end_mark)
         end
     end
 
@@ -243,7 +243,7 @@ function M.render_code(buf, info)
             hl_eol = true,
         },
     }
-    list.add(marks, background_mark)
+    list.add_mark(marks, background_mark)
 
     if code.width == 'block' then
         -- Overwrite anything beyond left_pad + block width + right_pad with Normal
@@ -261,7 +261,7 @@ function M.render_code(buf, info)
                     virt_text_win_col = width,
                 },
             }
-            list.add(marks, block_background_mark)
+            list.add_mark(marks, block_background_mark)
         end
     end
 
@@ -283,7 +283,7 @@ function M.render_code(buf, info)
                 virt_text_pos = 'inline',
             },
         }
-        list.add(marks, row_padding_mark)
+        list.add_mark(marks, row_padding_mark)
     end
     return marks
 end
@@ -304,7 +304,7 @@ function M.render_language(buf, info, code_block)
     end
     local marks = {}
     if code.sign then
-        list.add(marks, M.render_sign(buf, info, icon, icon_highlight))
+        list.add_mark(marks, M.render_sign(buf, info, icon, icon_highlight))
     end
     -- Requires inline extmarks
     if not util.has_10 then
@@ -332,7 +332,7 @@ function M.render_language(buf, info, code_block)
             virt_text_pos = 'inline',
         },
     }
-    list.add(marks, language_marker)
+    list.add_mark(marks, language_marker)
     return marks
 end
 
@@ -399,7 +399,7 @@ function M.render_list_marker(buf, info)
                 virt_text_pos = 'overlay',
             },
         }
-        list.add(marks, bullet_mark)
+        list.add_mark(marks, bullet_mark)
         -- Requires inline extmarks
         if util.has_10 and bullet.right_pad > 0 then
             ---@type render.md.Mark
@@ -412,7 +412,7 @@ function M.render_list_marker(buf, info)
                     virt_text_pos = 'inline',
                 },
             }
-            list.add(marks, padding_mark)
+            list.add_mark(marks, padding_mark)
         end
         return marks
     end
@@ -472,7 +472,7 @@ end
 ---@private
 ---@param buf integer
 ---@param info render.md.NodeInfo
----@param text string?
+---@param text? string
 ---@param highlight string
 ---@return render.md.Mark?
 function M.render_sign(buf, info, text, highlight)
@@ -515,7 +515,7 @@ function M.render_table(buf, info)
         local row = ts.info(row_node, buf)
         if row.type == 'pipe_table_delimiter_row' then
             delim = row
-            list.add(marks, M.render_table_delimiter(row))
+            list.add_mark(marks, M.render_table_delimiter(row))
         elseif row.type == 'pipe_table_header' then
             first = row
             vim.list_extend(marks, M.render_table_row(buf, row, pipe_table.head))
@@ -586,7 +586,7 @@ function M.render_table_row(buf, row, highlight)
                         virt_text_pos = 'overlay',
                     },
                 }
-                list.add(marks, pipe_mark)
+                list.add_mark(marks, pipe_mark)
             elseif cell.type == 'pipe_table_cell' then
                 -- Requires inline extmarks
                 if pipe_table.cell == 'padded' and util.has_10 then
@@ -602,7 +602,7 @@ function M.render_table_row(buf, row, highlight)
                                 virt_text_pos = 'inline',
                             },
                         }
-                        list.add(marks, padding_mark)
+                        list.add_mark(marks, padding_mark)
                     end
                 end
             else
@@ -622,7 +622,7 @@ function M.render_table_row(buf, row, highlight)
                 virt_text_pos = 'overlay',
             },
         }
-        list.add(marks, overlay_mark)
+        list.add_mark(marks, overlay_mark)
     end
     return marks
 end

lua/render-markdown/handler/markdown_inline.lua

@@ -21,11 +21,11 @@ function M.parse(root, buf)
         local info = ts.info(node, buf)
         logger.debug_node_info(capture, info)
         if capture == 'code' then
-            list.add(marks, M.render_code(info))
+            list.add_mark(marks, M.render_code(info))
         elseif capture == 'callout' then
-            list.add(marks, M.render_callout(info))
+            list.add_mark(marks, M.render_callout(info))
         elseif capture == 'link' then
-            list.add(marks, M.render_link(info))
+            list.add_mark(marks, M.render_link(info))
         else
             logger.unhandled_capture('inline', capture)
         end

lua/render-markdown/health.lua

@@ -66,7 +66,7 @@ function M.version(minimum, recommended)
 end
 
 ---@param language string
----@param advice string?
+---@param advice? string
 function M.check_parser(language, advice)
     local parsers = require('nvim-treesitter.parsers')
     if parsers.has_parser(language) then
@@ -89,7 +89,7 @@ function M.check_highlight(language)
 end
 
 ---@param name string
----@param advice string?
+---@param advice? string
 function M.check_executable(name, advice)
     if vim.fn.executable(name) == 1 then
         vim.health.ok(name .. ': installed')
@@ -101,7 +101,7 @@ function M.check_executable(name, advice)
 end
 
 ---@param name string
----@param advice string[]?
+---@param advice? string[]
 function M.check_plugin(name, advice)
     local has_plugin = pcall(require, name)
     if not has_plugin then

lua/render-markdown/list.lua

@@ -1,11 +1,14 @@
+local logger = require('render-markdown.logger')
+
 ---@class render.md.ListHelper
 local M = {}
 
----@param values render.md.Mark[]
----@param value? render.md.Mark
-function M.add(values, value)
-    if value ~= nil then
-        table.insert(values, value)
+---@param marks render.md.Mark[]
+---@param new_mark? render.md.Mark
+function M.add_mark(marks, new_mark)
+    if new_mark ~= nil then
+        logger.debug('mark', new_mark)
+        table.insert(marks, new_mark)
     end
 end
 

lua/render-markdown/logger.lua

@@ -16,6 +16,7 @@ end
 ---@class render.md.LogEntry
 ---@field date string
 ---@field level string
+---@field name string
 ---@field message string
 
 ---@class render.md.Log
@@ -29,13 +30,15 @@ function log.reset()
 end
 
 ---@param level string
+---@param name string
 ---@param message any
-function log.add(level, message)
+function log.add(level, name, message)
     ---@type render.md.LogEntry
     local entry = {
         ---@diagnostic disable-next-line: assign-type-mismatch
         date = os.date('%Y-%m-%d %H:%M:%S'),
         level = string.upper(level),
+        name = name,
         message = convert_message(message),
     }
     table.insert(log.entries, entry)
@@ -47,7 +50,7 @@ function log.flush()
     end
     local file = assert(io.open(log_file, 'w'))
     for _, entry in ipairs(log.entries) do
-        local line = string.format('%s - %s - %s', entry.date, entry.level, entry.message)
+        local line = string.format('%s [%s] %s: %s', entry.date, entry.level, entry.name, entry.message)
         file:write(line .. '\n')
     end
     file:close()
@@ -61,24 +64,27 @@ function M.start()
     log.reset()
 end
 
+---@param name string
 ---@param message any
-function M.debug(message)
+function M.debug(name, message)
     if vim.tbl_contains({ 'debug' }, state.config.log_level) then
-        log.add('debug', message)
+        log.add('debug', name, message)
     end
 end
 
+---@private
+---@param name string
 ---@param message any
-function M.error(message)
+function M.error(name, message)
     if vim.tbl_contains({ 'debug', 'error' }, state.config.log_level) then
-        log.add('error', message)
+        log.add('error', name, message)
     end
 end
 
 ---@param capture string
 ---@param info render.md.NodeInfo
 function M.debug_node_info(capture, info)
-    M.debug({
+    M.debug('node info', {
         capture = capture,
         text = info.text,
         rows = { info.start_row, info.end_row },
@@ -90,15 +96,15 @@ end
 ---@param group string
 ---@param capture string
 function M.unhandled_capture(group, capture)
-    M.error(string.format('Unhandled %s capture: %s', 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(string.format('Unhandled %s %s type: %s', language, group, value))
+    M.error('unhandled type', string.format('%s -> %s -> %s', language, group, value))
 end
 
 function M.flush()

lua/render-markdown/str.lua

@@ -1,7 +1,7 @@
 ---@class render.md.StringHelper
 local M = {}
 
----@param s string?
+---@param s? string
 ---@return integer
 function M.width(s)
     if s == nil then
@@ -26,7 +26,7 @@ function M.pad_to(value, s)
 end
 
 ---@param padding integer
----@param s string?
+---@param s? string
 ---@return string
 function M.pad(padding, s)
     local result = string.rep(' ', padding)