Merge pull request #36 from mhiro2/docs/persist-privacy-and-truncated-viewport

patch: Document persist privacy and surface copy-mode viewport truncation

Author: mhiro2

README.md

@@ -331,6 +331,14 @@ for a name instead of using the default.
 > Persistence uses repository storage when the current working directory is inside a git repository.
 > Outside a git repository, sessions fall back to cwd-based storage.
 
+> [!IMPORTANT]
+> Sessions are written as plain JSON under `vim.fn.stdpath("state") .. "/peekstack/"`. Each entry
+> stores the file URI, line/column range, title, provider name, pin/buffer-mode flags, parent
+> popup id, and the timestamp the entry was captured. Each session also tracks `created_at` and
+> `updated_at` metadata. Any path you peek at while persistence is enabled is recorded on disk in
+> cleartext, so avoid enabling persistence on shared machines or for repositories whose file paths
+> or symbol names are sensitive.
+
 ### Auto persist (optional)
 
 When `persist.auto.enabled = true`, peekstack can automatically restore and save a session:

doc/peekstack.txt

@@ -449,6 +449,17 @@ Auto persistence (`persist.auto`) requires `persist.enabled = true`:
 Auto persistence runs only inside a git repository and always uses
 the repository session storage.
 
+PRIVACY NOTE                                      *peekstack-persist-privacy*
+
+Sessions are written as plain JSON under
+`vim.fn.stdpath("state") .. "/peekstack/"`. Each entry stores the file
+URI, line/column range, title, provider name, pin/buffer-mode flags,
+parent popup id, and the timestamp the entry was captured. Each session
+also tracks `created_at` and `updated_at` metadata. Any path you peek at
+while persistence is enabled is recorded on disk in cleartext, so avoid
+enabling persistence on shared machines or for repositories whose file
+paths or symbol names are sensitive.
+
 ==============================================================================
 SETUP RELOAD                                            *peekstack-setup-reload*
 

lua/peekstack/core/popup.lua

@@ -3,6 +3,7 @@ local origin = require("peekstack.core.popup.origin")
 local window = require("peekstack.core.popup.window")
 local diagnostics_ui = require("peekstack.ui.diagnostics")
 local keymaps = require("peekstack.ui.keymaps")
+local viewport_ui = require("peekstack.ui.viewport")
 
 local M = {}
 
@@ -55,6 +56,7 @@ function M.create(location, opts)
     pinned = false,
     buffer_mode = prepared.buffer_mode,
     line_offset = prepared.line_offset,
+    viewport = prepared.viewport,
     created_at = os.time(),
     last_active_at = vim.uv.now(),
     ephemeral = opts.ephemeral or false,
@@ -67,6 +69,7 @@ function M.create(location, opts)
   vim.w[opened.winid].peekstack_popup_id = id
 
   popup.diagnostics = diagnostics_ui.decorate(popup)
+  popup.viewport_marks = viewport_ui.decorate(popup)
 
   return popup
 end
@@ -87,6 +90,7 @@ function M.close(popup)
   -- leak into normal editing of the shared buffer.
   require("peekstack.ui.keymaps").remove_popup(popup)
   diagnostics_ui.clear(popup.diagnostics)
+  viewport_ui.clear(popup.viewport_marks)
   if popup.winid and vim.api.nvim_win_is_valid(popup.winid) then
     vim.api.nvim_win_close(popup.winid, true)
   end

lua/peekstack/core/popup/buffer.lua

@@ -15,10 +15,11 @@ local MAX_VIEWPORT_LINES = 500
 ---@return integer start_line 0-indexed inclusive
 ---@return integer end_line 0-indexed exclusive (-1 means all)
 ---@return integer line_offset lines skipped from the start
+---@return integer total total line count of the source buffer
 function M.compute_viewport(source_bufnr, target_line)
   local total = vim.api.nvim_buf_line_count(source_bufnr)
   if total <= MAX_VIEWPORT_LINES then
-    return 0, -1, 0
+    return 0, -1, 0, total
   end
 
   local half = math.floor(MAX_VIEWPORT_LINES / 2)
@@ -28,7 +29,7 @@ function M.compute_viewport(source_bufnr, target_line)
     start_line = math.max(0, end_line - MAX_VIEWPORT_LINES)
   end
 
-  return start_line, end_line, start_line
+  return start_line, end_line, start_line, total
 end
 
 ---@param bufnr integer
