fix!: show debug msg only when debug is true (#220)

* docs: fix the format for some docs

* fix!: show debug msg only when `debug` is `true`

Fix #212

* test: enable debug logging in tests

doc/telescope-frecency.txt

@@ -281,24 +281,24 @@ plugin. See |telescope-frecency-combining-results-outside-this-plugin|.
 
 Options:			     *telescope-frecency-function-query-options*
 			   *telescope-frecency-function-query-options-direction*
-  - `direction`	type: `"asc"|"desc"`
+  - `direction`	Default: `"desc"
-		default: `"desc"`
+		`Type: `"asc"|"desc"`
 		This specifies the order direction for results.
 			       *telescope-frecency-function-query-options-limit*
-  - `limit`	type: `integer`
+  - `limit`	Default: `100
-		default: `100`
+		`Type: `integer`
 		This limits the number of results.
 			       *telescope-frecency-function-query-options-order*
-  - `order`	type: `"count"|"path"|"score"|"timestamps"`
+  - `order`	Default: `"score"
-		default: `"score"`
+		`Type: `"count"|"path"|"score"|"timestamps"`
 		This is used to sort results with their properties. With
 		`"count"`, `"score"` and `"timestamps"`, when candidates have the
 		same value, they will be sorted by `"path"` always ascendingly.
 		With `"path"`, the order direction differs by the value of
 		`direction`.
 			      *telescope-frecency-function-query-options-record*
-  - `record`	type: `boolean`
+  - `record`	Default: `false
-		default: `false`
+		Type: `boolean`
 		If `false`, it returns results containing filenames with
 		absolute paths. If `true`, it contains tables with this
 		properties below.
@@ -308,8 +308,8 @@ Options:			     *telescope-frecency-function-query-options*
 		`score`: Recency score to be used in frecency picker.
 		`timestamps`: UNIX timestamps that the file has been opened at.
 			   *telescope-frecency-function-query-options-workspace*
-  - `workspace`	type: `string?`
+  - `workspace`	`Default: `nil`
-		default: `nil`
+		Type: `string?
 		This applies |telescope-frecency-introduction-workspace-filter|
 		into query results. You can limit candidates to ones that
 		exist below the directory specified this value. See also
@@ -391,6 +391,19 @@ Type: `integer`
 
 It will remove entries when stale ones exist more than this count.
 
+					*telescope-frecency-configuration-debug*
+debug ~
+
+Default: `false`
+Type: `boolean`
+
+This plugin uses `plenary.log` to log debugging messages. You should set this to
+`true` and set environmental variable `DEBUG_PLENARY` to see debug messages.
+>bash
+    # Launch Neovim with DEBUG_PLENARY=1 and set `debug = true` and you can
+    # see debug messages.
+    env DEBUG_PLENARY=1 nvim
+
 			    *telescope-frecency-configuration-default_workspace*
 default_workspace ~
 

lua/frecency/config.lua

@@ -7,6 +7,7 @@ local os_util = require "frecency.os_util"
 ---@field db_root? string default: vim.fn.stdpath "state"
 ---@field db_safe_mode? boolean default: true
 ---@field db_validate_threshold? integer default: 10
+---@field debug? boolean default: false
 ---@field default_workspace? string default: nil
 ---@field disable_devicons? boolean default: false
 ---@field filter_delimiter? string default: ":"
@@ -33,6 +34,7 @@ local Config = {}
 ---@field db_root string default: vim.fn.stdpath "state"
 ---@field db_safe_mode boolean default: true
 ---@field db_validate_threshold integer default: 10
+---@field debug boolean default: false
 ---@field default_workspace? string default: nil
 ---@field disable_devicons boolean default: false
 ---@field filter_delimiter string default: ":"
@@ -55,6 +57,7 @@ Config.new = function()
     db_root = vim.fn.stdpath "state",
     db_safe_mode = true,
     db_validate_threshold = 10,
+    debug = false,
     default_workspace = nil,
     disable_devicons = false,
     filter_delimiter = ":",
@@ -92,6 +95,7 @@ Config.new = function()
     db_root = true,
     db_safe_mode = true,
     db_validate_threshold = true,
+    debug = true,
     default_workspace = true,
     disable_devicons = true,
     filter_delimiter = true,
@@ -139,6 +143,7 @@ Config.setup = function(ext_config)
     db_root = { opts.db_root, "s" },
     db_safe_mode = { opts.db_safe_mode, "b" },
     db_validate_threshold = { opts.db_validate_threshold, "n" },
+    debug = { opts.debug, 'b' },
     default_workspace = { opts.default_workspace, "s", true },
     disable_devicons = { opts.disable_devicons, "b" },
     filter_delimiter = { opts.filter_delimiter, "s" },

lua/frecency/database.lua

@@ -2,7 +2,7 @@ local Table = require "frecency.database.table"
 local FileLock = require "frecency.file_lock"
 local config = require "frecency.config"
 local watcher = require "frecency.watcher"
-local log = require "plenary.log"
+local log = require "frecency.log"
 local async = require "plenary.async" --[[@as FrecencyPlenaryAsync]]
 local Path = require "plenary.path" --[[@as FrecencyPlenaryPath]]
 

lua/frecency/database/table.lua

@@ -1,4 +1,4 @@
-local log = require "plenary.log"
+local log = require "frecency.log"
 
 ---@class FrecencyDatabaseRecordValue
 ---@field count integer

lua/frecency/file_lock.lua

@@ -1,6 +1,6 @@
+local log = require "frecency.log"
 local Path = require "plenary.path" --[[@as FrecencyPlenaryPath]]
 local async = require "plenary.async" --[[@as FrecencyPlenaryAsync]]
-local log = require "plenary.log"
 
 ---@class FrecencyFileLock
 ---@field base string

lua/frecency/finder.lua

@@ -1,8 +1,8 @@
 local config = require "frecency.config"
 local os_util = require "frecency.os_util"
+local log = require "frecency.log"
 local Job = require "plenary.job"
 local async = require "plenary.async" --[[@as FrecencyPlenaryAsync]]
-local log = require "plenary.log"
 
 ---@class FrecencyFinder
 ---@field config FrecencyFinderConfig

lua/frecency/fs.lua

@@ -1,8 +1,8 @@
 local config = require "frecency.config"
 local os_util = require "frecency.os_util"
+local log = require "frecency.log"
 local Path = require "plenary.path" --[[@as FrecencyPlenaryPath]]
 local scandir = require "plenary.scandir"
-local log = require "plenary.log"
 local uv = vim.uv or vim.loop
 
 ---@class FrecencyFS

lua/frecency/init.lua

@@ -4,7 +4,7 @@ local FS = require "frecency.fs"
 local Picker = require "frecency.picker"
 local Recency = require "frecency.recency"
 local config = require "frecency.config"
-local log = require "plenary.log"
+local log = require "frecency.log"
 
 ---@class Frecency
 ---@field private buf_registered table<integer, boolean> flag to indicate the buffer is registered to the database.

lua/frecency/log.lua

@@ -0,0 +1,8 @@
+local config = require "frecency.config"
+local log = require "plenary.log"
+
+return setmetatable({}, {
+  __index = function(_, key)
+    return config.debug and log[key] or function() end
+  end,
+})

lua/frecency/picker.lua

@@ -3,7 +3,7 @@ local Finder = require "frecency.finder"
 local config = require "frecency.config"
 local fuzzy_sorter = require "frecency.fuzzy_sorter"
 local substr_sorter = require "frecency.substr_sorter"
-local log = require "plenary.log"
+local log = require "frecency.log"
 local Path = require "plenary.path" --[[@as FrecencyPlenaryPath]]
 local actions = require "telescope.actions"
 local config_values = require("telescope.config").values

lua/frecency/tests/database_spec.lua

@@ -20,7 +20,7 @@ local function with_database(f)
   local dir, close = util.tmpdir()
   dir:joinpath("file_frecency.bin"):touch()
   return function()
-    config.setup { db_root = dir.filename }
+    config.setup { debug = true, db_root = dir.filename }
     local database = Database.new(fs)
     f(database)
     close()

lua/frecency/tests/file_lock_spec.lua

@@ -1,9 +1,12 @@
 ---@diagnostic disable: undefined-field
+local config = require "frecency.config"
 local FileLock = require "frecency.file_lock"
 local util = require "frecency.tests.util"
 local async = require "plenary.async" --[[@as FrecencyPlenaryAsync]]
 require("plenary.async").tests.add_to_env()
 
+config.setup { debug = true }
+
 local function with_dir(f)
   local dir, close = util.make_tree {}
   local filename = (dir / "file_lock_test").filename

lua/frecency/tests/frecency_spec.lua

@@ -28,9 +28,9 @@ local function with_files(files, cb_or_config, callback)
   local dir, close = util.make_tree(files)
   local cfg
   if type(cb_or_config) == "table" then
-    cfg = vim.tbl_extend("force", { db_root = dir.filename }, cb_or_config)
+    cfg = vim.tbl_extend("force", { debug = true, db_root = dir.filename }, cb_or_config)
   else
-    cfg = { db_root = dir.filename }
+    cfg = { debug = true, db_root = dir.filename }
     callback = cb_or_config
   end
   assert(callback)

lua/frecency/watcher.lua

@@ -1,5 +1,5 @@
+local log = require "frecency.log"
 local async = require "plenary.async" --[[@as FrecencyPlenaryAsync]]
-local log = require "plenary.log"
 local uv = vim.loop or vim.uv
 
 ---@class FrecencyNativeWatcherMtime