fix(highlight-hover): Set cursor in parent if child is folded

Hopefully this commit fixes #1.

- Improved algorithm that finds the items to set hover-highlight
- Now we can set cursor on the nearest parent if the leaf node is folded
  in the outline.
- Set cursor column appropriate depending on whether lineno is enabled.

API:
- parser.preorder_iter now supports an optional argument as function,
  which determines whether to explore children. By default, folded
  parents will not explore children. This can now be overridden.

Behaviour:
- If you fold a nested node and hit <C-g>, you can go back to the
  nearest parent
- The column that cursor goes to is no longer arbitrarily chosen

It appears that simrat or whoever wrote this code thought the column was
1-indexed, however it is 0-indexed, so the old code was always putting
the cursor on the 2nd column.

Now, we put it in the first column. If lineno is enabled, we set the
cursor the be at the column of lineno padding, this makes both the
lineno and the markers visible.

Unfortunately the so-called 'improved' algorithm for
_highlight_current_item is still not the best. The most optimal would be
O(n). However, to make sure we stop refactoring now that it works OK and
can already fix an issue, I will leave this to posterity.

Tested to work (for me).

lua/outline/init.lua

@@ -280,11 +280,21 @@ function M._highlight_current_item(winnr)
     return
   end
 
-  local win = winnr or vim.api.nvim_get_current_win()
-  local hovered_line = vim.api.nvim_win_get_cursor(win)[1] - 1
-  local leaf_node = nil
+  -- TODO: Find an efficient way to:
+  -- 1) Set highlight for all nodes in range (regardless of visibility)
+  -- 2) Find the line number of the deepest node in range, that is visible (no
+  --    parents folded)
+  -- In one go
 
-  local cb = function(value)
+  local win = winnr or vim.api.nvim_get_current_win()
+  local buf = vim.api.nvim_win_get_buf(win)
+
+  local hovered_line = vim.api.nvim_win_get_cursor(win)[1] - 1
+  local parent_nodes = {}
+
+  -- Must not skip folded nodes so that when user unfolds a parent, they can see the leaf
+  -- node highlighted.
+  for value in parser.preorder_iter(M.state.outline_items, function() return true end) do
     value.hovered = nil
 
     if
@@ -292,18 +302,35 @@ function M._highlight_current_item(winnr)
       or (hovered_line > value.range_start and hovered_line < value.range_end)
     then
       value.hovered = true
-      leaf_node = value
+      table.insert(parent_nodes, value)
     end
   end
 
-  utils.items_dfs(cb, M.state.outline_items)
+  if #parent_nodes == 0 then
+    return
+  end
 
+  -- Probably can't 'just' writer.add_hover_highlights here because we might
+  -- want to auto_unfold_hover
   _update_lines()
 
-  if leaf_node then
-    for index, node in ipairs(M.state.flattened_outline_items) do
-      if node == leaf_node then
-        vim.api.nvim_win_set_cursor(M.view.winnr, { index, 1 })
+  -- Put cursor on deepest visible match
+  local col = 0
+  if cfg.o.outline_items.show_symbol_lineno then
+    -- Padding area between lineno column and start of guides
+    col = #tostring(vim.api.nvim_buf_line_count(buf) - 1)
+  end
+  local flats = M.state.flattened_outline_items
+  local found = false
+  local find_node
+
+  while #parent_nodes > 0 and not found do
+    find_node = table.remove(parent_nodes, #parent_nodes)
+    -- TODO: Is it feasible to use binary search here?
+    for line, node in ipairs(flats) do
+      if node == find_node then
+        vim.api.nvim_win_set_cursor(M.view.winnr, { line, col })
+        found = true
         break
       end
     end