feat(attach): add OrgAttach:attach_to_other_buffer()

This function has no direct Emacs equivalent. However, it tries to
replicate the functionality provided by `org-attach-dired-to-subtree`,
which attaches files selected in a dired window (roughly equivalent to
Vim's NetRW) to the last-seen Orgmode task.

Our implementation tries to be extremely general because the Neovim
ecosystem has a plethora of file browser plugins.

Author: troiganto

docs/configuration.org

@@ -3015,6 +3015,18 @@ looks up =file.txt= in the current node's attachments directory and opens
 it. Attaching a file stores a link to the attachment. See
 [[#org_attach_store_link_p][org_attach_store_link_p]] on how to configure this behavior.
 
+You can also attach files from a different buffer. The following
+mapping attaches the path under the cursor to the current headline of the
+most recently open org file:
+
+#+begin_src lua
+vim.keymap.set('n', '<Leader>o+', function()
+    local file = vim.fn.expand('<cfile>')
+    local org = require('orgmode')
+    org.attach:attach_to_other_buffer(file)
+end)
+#+end_src
+
 The only missing feature is expansion of attachment links before exporting
 a file with [[#org_export][org_exporting]].
 

lua/orgmode/attach/core.lua

@@ -27,6 +27,145 @@ function AttachCore:get_current_node()
   return AttachNode.at_cursor(self.files:get_current_file())
 end
 
+---Get an attachment node for an arbitrary window.
+---
+---An error occurs if the given window doesn't point at a loaded org file.
+---
+---@param winid integer window-ID or 0 for the current window
+---@return OrgAttachNode
+function AttachCore:get_node_by_winid(winid)
+  local bufnr = vim.api.nvim_win_get_buf(winid)
+  local path = vim.api.nvim_buf_get_name(bufnr)
+  local file = self.files:get(path)
+  local cursor = vim.api.nvim_win_get_cursor(winid)
+  return AttachNode.at_cursor(file, cursor)
+end
+
+---@param self OrgAttachCore
+---@param bufnr integer
+---@return OrgFile | nil
+local function get_file_by_bufnr(self, bufnr)
+  if not vim.api.nvim_buf_is_loaded(bufnr) then
+    return
+  end
+  local path = vim.api.nvim_buf_get_name(bufnr)
+  return self.files:load_file_sync(path) or nil
+end
+
+---Get all attachment nodes that are pointed at in a given buffer.
+---
+---If the buffer is not loaded, or if it's not an org file, this returns an
+---empty list.
+---
+---If the buffer is loaded but hidden, this returns a table mapping from 0 to
+---the only attachment node pointed at by the mark `"` (position at last exit
+---from the buffer).
+---
+---If the buffer is active, this returns a table mapping from window-ID to
+---attachment node containing the curser in that window. Note that two windows
+---may point at the same attachment node.
+---
+---See `:help windows-intro` for terminology.
+---
+---@param bufnr integer
+---@return OrgAttachNode[]
+function AttachCore:get_nodes_by_buffer(bufnr)
+  local file = get_file_by_bufnr(self, bufnr)
+  if not file then
+    return {}
+  end
+  local windows = vim.fn.win_findbuf(bufnr)
+  if #windows == 0 then
+    -- Org file is loaded but hidden.
+    local cursor = vim.api.nvim_buf_get_mark(bufnr, '"')
+    return { AttachNode.at_cursor(file, cursor) }
+  end
+  -- Org file is active, collect all windows.
+  -- Because all nodes are in the same buffer, we use the fact that their
+  -- starting-line numbers are unique. This lets us deduplicate multiple
+  -- windows that show the same node.
+  local nodes = {} ---@type table<integer, OrgAttachNode>
+  for _, winid in ipairs(windows) do
+    local cursor = vim.api.nvim_win_get_cursor(winid)
+    local node = AttachNode.at_cursor(file, cursor)
+    nodes[node:get_start_line()] = node
+  end
+  return vim.tbl_values(nodes)
+end
+
+---Like `get_nodes_by_buffer()`, but only accept an unambiguous result.
+---
+---If the buffer is displayed in multiple windows, *and* those windows have
+---their cursors at different attachment nodes, return nil.
+---
+---@param bufnr integer
+---@return OrgAttachNode|nil
+function AttachCore:get_single_node_by_buffer(bufnr)
+  local file = get_file_by_bufnr(self, bufnr)
+  if not file then
+    return {}
+  end
+  local windows = vim.fn.win_findbuf(bufnr)
+  if #windows == 0 then
+    -- Org file is loaded but hidden.
+    local cursor = vim.api.nvim_buf_get_mark(bufnr, '"')
+    return AttachNode.at_cursor(file, cursor)
+  end
+  -- Org file is active. Check that all cursors are on the same node.
+  -- (This is a very cold loop, so it being a bit awkward is acceptable.)
+  local node
+  for _, winid in ipairs(windows) do
+    local cursor = vim.api.nvim_win_get_cursor(winid)
+    local next_node = AttachNode.at_cursor(file, cursor)
+    -- Because all nodes are in the same buffer, we use the fact that their
+    -- starting-line numbers are unique. This lets us detect when two windows
+    -- point at different nodes.
+    if node and node:get_start_line() ~= next_node:get_start_line() then
+      return
+    end
+    node = AttachNode.at_cursor(file, cursor)
+  end
+  return node
+end
+
+---List attachment nodes across buffers.
+---
+---By default, the result includes all nodes pointed at by a cursor in
+---a window. If `include_hidden` is true, the result also includes buffers that
+---are loaded but hidden. In their case, the node that contains the `"` mark is
+---used.
+---
+---@param opts? { include_hidden?: boolean }
+---@return OrgAttachNode[]
+function AttachCore:list_current_nodes(opts)
+  local nodes = {} ---@type OrgAttachNode[]
+  local seen_bufs = {} ---@type table<integer, true>
+  for _, winid in vim.api.nvim_list_wins() do
+    local bufnr = vim.api.nvim_win_get_buf(winid)
+    local path = vim.api.nvim_buf_get_name(bufnr)
+    local file = self.files:load_file_sync(path)
+    if file then
+      local cursor = vim.api.nvim_win_get_cursor(winid)
+      nodes[#nodes + 1] = AttachNode.at_cursor(file, cursor)
+    end
+    seen_bufs[bufnr] = true
+  end
+  if opts and opts.include_hidden or false then
+    for _, bufnr in vim.api.nvim_list_bufs() do
+      if not seen_bufs[bufnr] then
+        local file = get_file_by_bufnr(self, bufnr)
+        if file then
+          -- Hidden buffers don't have cursors, only windows do; instead, we
+          -- use the mark where the buffer was last exited.
+          local cursor = vim.api.nvim_buf_get_mark(bufnr, '"')
+          nodes[#nodes + 1] = AttachNode.at_cursor(file, cursor)
+        end
+      end
+    end
+  end
+  return nodes
+end
+
 ---Return the directory associated with the current outline node.
 ---
 ---First check for DIR property, then ID property.

lua/orgmode/attach/init.lua

@@ -191,6 +191,29 @@ function Attach:get_node(file, cursor)
   return AttachNode.at_cursor(file, cursor)
 end
 
+---Get attachment node pointed at in a window
+---
+---@param window? integer | string window-ID, window number or any argument
+---                                accepted by `winnr()`; if 0 or nil, use the
+---                                current window
+---@return OrgAttachNode
+function Attach:get_node_by_window(window)
+  local winid
+  if not window or window == 0 then
+    winid = vim.api.nvim_get_current_win()
+  elseif type(window) == 'string' then
+    winid = vim.fn.win_getid(vim.fn.winnr(window))
+  elseif vim.fn.win_id2win(window) ~= 0 then
+    winid = window
+  else
+    winid = vim.fn.win_getid(window)
+  end
+  if winid == 0 then
+    error(('invalid window: %s'):format(window))
+  end
+  return self.core:get_node_by_winid(winid)
+end
+
 ---Return the directory associated with the current outline node.
 ---
 ---First check for DIR property, then ID property.
@@ -556,6 +579,141 @@ function Attach:attach_lns(node)
   return self:attach(nil, { method = 'lns', node = node })
 end
 
+---@class orgmode.attach.attach_to_other_buffer.Options
+---@inlinedoc
+---@field window? integer | string if passed, attach to the node pointed at in
+---               the given window; you can pass a window-ID, window number, or
+---               `winnr()`-style strings, e.g. `#` to use the previously
+---               active window. Pass 0 for the current window. It's an error
+---               if the window doesn't display an org file.
+---@field ask? 'always'|'multiple' determines what to do if `window` is nil;
+---            if 'always', collect all nodes displayed in a window and ask the
+---            user to select one. If 'multiple', only ask if more than one
+---            node is displayed. If false or nil, never ask the user; accept
+---            the unambiguous choice or abort.
+---@field prefer_recent? 'ask'|'buffer'|'window'|boolean if not nil but
+---                      `window` is nil, and more than one node is displayed,
+---                      and one of them is more preferable than the others,
+---                      this one is used without asking the user.
+---                      Preferred nodes are those displayed in the current
+---                      window's current buffer and alternate buffer, as well
+---                      as the previous window's current buffer. Pass 'buffer'
+---                      to prefer the alternate buffer over the previous
+---                      window. Pass 'window' for the same vice versa. Pass
+---                      'ask' to ask the user in case of conflict. Pass 'true'
+---                      to prefer only an unambiguous recent node over
+---                      non-recent ones.
+---@field include_hidden? boolean If not nil, include not only displayed nodes,
+---                       but also those in hidden buffers; for those, the node
+---                       pointed at by the `"` mark (position when last
+---                       exiting the buffer) is chosen.
+---@field visit_dir? boolean if not nil, open the relevant attachment directory
+---                          after attaching the file.
+---@field method? 'cp' | 'mv' | 'ln' | 'lns' The attachment method, same values
+---               as in `org_attach_method`.
+
+---@param file_or_files string | string[]
+---@param opts? orgmode.attach.attach_to_other_buffer.Options
+---@return string|nil attachment_name
+function Attach:attach_to_other_buffer(file_or_files, opts)
+  local files = utils.ensure_array(file_or_files) ---@type string[]
+  return self
+    :find_other_node(opts)
+    :next(function(node)
+      if not node then
+        return nil
+      end
+      return self:attach_many(files, {
+        node = node,
+        method = opts and opts.method,
+        visit_dir = opts and opts.visit_dir,
+      })
+    end)
+    :wait(MAX_TIMEOUT)
+end
+
+---Helper to `Attach:attach_to_other_buffer`, unfortunately really complicated.
+---@param opts? orgmode.attach.attach_to_other_buffer.Options
+---@return OrgPromise<OrgAttachNode | nil>
+function Attach:find_other_node(opts)
+  local window = opts and opts.window
+  local ask = opts and opts.ask
+  local prefer_recent = opts and opts.prefer_recent
+  local include_hidden = opts and opts.include_hidden or false
+  if window then
+    return Promise.resolve(self:get_node_by_window(window))
+  end
+  if prefer_recent then
+    local ok, node = pcall(self.core.get_current_node, self.core)
+    if ok then
+      return Promise.resolve(node)
+    end
+    local altbuf_nodes, altwin_node
+    if prefer_recent == 'buffer' then
+      altbuf_nodes = self.core:get_single_node_by_buffer(vim.fn.bufnr('#'))
+      if altbuf_nodes then
+        return Promise.resolve(altbuf_nodes)
+      end
+      ok, altwin_node = pcall(self.get_node_by_window, self, '#')
+      if ok then
+        return Promise.resolve(altwin_node)
+      end
+    elseif prefer_recent == 'window' then
+      ok, altwin_node = pcall(self.get_node_by_window, self, '#')
+      if ok then
+        return Promise.resolve(altwin_node)
+      end
+      altbuf_nodes = self.core:get_single_node_by_buffer(vim.fn.bufnr('#'))
+      if altbuf_nodes then
+        return Promise.resolve(altbuf_nodes)
+      end
+    else
+      local altbuf = vim.fn.bufnr('#')
+      local altwin = vim.fn.win_getid(vim.fn.winnr('#'))
+      -- altwin falls back to current window if previous window doesn't exist;
+      -- that's fine, we've handled it earlier.
+      ok, altwin_node = pcall(self.core.get_node_by_winid, self.core, altwin)
+      altwin_node = ok and altwin_node or nil
+      altbuf_nodes = self.core:get_nodes_by_buffer(altbuf)
+      if altwin_node and (#altbuf_nodes == 0 or vim.api.nvim_win_get_buf(altwin) == altbuf) then
+        return Promise.resolve(altwin_node)
+      end
+      if #altbuf_nodes == 1 and not altwin_node then
+        return Promise.resolve(altbuf_nodes[1])
+      end
+      if prefer_recent == 'ask' then
+        local candidates = altbuf_nodes
+        if altwin_node then
+          table.insert(candidates, 1, altwin_node)
+        end
+        return ui.select_node(candidates)
+      end
+      -- More than one possible attachment location and not asking; fall back
+      -- to regular behavior.
+    end
+  end
+  local candidates = self.core:list_current_nodes({ include_hidden = include_hidden })
+  if #candidates == 0 then
+    return Promise.reject('nowhere to attach to')
+  end
+  if ask == 'always' then
+    return ui.select_node(candidates)
+  end
+  if ask == 'multiple' then
+    if #candidates == 1 then
+      return Promise.resolve(candidates[1])
+    end
+    return ui.select_node(candidates)
+  end
+  if ask then
+    return Promise.reject(('invalid value for ask: %s'):format(ask))
+  end
+  if #candidates == 1 then
+    return Promise.resolve(candidates[1])
+  end
+  return Promise.reject('more than one possible attachment location')
+end
+
 ---Open the attachments directory via `vim.ui.open()`.
 ---
 ---@param attach_dir? string the directory to open

lua/orgmode/attach/ui.lua

@@ -1,3 +1,4 @@
+local AttachNode = require('orgmode.attach.node')
 local Input = require('orgmode.ui.input')
 local Promise = require('orgmode.utils.promise')
 local fileops = require('orgmode.attach.fileops')
@@ -66,6 +67,36 @@ function M.ask_new_method()
   end)
 end
 
+---Dialog that has user select one among a given number of attachment nodes.
+---
+---Returns nil if the user cancels with `<Esc>`.
+---
+---Errors if the user's selection doesn't match a single node.
+---
+---@param nodes OrgAttachNode[]
+---@return OrgPromise<OrgAttachNode | nil> selection
+function M.select_node(nodes)
+  ---@param arglead string
+  ---@return OrgAttachNode[]
+  local function get_matches(arglead)
+    return vim.fn.matchfuzzy(nodes, arglead, { matchseq = true, text_cb = AttachNode.get_title })
+  end
+  return Input.open('Select an attachment node: ', '', get_matches):next(function(choice)
+    if not choice then
+      return nil
+    end
+    local matches = get_matches(choice)
+    if #matches == 1 then
+      return matches[1]
+    end
+    if #matches > 1 then
+      error('more than one match for ' .. tostring(choice))
+    else
+      error('no matching buffer for ' .. tostring(choice))
+    end
+  end)
+end
+
 ---Helper for `make_completion()`.
 ---
 ---@param directory string