feat(core): improve logging

Author: 3rd

lua/image/backends/kitty/helpers.lua

@@ -1,5 +1,6 @@
 local codes = require("image/backends/kitty/codes")
 local utils = require("image/utils")
+local log = require("image/utils/logger").within("backend.kitty")
 
 local uv = vim.uv
 -- Allow for loop to be used on older versions
@@ -28,7 +29,7 @@ local write = function(data, tty, escape)
 
   local payload = data
   if escape and utils.tmux.is_tmux then payload = utils.tmux.escape(data) end
-  -- utils.debug("write:", vim.inspect(payload), tty)
+  log.debug("write", { payload_len = #payload, tty = tty })
   if tty then
     local handle = io.open(tty, "w")
     if not handle then error("failed to open tty") end
@@ -70,7 +71,7 @@ end
 local write_graphics = function(config, data)
   local control_payload = ""
 
-  -- utils.debug("kitty.write_graphics()", config, data)
+  log.debug("write_graphics", { config = config, has_data = data ~= nil })
 
   for k, v in pairs(config) do
     if v ~= nil then
@@ -112,7 +113,7 @@ local write_graphics = function(config, data)
       uv.sleep(1)
     end
   else
-    -- utils.debug("kitty control payload:", control_payload)
+    log.debug("control payload", { payload = control_payload })
     write("\x1b_G" .. control_payload .. "\x1b\\", config.tty, true)
   end
 end

lua/image/backends/kitty/init.lua

@@ -1,6 +1,7 @@
 local codes = require("image/backends/kitty/codes")
 local helpers = require("image/backends/kitty/helpers")
 local utils = require("image/utils")
+local log = require("image/utils/logger").within("backend.kitty")
 
 local editor_tty = utils.term.get_tty()
 local is_SSH = (vim.env.SSH_CLIENT ~= nil) or (vim.env.SSH_TTY ~= nil)
@@ -58,7 +59,7 @@ backend.render = function(image, x, y, width, height)
     }
     if with_virtual_placeholders then transmit_payload.display_virtual_placeholder = 1 end
     helpers.write_graphics(transmit_payload, image.cropped_path)
-    -- utils.debug("[kitty] transmitted image " .. image.id .. " (" .. image.internal_id .. ")")
+    log.debug("transmitted image " .. image.id .. " (" .. image.internal_id .. ")")
   end
   if backend.features.crop then
     local preprocessing_hash = ("%s-%s"):format(image.id, image.resize_hash)
@@ -156,7 +157,7 @@ backend.render = function(image, x, y, width, height)
   backend.state.images[image.id] = image
   image.is_rendered = true
 
-  -- utils.debug("path:", image.cropped_path, display_payload)
+  log.debug("path:", { path = image.cropped_path, payload = display_payload })
 end
 
 local get_clear_tty_override = function()
@@ -188,7 +189,7 @@ backend.clear = function(image_id, shallow)
       backend.state.images[image_id] = nil
       transmitted_images[image.id] = nil
     end
-    -- utils.debug("[kitty] cleared image", image.id, "(" .. image.internal_id .. ")", "shallow:", shallow)
+    log.debug("cleared image", { id = image.id, internal_id = image.internal_id, shallow = shallow })
     return
   end
 
@@ -200,14 +201,14 @@ backend.clear = function(image_id, shallow)
     tty = get_clear_tty_override(),
   })
 
-  -- utils.debug("[kitty] cleared all")
+  log.debug("cleared all")
   for id, image in pairs(backend.state.images) do
     image.is_rendered = false
     if not shallow then
       backend.state.images[id] = nil
       transmitted_images[image.id] = nil
     end
-    -- utils.debug("[kitty] cleared image (all)", image.id, "shallow:", shallow)
+    log.debug("cleared image (all)", { id = image.id, shallow = shallow })
   end
 end
 

lua/image/backends/ueberzug.lua

@@ -1,4 +1,5 @@
 local utils = require("image/utils")
+local log = require("image/utils/logger").within("backend.ueberzug")
 
 local child = nil
 local should_be_alive = false
