Merge pull request #1 from mhiro2/chore/minor-hardening-and-typing

chore: Minor hardening, performance, and type annotation improvements

Author: mhiro2

lua/peekstack/commands.lua

@@ -14,6 +14,27 @@ local COMMAND_NAMES = {
   "PeekstackQuickPeek",
 }
 
+---@param session PeekstackSession|table
+---@return integer
+local function session_item_count(session)
+  local items = session and session.items
+  if type(items) ~= "table" then
+    return 0
+  end
+  return #items
+end
+
+---@param session PeekstackSession|table
+---@return string
+local function session_updated_at_text(session)
+  local meta = session and session.meta
+  local updated_at = type(meta) == "table" and meta.updated_at or nil
+  if type(updated_at) ~= "number" then
+    return "unknown"
+  end
+  return os.date("%Y-%m-%d %H:%M:%S", updated_at)
+end
+
 ---@return string[]
 local function list_session_names()
   local persist = require("peekstack.persist")
@@ -76,8 +97,8 @@ function M.setup()
           local info = string.format(
             "%s: %d items (updated: %s)",
             selected,
-            #session.items,
-            os.date("%Y-%m-%d %H:%M:%S", session.meta.updated_at)
+            session_item_count(session),
+            session_updated_at_text(session)
           )
           vim.ui.select({ "Restore", "Info only" }, { prompt = info }, function(action)
             if action == "Restore" then

lua/peekstack/core/events.lua

@@ -75,6 +75,9 @@ function M.setup()
     group = group,
     callback = function()
       local winid = vim.api.nvim_get_current_win()
+      if vim.w[winid].peekstack_popup_id == nil then
+        return
+      end
       if is_floating_window(winid) then
         stack.touch(winid)
       end

lua/peekstack/init.lua

@@ -194,9 +194,25 @@ local function peek_by_provider(provider, opts)
   end)
 end
 
+---@class PeekstackPeekMethods
+---@field definition fun(opts?: table)
+---@field implementation fun(opts?: table)
+---@field references fun(opts?: table)
+---@field type_definition fun(opts?: table)
+---@field declaration fun(opts?: table)
+---@field diagnostics_cursor fun(opts?: table)
+---@field diagnostics_buffer fun(opts?: table)
+---@field file_under_cursor fun(opts?: table)
+---@field grep fun(opts?: table)
+---@field marks_buffer fun(opts?: table)
+---@field marks_global fun(opts?: table)
+---@field marks_all fun(opts?: table)
+
+---@alias PeekstackPeekCallable fun(provider: string, opts?: table)
+
 --- `M.peek` is a callable table: call `M.peek("provider", opts)` directly,
 --- or use convenience shortcuts like `M.peek.definition(opts)`.
