[mini.visits] Visits tweaked to operate like grapple or harpoon

[abeldekat]

From grapple.nvim to mini.visits

mini_visits_like_grapple_and_harpoon.mp4

I always thought it must be possible to use mini.visits in a similar way as grapple or harpoon

However, two previous implementation attempts failed.

In its default setup, visits has the following incompatible traits:

• Visits are created and updated automatically. The order is not under user-control.
• All visits are stored in the same file. When working in multiple simultaneous projects, the last project to close often overwrites other relevant visits.

Relevant line in help regarding simultaneous projects:

Notes:
- Storage is implemented in such a way that it doesn't really support more
  than one parallel Neovim processes. Meaning that if there are two or more
  simultaneous Neovim processes with same visit index storage path, the last
  one writing to it will preserve its visit history while others - won't.

Relevant line in help regarding harpoon:

... This module implements a more common labeling which does not imply order
with ability to make it automated depending on the task and/or preference ...

It took me a while to find the obvious solution: Store one index per project.
Having this basic approach, the rest of the implementation followed naturally.

EDIT 20240822: The latest version can be found here

EDIT 20240826:

I refactored the code into a separate internal plugin: ak.mini.visits_harpooned and ak.mini.visits_harpooned_line

The setup

Visits.setup({
  list = { sort = H.sort }, -- only on recency
  silent = true, -- false,
  store = {
    autowrite = H.autowrite, -- if false, write on action
    normalize = H.gen_normalize(), -- remove visits without labels
    path = H.somewhat_unique_project_name(), -- store per project dir
  },
  track = { event = "" }, -- visits are added programmatically as a result of actions
})

This setup constrains the behaviour of mini.visits. I don't think it's possible to have the default experience alongside the functionality described in this post.
That said, I personally don't need default mini.visits functionality, as my workflow leans heavily on grapple/harpoon features, in combination with mini.pick, oil and tmux.

Core version

EDIT 20240819: Added a standalone version without statusline and extra maintenance options.

core standalone version

-- Just a POC, showing the core setup needed to use mini.visits like grapple/harpoon.
-- Lacks a UI to add/remove/change files under label, but:
-- 1. Either clear the label from the files using a simple for loop.
-- 2. Add/remove a label on an individual file(toggle)
local Visits = require("mini.visits")

-- Helpers:
local H = {}

H.labels = { "main", "side", "test", "col" }
H.label = H.labels[1]
H.autowrite = false

H.map = function(lhs, rhs, desc) vim.keymap.set("n", lhs, rhs, { desc = desc, silent = true }) end

-- TODO: Good enough, but not guaranteed to be unique
H.somewhat_unique_project_name = function()
  local result = string.format("%s/%s", vim.fn.stdpath("data"), "mini-visits-index")
  local cwd = vim.fn.getcwd()
  local cwd_to_number = 1
  for i = 1, #cwd do -- transform cwd to a number
    cwd_to_number = cwd_to_number + string.byte(cwd, i)
  end
  return string.format("%s-%d-%s", result, cwd_to_number, vim.fn.fnamemodify(cwd, ":t"))
end

H.iterate = function(label, index) -- does not track!
  Visits.iterate_paths("first", nil, { filter = label, n_times = index })
end

H.sort = function(path_data_arr) -- only on recency
  table.sort(path_data_arr, function(a, b) return a.latest < b.latest end)
  return path_data_arr
end

H.gen_normalize = function() -- keep visits with labels, remove others
  local default = Visits.gen_normalize.default()
  return function(index)
    index = default(index)
    for cwd, paths in pairs(index) do
      for path, data in pairs(paths) do
        if not data.labels then index[cwd][path] = nil end
      end
    end
    return index
  end
end

H.on_change = function()
  if not H.autowrite then Visits.write_index() end
end

local A = { -- actions:
  ui = function() Visits.select_path(nil, { filter = H.label }) end,
  select = function(index) H.iterate(H.label, index) end,
  switch_context = function() -- alternatively: MiniExtra.pickers.visit_labels
    vim.ui.select(H.labels, { prompt = "Visits switch context" }, function(choice)
      if not choice then return end
      H.label = choice
    end)
  end,
  clear = function()
    local visits = Visits.list_paths(nil, { filter = H.label })
    for _, path in ipairs(visits) do
      Visits.remove_label(H.label, path)
    end
    H.on_change()
  end,
  toggle = function(label)
    local full_path = vim.fn.expand("%:p")
    if vim.list_contains(Visits.list_paths(nil, { filter = label }), full_path) then
      Visits.remove_label(label)
    else
      Visits.register_visit() -- must change "latest" field
      Visits.add_label(label)
    end
    H.on_change()
  end,
}

