feat: logging + :Rocks log command

README.md

@@ -118,6 +118,11 @@ that are no longer needed, run the `:Rocks prune [rock]` command.
 The `:Rocks edit` command opens the `rocks.toml` file for manual editing.
 Make sure to run `:Rocks sync` when you are done.
 
+### Troubleshooting
+
+The `:Rocks log` command opens a log file for the current session,
+which contains the `luarocks` stderr output, among other logs.
+
 ## :waning_crescent_moon: Lua API
 
 This plugin provides a Lua API for extensibility.

doc/rocks.txt

@@ -22,12 +22,14 @@ rocks.nvim commands                                             *rocks.commands*
  command	  	                     action
 ------------------------------------------------------------------------------
 
- install [rock] [version?]  	     install {rock} with optional {version}.
- prune [rock]                     uninstall {rock} and its stale dependencies,
+ install [rock] [version?]  	     Install {rock} with optional {version}.
+ prune [rock]                     Uninstall {rock} and its stale dependencies,
                                   and remove it from rocks.toml.
- sync                             synchronize installed rocks with rocks.toml.
- update                           search for updated rocks and install them.
- edit                             edit the rocks.toml file.
+ sync                             Synchronize installed rocks with rocks.toml.
+                                  It may take more than one sync to prune all rocks that can be pruned.
+ update                           Search for updated rocks and install them.
+ edit                             Edit the rocks.toml file.
+ log                              Open the log file.
 
 
 ==============================================================================

lua/rocks/commands.lua

@@ -14,6 +14,7 @@
 ---                                  It may take more than one sync to prune all rocks that can be pruned.
 --- update                           Search for updated rocks and install them.
 --- edit                             Edit the rocks.toml file.
+--- log                              Open the log file.
 ---
 ---@brief ]]
 ---
@@ -122,6 +123,11 @@ local rocks_command_tbl = {
             vim.cmd.e(require("rocks.config.internal").config_path)
         end,
     },
+    log = {
+        impl = function(_)
+            require("rocks.log").open_logfile()
+        end,
+    },
 }
 
 local function rocks(opts)

lua/rocks/log.lua

