feat(log): add possibility for debug logging to diagnose issues

The log can be enabled by specifying it in the yazi.nvim config:

```lua
-- ... other config options here
---@type YaziConfig
opts = {
  log_level = vim.log.levels.DEBUG,
},
```

Only DEBUG level is supported for now.

You can find out the location of the log file by running the following command:

```vim
:checkhealth yazi
```

lua/yazi.lua

@@ -3,6 +3,7 @@ local utils = require('yazi.utils')
 local vimfn = require('yazi.vimfn')
 local configModule = require('yazi.config')
 local event_handling = require('yazi.event_handling')
+local Log = require('yazi.log')
 
 local M = {}
 
@@ -39,7 +40,8 @@ function M.yazi(config, path)
   )
 
   if M.yazi_loaded == false then
-    -- ensure that the buffer is closed on exit
+    Log:debug(string.format('Opening yazi with the command: (%s)', cmd))
+
     local job_id = vimfn.termopen(cmd, {
       ---@diagnostic disable-next-line: unused-local
       on_exit = function(_job_id, code, _event)
@@ -76,6 +78,8 @@ function M.setup(opts)
   M.config =
     vim.tbl_deep_extend('force', configModule.default(), M.config, opts or {})
 
+  Log.level = M.config.log_level
+
   if M.config.open_for_directories == true then
     ---@param file string
     ---@param bufnr number

lua/yazi/config.lua

@@ -5,6 +5,7 @@ local M = {}
 function M.default()
   ---@type YaziConfig
   return {
+    log_level = vim.log.levels.OFF,
     open_for_directories = false,
     enable_mouse_support = false,
     open_file_function = openers.open_file,

lua/yazi/health.lua

@@ -34,6 +34,10 @@ return {
       )
     end
 
+    local logfile_location = require('yazi.log'):get_logfile_path()
+    vim.health.info('yazi.nvim log file is at ' .. logfile_location)
+    vim.health.info('    hint: use `gf` to open the file path under the cursor')
+
     vim.health.ok('yazi')
   end,
 }

lua/yazi/log.lua

@@ -0,0 +1,66 @@
+local plenary_path = require('plenary.path')
+
+---@class (exact) yazi.Log
+---@field level yazi.LogLevel
+---@field path string
+local Log = {}
+
+--- The log levels are the same as for vim.log.levels
+---@enum yazi.LogLevel
+local log_levels = {
+  TRACE = 0,
+  DEBUG = 1,
+  INFO = 2,
+  WARN = 3,
+  ERROR = 4,
+  OFF = 5,
+}
+
+---@type yazi.LogLevel
+Log.level = log_levels.OFF
+
+---@return string
+function Log:get_logfile_path()
+  local ok, stdpath = pcall(vim.fn.stdpath, 'log')
+  if not ok then
+    stdpath = vim.fn.stdpath('cache')
+  end
+  return plenary_path:new(stdpath, 'yazi.log'):absolute()
+end
+
+Log.path = Log:get_logfile_path()
+
+---@type file*? # the file handle for the log file
+local file = nil
+
+---@param level string
+---@param message string
+function Log:write_message(level, message)
+  -- initialize if needed
+  if not file then
+    local logfile, err = io.open(self.path, 'a+')
+    file = logfile
+
+    if not file then
+      local err_msg =
+        string.format('yazi.nvim: Failed to open log file at "%s"', err)
+      vim.notify(err_msg, vim.log.levels.ERROR)
+    end
+  end
+
+  if file ~= nil then
+    local timestamp = os.date('%Y-%m-%d %H:%M:%S')
+    local msg = string.format('[%s] %s %s', timestamp, level, message)
+    file:write(msg .. '\n')
+    file:flush()
+  end
+end
+
+---@param message string
+function Log:debug(message)
+  if self.level and self.level >= log_levels.DEBUG then
+    self:write_message('DEBUG', message)
+  end
+end
+
+return Log

lua/yazi/types.lua

@@ -9,6 +9,7 @@
 ---@field public floating_window_scaling_factor? float "the scaling factor for the floating window. 1 means 100%, 0.9 means 90%, etc."
 ---@field public yazi_floating_window_winblend? float "the transparency of the yazi floating window (0-100). See :h winblend"
 ---@field public yazi_floating_window_border? any "the type of border to use. See nvim_open_win() for the values your neovim version supports"
+---@field public log_level? yazi.LogLevel
 
 ---@class YaziConfigHooks
 ---@field public yazi_opened fun(preselected_path: string | nil, buffer: integer, config: YaziConfig):nil