@@ -27,7 +28,7 @@ local spawn = function()
 
   local write = function(data)
     local serialized = vim.fn.json_encode(data)
-    -- utils.debug("ueberzug:stdin", serialized)
+    log.debug("stdin", { data = serialized })
     vim.loop.write(stdin, serialized .. "\n")
   end
 

lua/image/image.lua

@@ -1,5 +1,6 @@
 local renderer = require("image/renderer")
 local utils = require("image/utils")
+local log = require("image/utils/logger").within("image")
 
 -- { ["buf:row:col"]: { id, height } }
 ---@type table<string, { id: number, height: number }>
@@ -55,7 +56,7 @@ function Image:render(geometry)
 
   -- track last_modified and wipe cache
   local current_last_modified = vim.fn.getftime(self.original_path)
-  -- utils.debug(("timestamp: %s, last_modified: %s"):format(current_last_modified, self.last_modified))
+  log.debug(("timestamp: %s, last_modified: %s"):format(current_last_modified, self.last_modified))
   if self.last_modified ~= current_last_modified then
     self.last_modified = current_last_modified
     self.resize_hash = nil
@@ -77,18 +78,18 @@ function Image:render(geometry)
     renderer.clear_cache_for_path(self.original_path)
   end
 
-  -- utils.debug(("---------------- %s ----------------"):format(self.id))
+  log.debug(("---------------- %s ----------------"):format(self.id))
   local was_rendered = renderer.render(self)
 
-  -- utils.debug(
-  --   ("[image] success: %s x: %s, y: %s, width: %s, height: %s"):format(
-  --     was_rendered,
-  --     self.geometry.x,
-  --     self.geometry.y,
-  --     self.geometry.width,
-  --     self.geometry.height
-  --   )
-  -- )
+  log.debug(
+    ("success: %s x: %s, y: %s, width: %s, height: %s"):format(
+      was_rendered,
+      self.geometry.x,
+      self.geometry.y,
+      self.geometry.width,
+      self.geometry.height
+    )
+  )
 
   -- clear if already rendered but rendering this should be prevented
   if self.is_rendered and not was_rendered then
@@ -112,7 +113,7 @@ function Image:render(geometry)
 
       if not has_up_to_date_extmark then
         if previous_extmark ~= nil then
-          -- utils.debug(("(image.render) clearing extmark %s"):format(previous_extmark.id))
+          log.debug(("clearing extmark %s"):format(previous_extmark.id))
           vim.api.nvim_buf_del_extmark(self.buffer, self.global_state.extmarks_namespace, previous_extmark.id)
           buf_extmark_map[extmark_key] = nil
         end
@@ -128,7 +129,7 @@ function Image:render(geometry)
           extmark_opts.virt_lines = filler
         end
 
-        -- utils.debug(("(image.render) creating extmark %s"):format(self.internal_id))
+        log.debug(("creating extmark %s"):format(self.internal_id))
         local extmark_row = math.max(row or 0, 0)
         local extmark_col = math.max(col or 0, 0)
         local ok, extmark_id = pcall(
@@ -165,7 +166,7 @@ end
 
 ---@param shallow? boolean
 function Image:clear(shallow)
-  -- utils.debug(("[image] clear %s, shallow: %s"):format(self.id, shallow))
+  log.debug(("clear %s, shallow: %s"):format(self.id, shallow))
   self.global_state.backend.clear(self.id, shallow or false)
 
   self.rendered_geometry = {
@@ -262,7 +263,7 @@ local from_file = function(path, options, state)
 
   -- bail if not an image
   if not utils.magic.is_image(absolute_original_path) then
-    -- utils.debug(("image.nvim: not an image: %s"):format(absolute_original_path))
+    log.info(("not an image: %s"):format(absolute_original_path))
     return nil
   end
 
@@ -302,7 +303,7 @@ local from_file = function(path, options, state)
         namespace = opts.namespace or nil,
         last_modified = vim.fn.getftime(absolute_original_path),
       }, state)