----@type table
+---@type PeekstackPeekMethods|PeekstackPeekCallable
 M.peek = setmetatable({
   definition = function(opts)
     return peek_by_provider("lsp.definition", opts)

lua/peekstack/types.lua

@@ -46,13 +46,14 @@
 ---@field origin_bufnr integer
 ---@field origin_is_popup boolean
 ---@field title string
+---@field title_chunks? PeekstackTitleChunk[]
 ---@field pinned boolean
 ---@field buffer_mode "copy"|"source"
 ---@field line_offset integer
 ---@field created_at integer
 ---@field last_active_at integer
 ---@field ephemeral boolean
----@field win_opts table
+---@field win_opts PeekstackRenderWinOpts
 
 ---@class PeekstackStackModel
 ---@field root_winid integer
@@ -88,6 +89,19 @@
 ---@field [1] string
 ---@field [2]? string
 
+---@class PeekstackRenderWinOpts
+---@field relative string
+---@field row number
+---@field col number
+---@field width integer
+---@field height integer
+---@field style string
+---@field border string|string[]
+---@field focusable boolean
+---@field zindex integer
+---@field title? string|PeekstackTitleChunk[]
+---@field title_pos? string
+
 ---@class PeekstackStoreData
 ---@field version integer
 ---@field sessions table<string, PeekstackSession>

lua/peekstack/ui/render.lua

@@ -287,9 +287,10 @@ end
 ---@param location PeekstackLocation
 ---@param opts? { buffer_mode?: "copy"|"source" }
 ---@return integer winid
----@return table win_opts
+---@return PeekstackRenderWinOpts win_opts
 function M.open(bufnr, location, opts)
   local layout_opts = layout.compute(1)
+  ---@type PeekstackRenderWinOpts
   local win_opts = {
     relative = "editor",
     row = layout_opts.row,

lua/peekstack/util/fs.lua

@@ -4,12 +4,34 @@ local M = {}
 local cached_repo_root = nil
 ---@type string?
 local cached_repo_cwd = nil
+---@type string?
+local cached_scope_base = nil
+local scope_base_ready = false
 
 local function reset_repo_root_cache()
   cached_repo_root = nil
   cached_repo_cwd = nil
 end
 
+local function reset_scope_base_cache()
+  cached_scope_base = nil
+  scope_base_ready = false
+end
+
+---@return string
+local function scope_base_dir()
+  local base = vim.fn.stdpath("state") .. "/peekstack"
+  if cached_scope_base ~= base then
+    cached_scope_base = base
+    scope_base_ready = false
+  end
+  if not scope_base_ready then
+    M.ensure_dir(base)
+    scope_base_ready = true
+  end
+  return base
+end
+
 vim.api.nvim_create_autocmd("DirChanged", {
   group = vim.api.nvim_create_augroup("PeekstackRepoRootCache", { clear = true }),
   callback = reset_repo_root_cache,
@@ -54,6 +76,11 @@ function M._reset_repo_root_cache()
   reset_repo_root_cache()
 end
 
+---Reset scope-path cache (for testing).
+function M._reset_scope_path_cache()
+  reset_scope_base_cache()
+end
+
 ---@param path string
 ---@return string
 function M.ensure_dir(path)
@@ -80,8 +107,7 @@ end
 ---@param scope string
 ---@return string
 function M.scope_path(scope)
-  local base = vim.fn.stdpath("state") .. "/peekstack"
-  M.ensure_dir(base)
+  local base = scope_base_dir()
   if scope == "global" then
     return base .. "/global.json"
   end

tests/commands_spec.lua

@@ -2,16 +2,21 @@ describe("peekstack.commands", function()
   local commands = require("peekstack.commands")
   local persist = require("peekstack.persist")
   local original_list_sessions = nil
+  local original_select = nil
 
   before_each(function()
     commands._reset()
     original_list_sessions = persist.list_sessions
+    original_select = vim.ui.select
   end)
 
   after_each(function()
     if original_list_sessions then
       persist.list_sessions = original_list_sessions
     end
+    if original_select then
+      vim.ui.select = original_select
+    end
     commands._reset()
   end)
 
@@ -34,4 +39,33 @@ describe("peekstack.commands", function()
     assert.same({ "alpha", "beta" }, names)
     assert.is_false(called_with_opts)
   end)
+
+  it("handles missing session meta in list command", function()
+    local prompts = {}
+    persist.list_sessions = function(opts)
+      assert.is_truthy(opts)
+      assert.is_truthy(opts.on_done)
+      opts.on_done({
+        broken = {
+          items = { { uri = "file:///tmp/a.lua" } },
+        },
+      })
+      return {}
+    end
+
+    vim.ui.select = function(_items, opts, on_choice)
+      table.insert(prompts, opts.prompt)
+      if opts.prompt == "Select a session" then
+        on_choice("broken")
+        return
+      end
+      on_choice("Info only")
+    end
+
+    commands.setup()
+    vim.api.nvim_cmd({ cmd = "PeekstackListSessions" }, {})
+
+    assert.equals("Select a session", prompts[1])
+    assert.equals("broken: 1 items (updated: unknown)", prompts[2])
+  end)
 end)

tests/events_spec.lua

@@ -0,0 +1,73 @@
+describe("peekstack.core.events", function()
+  local events = require("peekstack.core.events")
+  local stack = require("peekstack.core.stack")
+  local config = require("peekstack.config")
+
+  local original_touch
+  local original_close_ephemerals
+  local original_win_get_config
+
+  before_each(function()
+    config.setup({
+      ui = {
+        quick_peek = { close_events = {} },
+        popup = { auto_close = { enabled = false } },
+      },
+    })
+    original_touch = stack.touch
+    original_close_ephemerals = stack.close_ephemerals
+    original_win_get_config = vim.api.nvim_win_get_config
+  end)
+
+  after_each(function()
+    stack.touch = original_touch
+    stack.close_ephemerals = original_close_ephemerals
+    vim.api.nvim_win_get_config = original_win_get_config
+    local winid = vim.api.nvim_get_current_win()
+    vim.w[winid].peekstack_popup_id = nil
+  end)
+
+  it("skips non-peekstack windows on CursorMoved", function()
+    local touch_calls = 0
+    local config_calls = 0
+    stack.touch = function()
+      touch_calls = touch_calls + 1
+    end
+    stack.close_ephemerals = function() end
+    vim.api.nvim_win_get_config = function(winid)
+      config_calls = config_calls + 1
+      return original_win_get_config(winid)
+    end
+
+    local winid = vim.api.nvim_get_current_win()
+    vim.w[winid].peekstack_popup_id = nil
+
+    events.setup()
+    vim.api.nvim_exec_autocmds("CursorMoved", { modeline = false })
+
+    assert.equals(0, touch_calls)
+    assert.equals(0, config_calls)
+  end)
+
+  it("touches peekstack popup windows on CursorMoved", function()
+    local touch_calls = 0
+    local config_calls = 0
+    stack.touch = function()
+      touch_calls = touch_calls + 1
+    end
+    stack.close_ephemerals = function() end
+    vim.api.nvim_win_get_config = function()
+      config_calls = config_calls + 1
+      return { relative = "editor" }
+    end
+
+    local winid = vim.api.nvim_get_current_win()
+    vim.w[winid].peekstack_popup_id = 999
+
+    events.setup()
+    vim.api.nvim_exec_autocmds("CursorMoved", { modeline = false })
+
+    assert.equals(1, touch_calls)
+    assert.equals(1, config_calls)
+  end)
+end)

tests/fs_spec.lua

@@ -31,6 +31,18 @@ describe("fs", function()
   end)
 
   describe("scope_path", function()
+    local original_ensure_dir
+
+    before_each(function()
+      fs._reset_scope_path_cache()
+      original_ensure_dir = fs.ensure_dir
+    end)
+
+    after_each(function()
+      fs.ensure_dir = original_ensure_dir
+      fs._reset_scope_path_cache()
+    end)
+
     it("returns a global path for 'global' scope", function()
       local path = fs.scope_path("global")
       assert.is_true(path:find("peekstack/global.json") ~= nil)
@@ -53,6 +65,20 @@ describe("fs", function()
       local path = fs.scope_path("global")
       assert.is_true(path:find(state_dir, 1, true) ~= nil)
     end)
+
+    it("runs ensure_dir only once after cache warmup", function()
+      local calls = 0
+      fs.ensure_dir = function(path)
+        calls = calls + 1
+        return path
+      end
+
+      fs.scope_path("global")
+      fs.scope_path("cwd")
+      fs.scope_path("global")
+
+      assert.equals(1, calls)
+    end)
   end)
 
   describe("uri_to_fname", function()