@@ -59,7 +60,7 @@ end
 
 ---@param location PeekstackLocation
 ---@param opts? table
----@return { bufnr: integer, source_bufnr: integer, buffer_mode: "copy"|"source", line_offset: integer }?
+---@return { bufnr: integer, source_bufnr: integer, buffer_mode: "copy"|"source", line_offset: integer, viewport?: PeekstackPopupViewport }?
 function M.prepare(location, opts)
   local buffer_mode = M.resolve_buffer_mode(opts or {})
 
@@ -95,7 +96,7 @@ function M.prepare(location, opts)
   vim.bo[bufnr].readonly = false
 
   local target_line = location.range.start.line or 0
-  local vp_start, vp_end, line_offset = M.compute_viewport(source_bufnr, target_line)
+  local vp_start, vp_end, line_offset, total = M.compute_viewport(source_bufnr, target_line)
   local ok_lines, lines = pcall(vim.api.nvim_buf_get_lines, source_bufnr, vp_start, vp_end, false)
   if not ok_lines then
     notify.warn("Failed to read buffer contents: " .. fname)
@@ -106,11 +107,25 @@ function M.prepare(location, opts)
   vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, lines)
   configure_popup_buffer(bufnr, source_bufnr, opts)
 
+  ---@type PeekstackPopupViewport?
+  local viewport = nil
+  local effective_end = vp_end == -1 and total or vp_end
+  local skipped_before = vp_start
+  local skipped_after = math.max(0, total - effective_end)
+  if skipped_before > 0 or skipped_after > 0 then
+    viewport = {
+      total = total,
+      skipped_before = skipped_before,
+      skipped_after = skipped_after,
+    }
+  end
+
   return {
     bufnr = bufnr,
     source_bufnr = source_bufnr,
     buffer_mode = buffer_mode,
     line_offset = line_offset,
+    viewport = viewport,
   }
 end
 

lua/peekstack/highlights.lua

