Merge pull request #3 from mhiro2/feat/picker-external-preview

feat(picker): Add preview window support for telescope/fzf-lua/snacks

Author: mhiro2

README.md

@@ -264,6 +264,8 @@ Configure via `require("peekstack").setup({ ... })`.
 peekstack uses a picker when multiple locations are returned (e.g. references). The
 default backend is `builtin`. To use an external picker, install the plugin and set
 `picker.backend` to one of: `telescope`, `fzf-lua`, `snacks`.
+When using these external backends, the picker preview window shows the selected file
+content around the target location.
 
 ```lua
 {

doc/peekstack.txt

@@ -150,6 +150,9 @@ Configure the backend with `picker.backend`:
   })
 <
 
+For external backends (`telescope`, `fzf-lua`, `snacks`), picker preview windows
+show file content around the selected location.
+
 If the chosen plugin is not installed, a warning is shown and the picker will not open.
 
 ==============================================================================

lua/peekstack/picker/fzf_lua.lua

@@ -6,39 +6,45 @@ local M = {}
 ---@param locations PeekstackLocation[]
 ---@param opts? table
 ---@param cb fun(location: PeekstackLocation)
-function M.pick(locations, _opts, cb)
+function M.pick(locations, opts, cb)
   local ok, fzf = pcall(require, "fzf-lua")
   if not ok then
     vim.notify("fzf-lua not available", vim.log.levels.WARN)
     return
   end
 
-  local items = picker_util.build_items(locations, 1)
+  local items = picker_util.build_external_items(locations, 1)
   for idx, item in ipairs(items) do
     item.index = idx
   end
 
-  fzf.fzf_exec(function()
-    local lines = {}
-    for _, item in ipairs(items) do
-      table.insert(lines, string.format("%d\t%s", item.index, item.label))
-    end
-    return lines
-  end, {
+  ---@type table
+  local exec_opts = vim.tbl_extend("force", opts or {}, {
     prompt = "Peekstack> ",
+    previewer = "builtin",
     actions = {
       ["default"] = function(selected)
         if not selected or not selected[1] then
           return
         end
-        local idx = tonumber(selected[1]:match("^(%d+)"))
+        local idx = tonumber(selected[1]:match("\t(%d+)$"))
         local item = idx and items[idx]
         if item then
           cb(item.value)
         end
       end,
     },
   })
+
+  fzf.fzf_exec(function()
+    local lines = {}
+    for _, item in ipairs(items) do
+      local file = item.file or ""
+      local label = item.label:gsub("[%r\n\t]", " ")
+      table.insert(lines, string.format("%s:%d:%d:%s\t%d", file, item.lnum, item.col, label, item.index))
+    end
+    return lines
+  end, exec_opts)
 end
 
 return M

lua/peekstack/picker/snacks.lua

@@ -13,27 +13,27 @@ function M.pick(locations, opts, cb)
     return
   end
 
-  local raw_items = picker_util.build_items(locations, 1)
+  local raw_items = picker_util.build_external_items(locations, 1)
   local items = {}
   for _, item in ipairs(raw_items) do
     local loc = item.value
+    local start = loc.range and loc.range.start or {}
     table.insert(items, {
       text = item.label,
-      file = loc.uri,
-      row = (loc.range.start.line or 0) + 1,
-      col = loc.range.start.character or 0,
-      loc = loc,
+      file = item.file or loc.uri,
+      pos = { item.lnum, start.character or 0 },
+      peekstack_loc = loc,
     })
   end
 
   local picker_opts = vim.tbl_extend("force", opts or {}, {
     title = "Peekstack",
     items = items,
-    format = "text",
+    format = "file",
     confirm = function(picker, item)
-      if item and item.loc then
+      if item and item.peekstack_loc then
         picker:close()
-        cb(item.loc)
+        cb(item.peekstack_loc)
       end
     end,
   })

lua/peekstack/picker/telescope.lua

@@ -13,28 +13,33 @@ function M.pick(locations, opts, cb)
     return
   end
   local finders = require("telescope.finders")
-  local sorters = require("telescope.config").values
+  local conf = require("telescope.config").values
+  local telescope_opts = opts or {}
 
-  local items = picker_util.build_items(locations, 1)
+  local items = picker_util.build_external_items(locations, 1)
   local entries = {}
   for _, item in ipairs(items) do
     table.insert(entries, {
       value = item.value,
       display = item.label,
       ordinal = item.label,
+      filename = item.file,
+      lnum = item.lnum,
+      col = item.col,
     })
   end
 
   telescope
-    .new(opts or {}, {
+    .new(telescope_opts, {
       prompt_title = "Peekstack",
       finder = finders.new_table({
         results = entries,
         entry_maker = function(entry)
           return entry
         end,
       }),
-      sorter = sorters.generic_sorter(opts or {}),
+      sorter = conf.generic_sorter(telescope_opts),
+      previewer = conf.grep_previewer(telescope_opts),
       attach_mappings = function(_, map)
         map("i", "<CR>", function(bufnr)
           local selection = require("telescope.actions.state").get_selected_entry()

lua/peekstack/types.lua

@@ -109,6 +109,15 @@
 ---@class PeekstackPicker
 ---@field pick fun(locations: PeekstackLocation[], opts?: table, cb: fun(location: PeekstackLocation))
 
+---@class PeekstackPickerItem
+---@field label string
+---@field value PeekstackLocation
+
+---@class PeekstackPickerExternalItem: PeekstackPickerItem
+---@field file? string
+---@field lnum integer
+---@field col integer
+
 ---@class PeekstackHistoryEntry
 ---@field location PeekstackLocation
 ---@field title? string

lua/peekstack/util/picker.lua

@@ -1,26 +1,51 @@
 local config = require("peekstack.config")
 local location = require("peekstack.core.location")
+local fs = require("peekstack.util.fs")
 
 local M = {}
 
----@param locations PeekstackLocation[]
----@param preview_lines integer
----@return table[]
-function M.build_items(locations, preview_lines)
+---@return PeekstackDisplayTextOpts
+local function display_text_opts()
   local ui_path = config.get().ui.path or {}
   local max_width = ui_path.max_width or 0
   if max_width == 0 then
     max_width = math.floor(vim.o.columns * 0.7)
   end
-  local opts = {
+  return {
     path_base = ui_path.base,
     max_width = max_width,
   }
+end
+
+---@param locations PeekstackLocation[]
+---@param preview_lines integer
+---@return PeekstackPickerItem[]
+function M.build_items(locations, preview_lines)
+  local opts = display_text_opts()
+  local items = {}
+  for _, loc in ipairs(locations) do
+    table.insert(items, {
+      label = location.display_text(loc, preview_lines, opts),
+      value = loc,
+    })
+  end
+  return items
+end
+
+---@param locations PeekstackLocation[]
+---@param preview_lines integer
+---@return PeekstackPickerExternalItem[]
+function M.build_external_items(locations, preview_lines)
+  local opts = display_text_opts()
   local items = {}
   for _, loc in ipairs(locations) do
+    local start = loc.range and loc.range.start or {}
     table.insert(items, {
       label = location.display_text(loc, preview_lines, opts),
       value = loc,
+      file = fs.uri_to_fname(loc.uri),
+      lnum = (start.line or 0) + 1,
+      col = (start.character or 0) + 1,
     })
   end
   return items

tests/picker_fzf_lua_spec.lua

@@ -4,12 +4,16 @@ describe("peekstack.picker.fzf_lua", function()
   it("should select the correct item when labels collide", function()
     local original = package.loaded["fzf-lua"]
     local picked = nil
+    local captured_opts = nil
 
     package.loaded["fzf-lua"] = {
       fzf_exec = function(source, opts)
+        captured_opts = opts
         local lines = source()
-        assert.is_true(lines[1]:match("^1\t") ~= nil)
-        assert.is_true(lines[2]:match("^2\t") ~= nil)
+        assert.is_true(lines[1]:match("^/tmp/same.lua:1:1:") ~= nil)
+        assert.is_true(lines[2]:match("^/tmp/same.lua:1:1:") ~= nil)
+        assert.is_true(lines[1]:match("\t1$") ~= nil)
+        assert.is_true(lines[2]:match("\t2$") ~= nil)
         opts.actions["default"]({ lines[2] })
       end,
     }
@@ -30,6 +34,8 @@ describe("peekstack.picker.fzf_lua", function()
     end)
 
     assert.are.same(loc2, picked)
+    assert.equals("builtin", captured_opts.previewer)
+    assert.equals("Peekstack> ", captured_opts.prompt)
 
     package.loaded["fzf-lua"] = original
   end)

tests/picker_snacks_spec.lua

@@ -1,54 +1,69 @@
 describe("peekstack.picker.snacks", function()
-  local config = require("peekstack.config")
+  local picker = require("peekstack.picker.snacks")
+  local original_snacks = nil
+  local original_notify = nil
 
   before_each(function()
-    config.setup({
-      picker = { backend = "snacks" },
-    })
+    original_snacks = package.loaded["snacks.picker"]
+    original_notify = vim.notify
   end)
 
-  it("should warn when snacks.nvim is not available", function()
-    -- Test by checking the module behavior when snacks is not installed
-    -- The pick function should handle the missing dependency gracefully
-    local location = require("peekstack.core.location")
+  after_each(function()
+    package.loaded["snacks.picker"] = original_snacks
+    vim.notify = original_notify
+  end)
 
-    local test_loc = {
-      uri = "file:///path/to/test.lua",
-      range = { start = { line = 0, character = 0 }, ["end"] = { line = 0, character = 10 } },
-      provider = "test_provider",
-    }
+  it("warns when snacks.nvim is not available", function()
+    package.loaded["snacks.picker"] = nil
+    local warned = false
+    vim.notify = function(msg)
+      if msg == "snacks.nvim not available" then
+        warned = true
+      end
+    end
 
-    -- Just verify the location module works correctly
-    local display_text = location.display_text(test_loc, 1)
-    assert.is_not_nil(display_text)
-    assert.is_true(type(display_text) == "string")
+    picker.pick({}, nil, function() end)
 
-    -- The snacks picker itself will warn when snacks is not available
-    -- but we can't easily test that in isolation without mocking
+    assert.is_true(warned)
   end)
 
-  it("should format locations correctly", function()
-    local location = require("peekstack.core.location")
-
-    local test_loc = {
-      uri = "file:///path/to/test.lua",
-      range = { start = { line = 5, character = 10 }, ["end"] = { line = 5, character = 20 } },
-      provider = "test_provider",
+  it("passes file format items and confirms selected location", function()
+    local picked = nil
+    local closed = false
+    local captured = nil
+    package.loaded["snacks.picker"] = {
+      pick = function(opts)
+        captured = opts
+        opts.confirm({
+          close = function()
+            closed = true
+          end,
+        }, opts.items[2])
+      end,
     }
 
-    local display_text = location.display_text(test_loc, 1)
-    assert.is_not_nil(display_text)
-    assert.is_true(type(display_text) == "string")
-  end)
-
-  it("should be registered as a known backend", function()
-    local known_backends = {
-      "builtin",
-      "telescope",
-      "fzf-lua",
-      "snacks",
+    local loc1 = {
+      uri = "file:///tmp/a.lua",
+      range = { start = { line = 3, character = 4 }, ["end"] = { line = 3, character = 4 } },
+      provider = "test",
+    }
+    local loc2 = {
+      uri = "file:///tmp/b.lua",
+      range = { start = { line = 7, character = 2 }, ["end"] = { line = 7, character = 2 } },
+      provider = "test",
     }
 
-    assert.is_true(vim.list_contains(known_backends, "snacks"))
+    picker.pick({ loc1, loc2 }, nil, function(choice)
+      picked = choice
+    end)
+
+    assert.equals("Peekstack", captured.title)
+    assert.equals("file", captured.format)
+    assert.equals("/tmp/a.lua", captured.items[1].file)
+    assert.same({ 4, 4 }, captured.items[1].pos)
+    assert.is_nil(captured.items[1].loc)
+    assert.are.same(loc1, captured.items[1].peekstack_loc)
+    assert.are.same(loc2, picked)
+    assert.is_true(closed)
   end)
 end)