for _, key in ipairs({
  -- Most important keys:
  { "<leader>j", A.ui, desc = "Visits ui" },
  { "<leader>a", function() A.toggle(H.label) end, desc = "Visits toggle" },
  -- Open indexed file in current label:
  { "<c-j>", function() A.select(1) end, desc = "Visit 1" },
  { "<c-k>", function() A.select(2) end, desc = "Visit 2" },
  { "<c-l>", function() A.select(3) end, desc = "Visit 3" },
  { "<c-h>", function() A.select(4) end, desc = "Visit 4" },
  -- Other actions:
  { "<leader>oj", A.switch_context, desc = "Visits switch context" },
  { "<leader>or", A.clear, desc = "Visits clear" },
}) do
  H.map(key[1], key[2], key["desc"])
end

Visits.setup({
  list = { sort = H.sort }, -- only on recency
  silent = true, -- false,
  store = {
    autowrite = H.autowrite, -- if false, write on action
    normalize = H.gen_normalize(), -- remove visits without labels
    path = H.somewhat_unique_project_name(), -- store per project dir
  },
  track = { event = "" }, -- visits are added programmatically as a result of actions
})

The code

All links are permalinks to fragments in my Neovim config: https://github.com/abeldekat/nvim_pde

ak.config.editor.mini_visits

Covers the main part of the implementation. Contains 250 lines of code. Minus 100 lines for the "maintain dialogue" part, the resulting 150 lines compare nicely to the corresponding grapple config.

Contains one hack.
The hack is needed to change labeled visits in batch mode. By temporarily overriding os.time, each latest field in the visit will differ one second with the previous visit.

EDIT 20240819: Removed the hack. Not needed when using MiniVisit.get_index(). Updated permalink.

ak.config.ui.visitsline

Show indicators for visits in the current context/label.
Used in ak.config.ui.mini_statusline.
Corresponding grapple part: ak.config.ui.grappleline

ak.config.editor.mini_pick

A customized picker to show all visits for all labels in the exact order per label.
Each line shows a label-path combination.
Key mapping: <leader>,

ak.config.editor.mini_pick_labeled

See this discussion

Provides fast labels for all pickers(including vim.ui.select) that show visit information. Labels are just letters, as opposed to labels used in the context of mini.visit.

Related code

ak.util.labels

Shared code defining the labels to use

ak.util.init

Also label an oil buffer

ak.config.autocmds

Use q to close the "maintain" dialogue

ak.deps.editor

Add package mini.visits(mini.deps code)

[echasnovski]

That's a nice project to craft what best suits your workflow!

At this level of complexity and incompatibility, though, maybe it would be better to write something own from scratch instead of forcing and hacking 'mini.visits'?

[abeldekat]

At this level of complexity and incompatibility, though, maybe it would be better to write something own from scratch instead of forcing and hacking 'mini.visits'?

That's interesting...
At the same time you wrote the comment, I removed the hack. I updated the post accordingly.

Yes, the code I provided is complex. I removed the custom maintenance part and the statusline integration in order to show the core setup. This results in 100 lines of configuration, only using the options mini.visits( as part of the mini toolbox ) provides.
Do you still think the following code snippet is complex and incompatible?

core version

-- Just a POC, showing the core setup needed to use mini.visits like grapple/harpoon.
-- Lacks a UI to add/remove/change files under label, but:
-- 1. Either clear the label from the files using a simple for loop.
-- 2. Add/remove a label on an individual file(toggle)
local Visits = require("mini.visits")

-- Helpers:
local H = {}

H.labels = { "main", "side", "test", "col" }
H.label = H.labels[1]
H.autowrite = false

H.map = function(lhs, rhs, desc) vim.keymap.set("n", lhs, rhs, { desc = desc, silent = true }) end

-- TODO: Good enough, but not guaranteed to be unique
H.somewhat_unique_project_name = function()
  local result = string.format("%s/%s", vim.fn.stdpath("data"), "mini-visits-index")
  local cwd = vim.fn.getcwd()
  local cwd_to_number = 1
  for i = 1, #cwd do -- transform cwd to a number
    cwd_to_number = cwd_to_number + string.byte(cwd, i)
  end
  return string.format("%s-%d-%s", result, cwd_to_number, vim.fn.fnamemodify(cwd, ":t"))
end

H.iterate = function(label, index) -- does not track!
  Visits.iterate_paths("first", nil, { filter = label, n_times = index })
end

H.sort = function(path_data_arr) -- only on recency
  table.sort(path_data_arr, function(a, b) return a.latest < b.latest end)
  return path_data_arr
end