@@ -0,0 +1,131 @@
+---@mod rocks.log rocks.nvim logging
+---
+---@brief [[
+---
+---The internal logging interface for rocks.nvim
+---
+---@brief ]]
+
+-- Copyright (C) 2023 Neorocks Org.
+--
+-- Version:    0.1.0
+-- License:    GPLv3
+-- Created:    12 Dec 2023
+-- Updated:    12 Dec 2023
+-- Homepage:   https://github.com/nvim-neorocks/rocks.nvim
+-- Maintainer: NTBBloodbath <bloodbathalchemist@protonmail.com>
+
+local log = {
+    -- NOTE: These functions are initialised as empty for type checking purposes
+    -- and implemented later.
+    trace = function(_) end,
+    debug = function(_) end,
+    info = function(_) end,
+    warn = function(_) end,
+    error = function(_) end,
+}
+
+local LARGE = 1e9
+
+local log_date_format = "%F %H:%M:%S"
+
+local function format_log(arg)
+    return vim.inspect(arg)
+end
+
+---For now, we have a log file per session
+local logfilename = vim.fn.tempname() .. "-rocks-nvim.log"
+
+---Get the rocks.nvim log file path.
+---@return string filepath
+function log.get_logfile()
+    return logfilename
+end
+
+---Open the rocks.nvim log file.
+function log.open_logfile()
+    vim.cmd.e(log.get_logfile())
+end
+
+local logfile, openerr
+--- @private
+--- Opens log file. Returns true if file is open, false on error
+--- @return boolean
+local function open_logfile()
+    -- Try to open file only once
+    if logfile then
+        return true
+    end
+    if openerr then
+        return false
+    end
+
+    logfile, openerr = io.open(log.get_logfile(), "a+")
+    if not logfile then
+        local err_msg = string.format("Failed to open rocks.nvim log file: %s", openerr)
+        vim.notify(err_msg, vim.log.levels.ERROR)
+        return false
+    end
+
+    local log_info = vim.uv.fs_stat(log.get_logfile())
+    if log_info and log_info.size > LARGE then
+        local warn_msg =
+            string.format("rocks.nvim log is large (%d MB): %s", log_info.size / (1000 * 1000), log.get_logfile())
+        vim.notify(warn_msg, vim.log.levels.WARN)
+    end
+
+    -- Start message for logging
+    logfile:write(string.format("[START][%s] rocks.nvim logging initiated\n", os.date(log_date_format)))
+    return true
+end
+
+--- Set the log level
+--- @param level (string|integer) The log level
+--- @see vim.log.levels
+function log.set_level(level)
+    local log_levels = vim.deepcopy(vim.log.levels)
+    vim.tbl_add_reverse_lookup(log_levels)
+    if type(level) == "string" then
+        log.level = assert(log_levels[string.upper(level)], string.format("rocks.nvim: Invalid log level: %q", level))
+    else
+        assert(log_levels[level], string.format("rocks.nvim: Invalid log level: %d", level))
+        log.level = level
+    end
+    vim.lsp.set_log_level(log.level)
+end
+
+for level, levelnr in pairs(vim.log.levels) do
+    log[level:lower()] = function(...)
+        if log.level == vim.log.levels.OFF or not open_logfile() then
+            return false
+        end
+        local argc = select("#", ...)
+        if levelnr < log.level then
+            return false
+        end
+        if argc == 0 then
+            return true
+        end
+        local info = debug.getinfo(2, "Sl")
+        local fileinfo = string.format("%s:%s", info.short_src, info.currentline)
+        local parts = {
+            table.concat({ level, "|", os.date(log_date_format), "|", fileinfo, "|" }, " "),
+        }
+        for i = 1, argc do
+            local arg = select(i, ...)
+            if arg == nil then
+                table.insert(parts, "<nil>")
+            elseif type(arg) == "string" then
+                table.insert(parts, arg)
+            else
+                table.insert(parts, format_log(arg))
+            end
+        end
+        logfile:write(table.concat(parts, " "), "\n")
+        logfile:flush()
+    end
+end
+
+log.set_level(vim.log.levels.INFO)
+
+return log

lua/rocks/luarocks.lua

@@ -19,6 +19,7 @@ local luarocks = {}
 
 local constants = require("rocks.constants")
 local config = require("rocks.config.internal")
+local log = require("rocks.log")
 local nio = require("nio")
 
 ---@class LuarocksCliOpts: SystemOpts
@@ -36,23 +37,30 @@ lock.set(true) -- initialise as unlocked
 luarocks.cli = function(args, on_exit, opts)
     opts = opts or {}
     opts.synchronized = opts.synchronized ~= nil and opts.synchronized or false
-    local on_exit_wrapped = on_exit and vim.schedule_wrap(on_exit)
+    local on_exit_wrapped = vim.schedule_wrap(function(sc)
+        if opts.synchronized then
+            pcall(lock.set, true)
+        end
+        ---@cast sc vim.SystemCompleted
+        if sc.code ~= 0 then
+            log.error("luarocks CLI FAILED")
+            log.error(sc.stderr)
+        end
+        if on_exit then
+            on_exit(sc)
+        end
+    end)
     if opts.synchronized then
         lock.wait()
         lock = nio.control.future()
-        on_exit_wrapped = vim.schedule_wrap(function(...)
-            pcall(lock.set, true)
-            if on_exit then
-                on_exit(...)
-            end
-        end)
     end
     local luarocks_cmd = vim.list_extend({
         config.luarocks_binary,
         "--lua-version=" .. constants.LUA_VERSION,
         "--tree=" .. config.rocks_path,
         "--server='https://nvim-neorocks.github.io/rocks-binaries/'",
     }, args)
+    log.info(luarocks_cmd)
     return vim.system(luarocks_cmd, opts, on_exit_wrapped)
 end