-      -- utils.debug(("image.nvim: cloned image %s from %s"):format(clone.id, instance.id))
+      log.debug(("cloned image %s from %s"):format(clone.id, instance.id))
       return clone
     end
   end
@@ -386,7 +387,7 @@ local from_url = function(url, options, callback, state)
   }, function(code, signal)
     if code ~= 0 then
       if state.options.ignore_download_error then
-        utils.debug("image: curl errored while downloading " .. url, {
+        log.error("curl errored while downloading " .. url, {
           code = code,
           signal = signal,
         })
@@ -402,7 +403,7 @@ local from_url = function(url, options, callback, state)
 
   vim.loop.read_start(stdout, function(err, data)
     assert(not err, err)
-    if not data then utils.debug("image: downloaded " .. url .. " to " .. tmp_path) end
+    if not data then log.info("downloaded " .. url .. " to " .. tmp_path) end
     state.remote_cache[url] = tmp_path
 
     vim.defer_fn(function()

lua/image/init.lua

@@ -1,12 +1,20 @@
 local utils = require("image/utils")
 local processors = require("image/processors")
 local report = require("image/report")
+local logger = require("image/utils/logger")
+local log = logger.within("core")
 
 ---@type Options
 local default_options = {
   -- backend = "ueberzug",
   backend = "kitty",
   processor = "magick_cli",
+  debug = {
+    enabled = false,
+    level = "debug",
+    file_path = "/tmp/image.nvim.log",
+    format = "compact",
+  },
   integrations = {
     markdown = {
       enabled = true,
@@ -69,6 +77,11 @@ api.setup = function(options)
   local opts = vim.tbl_deep_extend("force", default_options, options or {})
   state.options = opts
 
+  -- setup logger with debug configuration
+  if opts.debug then
+    logger.setup(opts.debug)
+  end
+
   vim.schedule(function()
     if opts.processor == "magick_rock" then
       local magick = require("image/magick")
@@ -94,8 +107,14 @@ api.setup = function(options)
   -- load integrations
   for integration_name, integration_options in pairs(opts.integrations) do
     if integration_options.enabled then
-      local integration = require("image/integrations/" .. integration_name)
-      if type(integration.setup) == "function" then integration.setup(api, integration_options, state) end
+      log.debug("Loading integration: " .. integration_name)
+      local ok, integration = pcall(require, "image/integrations/" .. integration_name)
+      if not ok then
+        log.error("Failed to load integration: " .. integration_name, integration)
+      elseif type(integration.setup) == "function" then
+        integration.setup(api, integration_options, state)
+        log.debug("Setup integration: " .. integration_name)
+      end
     end
   end
 
@@ -192,7 +211,7 @@ api.setup = function(options)
         { topline = topline, botline = botline, bufnr = bufnr, height = height, folded_lines = folded_lines }
 
       -- execute deferred clear / rerender
-      -- utils.debug("needs_clear", needs_clear, "needs_rerender", needs_rerender)
+      log.debug("needs_clear", { needs_clear = needs_clear, needs_rerender = needs_rerender })
       vim.schedule(function()
         if needs_clear then
           for _, curr in ipairs(api.get_images({ window = winid, buffer = prev.bufnr })) do
@@ -331,7 +350,7 @@ api.setup = function(options)
         if not state.enabled then return end
 
         vim.schedule(function()
-          -- utils.debug("FocusLost")
+          log.debug("FocusLost")
           if
             state.options.editor_only_render_when_focused
             or (utils.tmux.is_tmux and utils.tmux.get_window_id() ~= initial_tmux_window_id)
@@ -357,7 +376,7 @@ api.setup = function(options)
         -- bail if not enabled
         if not state.enabled then return end
 
-        -- utils.debug("FocusGained")
+        log.debug("FocusGained")
 
         state.disable_decorator_handling = false
 

lua/image/integrations/markdown.lua

@@ -2,7 +2,7 @@ local document = require("image/utils/document")
 
 return document.create_document_integration({
   name = "markdown",
-  -- debug = true,
+  debug = true,
   default_options = {
     clear_in_insert_mode = false,
     download_remote_images = true,