H.gen_normalize = function() -- keep visits with labels, remove others
  local default = Visits.gen_normalize.default()
  return function(index)
    index = default(index)
    for cwd, paths in pairs(index) do
      for path, data in pairs(paths) do
        if not data.labels then index[cwd][path] = nil end
      end
    end
    return index
  end
end

H.on_change = function()
  if not H.autowrite then Visits.write_index() end
end

local A = { -- actions:
  ui = function() Visits.select_path(nil, { filter = H.label }) end,
  select = function(index) H.iterate(H.label, index) end,
  switch_context = function() -- alternatively: MiniExtra.pickers.visit_labels
    vim.ui.select(H.labels, { prompt = "Visits switch context" }, function(choice)
      if not choice then return end
      H.label = choice
    end)
  end,
  clear = function()
    local visits = Visits.list_paths(nil, { filter = H.label })
    for _, path in ipairs(visits) do
      Visits.remove_label(H.label, path)
    end
    H.on_change()
  end,
  toggle = function(label)
    local full_path = vim.fn.expand("%:p")
    if vim.list_contains(Visits.list_paths(nil, { filter = label }), full_path) then
      Visits.remove_label(label)
    else
      Visits.register_visit() -- must change "latest" field
      Visits.add_label(label)
    end
    H.on_change()
  end,
}

for _, key in ipairs({
  -- Most important keys:
  { "<leader>j", A.ui, desc = "Visits ui" },
  { "<leader>a", function() A.toggle(H.label) end, desc = "Visits toggle" },
  -- Open indexed file in current label:
  { "<c-j>", function() A.select(1) end, desc = "Visit 1" },
  { "<c-k>", function() A.select(2) end, desc = "Visit 2" },
  { "<c-l>", function() A.select(3) end, desc = "Visit 3" },
  { "<c-h>", function() A.select(4) end, desc = "Visit 4" },
  -- Other actions:
  { "<leader>oj", A.switch_context, desc = "Visits switch context" },
  { "<leader>or", A.clear, desc = "Visits clear" },
}) do
  H.map(key[1], key[2], key["desc"])
end

Visits.setup({
  list = { sort = H.sort }, -- only on recency
  silent = true, -- false,
  store = {
    autowrite = H.autowrite, -- if false, write on action
    normalize = H.gen_normalize(), -- remove visits without labels
    path = H.somewhat_unique_project_name(), -- store per project dir
  },
  track = { event = "" }, -- visits are added programmatically as a result of actions
})

I included the above fragment in the post as a separate chapter.

The statusline integration is handcrafted. The code started as a plugin for harpoon: harpoonline.
When I moved to grapple, I archived harpoonline and simplified the code to be used in my config. It was trivial to copy the code to hook mini.visits into the mini.statusline component.

Naturally, there is a "fun" part at play. I could just as well keep using grapple.nvim.
However, when using mini, I get mini.visits for free. As in all components mini provides, the plugin is concise, stable, configurable and well tested. The plugin does a lot of the work I would otherwise need to code myself. I hope this is a valid argument against writing my own code from scratch...;)

[echasnovski]

You don't have to justify not wanting to write from scratch :) It was just an observation that came to mind while skimming through implementation. I am of course happy to see the proof that design of 'mini.nvim' modules is versatile enough to help implementing even vastly different workflows.

One thing I wanted to say several times, though. The core idea behind using H helper table is to be able to have code in "from top to bottom" order. Meaning that "main" functions go on top and helper go on bottom. This would be not possible with local function ... approach as they need to be defined before they are used in code. If you prefer using "from bottom to top" organization (which is totally fine), then using local function (or local a = function()) is a more convenient approach.

[abeldekat]

... The core idea behind using H helper table is to be able to have code in "from top to bottom" order...

Indeed. I do use this when there are lots of functions. There is another benefit, related to laziness: The order of the functions assigned to "H" does not matter...;). I am also thinking about code organization. I sometimes use an extra table, A, having functions related to actions.

Thanks for having a look at this post!

It's rewarding to be able to use a mini plugin for an important part in my workflow.
Also, the pick_with_labels functionality is very useful in this part. Thanks again for helping me to create an implementation without hacks...;)

[abeldekat]

I refactored the code into a separate internal plugin: ak.mini.visits_harpooned and ak.mini.visits_harpooned_line

[abeldekat]

visits_harpooned_and_files.mp4

Recently, I replaced oil.nvim with mini.files.

It took some effort to integrate mini.files into my visits_harpooned.

I can now use mini.files with almost the same functionality oil provided.

[echasnovski]

I can now use mini.files with almost the same functionality oil provided.

What is missing?

[abeldekat]

Nothing, after giving that a second thought. I should have expected that question...)
That sentence was formulated a bit too carefully. Apologies.