@@ -15,6 +15,7 @@ local HIGHLIGHT_LINKS = {
   PeekstackStackViewEmpty = "Comment",
   PeekstackStackViewCursorLine = "CursorLine",
   PeekstackInlinePreview = "Comment",
+  PeekstackViewportTruncated = "NonText",
   PeekstackTitleProvider = "Type",
   PeekstackTitlePath = "Directory",
   PeekstackTitleIcon = "Special",

lua/peekstack/types.lua

@@ -39,13 +39,19 @@
 ---@field items PeekstackSessionItem[]
 ---@field meta PeekstackSessionMeta
 
+---@class PeekstackPopupViewport
+---@field total integer total line count of the source buffer
+---@field skipped_before integer lines hidden above the popup viewport
+---@field skipped_after integer lines hidden below the popup viewport
+
 ---@class PeekstackPopupModel
 ---@field id integer
 ---@field bufnr integer
 ---@field source_bufnr integer
 ---@field winid integer?
 ---@field location PeekstackLocation
 ---@field diagnostics? PeekstackDiagnosticExtmarks
+---@field viewport_marks? PeekstackViewportExtmarks
 ---@field origin { winid: integer, bufnr: integer, row: integer, col: integer }
 ---@field origin_bufnr integer
 ---@field origin_is_popup boolean
@@ -55,6 +61,7 @@
 ---@field pinned boolean
 ---@field buffer_mode "copy"|"source"
 ---@field line_offset integer
+---@field viewport? PeekstackPopupViewport
 ---@field created_at integer
 ---@field last_active_at integer
 ---@field ephemeral boolean

lua/peekstack/ui/viewport.lua

@@ -0,0 +1,83 @@
+local M = {}
+
+local NS = vim.api.nvim_create_namespace("peekstack_viewport")
+
+---@class PeekstackViewportExtmarks
+---@field bufnr integer
+---@field ns integer
+---@field ids integer[]
+
+---@param count integer
+---@param direction "above"|"below"
+---@return string
+local function format_marker(count, direction)
+  local arrow = direction == "above" and "↑" or "↓"
+  local label = direction == "above" and "earlier" or "later"
+  local plural = count == 1 and "line" or "lines"
+  return string.format("%s %d %s %s hidden", arrow, count, label, plural)
+end
+
+---Decorate a popup buffer with virt_lines markers describing how many lines
+---are hidden above and below the visible viewport. Returns nil for popups
+---whose buffer reflects the full source (no truncation, source mode, etc.).
+---@param popup PeekstackPopupModel
+---@return PeekstackViewportExtmarks?
+function M.decorate(popup)
+  if not popup or popup.buffer_mode ~= "copy" then
+    return nil
+  end
+
+  local viewport = popup.viewport
+  if not viewport then
+    return nil
+  end
+
+  local bufnr = popup.bufnr
+  if not bufnr or not vim.api.nvim_buf_is_valid(bufnr) then
+    return nil
+  end
+
+  local line_count = vim.api.nvim_buf_line_count(bufnr)
+  if line_count == 0 then
+    return nil
+  end
+
+  local ids = {}
+
+  if viewport.skipped_before and viewport.skipped_before > 0 then
+    local id = vim.api.nvim_buf_set_extmark(bufnr, NS, 0, 0, {
+      virt_lines = { { { format_marker(viewport.skipped_before, "above"), "PeekstackViewportTruncated" } } },
+      virt_lines_above = true,
+    })
+    ids[#ids + 1] = id
+  end
+
+  if viewport.skipped_after and viewport.skipped_after > 0 then
+    local last = line_count - 1
+    local id = vim.api.nvim_buf_set_extmark(bufnr, NS, last, 0, {
+      virt_lines = { { { format_marker(viewport.skipped_after, "below"), "PeekstackViewportTruncated" } } },
+    })
+    ids[#ids + 1] = id
+  end
+
+  if #ids == 0 then
+    return nil
+  end
+
+  return { bufnr = bufnr, ns = NS, ids = ids }
+end
+
+---@param marks PeekstackViewportExtmarks?
+function M.clear(marks)
+  if not marks or not marks.bufnr then
+    return
+  end
+  if not vim.api.nvim_buf_is_valid(marks.bufnr) then
+    return
+  end
+  for _, id in ipairs(marks.ids or {}) do
+    pcall(vim.api.nvim_buf_del_extmark, marks.bufnr, marks.ns, id)
+  end
+end
+
+return M

tests/popup_buffer_spec.lua

@@ -85,6 +85,41 @@ describe("peekstack.core.popup.buffer", function()
     assert.equals(500, vim.api.nvim_buf_line_count(prepared.bufnr))
     assert.equals("line101", vim.api.nvim_buf_get_lines(prepared.bufnr, 0, 1, false)[1])
     assert.equals("line600", vim.api.nvim_buf_get_lines(prepared.bufnr, 499, 500, false)[1])
+    assert.is_not_nil(prepared.viewport)
+    assert.equals(600, prepared.viewport.total)
+    assert.equals(100, prepared.viewport.skipped_before)
+    assert.equals(0, prepared.viewport.skipped_after)
+  end)
+
+  it("reports trailing skipped lines when the target sits near the start", function()
+    local lines = {}
+    for i = 1, 600 do
+      lines[i] = "line" .. i
+    end
+
+    local path = make_file(lines)
+    local prepared = buffer.prepare(make_location(path, 10), { buffer_mode = "copy" })
+
+    assert.is_not_nil(prepared)
+    temp_bufnrs[#temp_bufnrs + 1] = prepared.bufnr
+    temp_bufnrs[#temp_bufnrs + 1] = prepared.source_bufnr
+
+    assert.equals(0, prepared.line_offset)
+    assert.is_not_nil(prepared.viewport)
+    assert.equals(600, prepared.viewport.total)
+    assert.equals(0, prepared.viewport.skipped_before)
+    assert.equals(100, prepared.viewport.skipped_after)
+  end)
+
+  it("does not report a viewport when the source fits in copy mode", function()
+    local path = make_file({ "alpha", "beta", "gamma" })
+    local prepared = buffer.prepare(make_location(path, 1), { buffer_mode = "copy" })
+
+    assert.is_not_nil(prepared)
+    temp_bufnrs[#temp_bufnrs + 1] = prepared.bufnr
+    temp_bufnrs[#temp_bufnrs + 1] = prepared.source_bufnr
+
+    assert.is_nil(prepared.viewport)
   end)
 
   it("reuses the source buffer in source mode", function()
@@ -98,5 +133,6 @@ describe("peekstack.core.popup.buffer", function()
     assert.equals(prepared.source_bufnr, prepared.bufnr)
     assert.equals(0, prepared.line_offset)
     assert.is_not.equals("nofile", vim.bo[prepared.bufnr].buftype)
+    assert.is_nil(prepared.viewport)
   end)
 end)