feat(nvim): add a new QueryCallback that uses :changes. Implement #45.

Author: Davidyz

doc/VectorCode.txt

@@ -1,4 +1,4 @@
-*VectorCode.txt*                For                 Last change: 2025 March 28
+*VectorCode.txt*                For                 Last change: 2025 March 29
 
 ==============================================================================
 Table of Contents                               *VectorCode-table-of-contents*
@@ -40,6 +40,7 @@ Table of Contents                               *VectorCode-table-of-contents*
         - |VectorCode-`cacher_backend.buf_is_enabled(bufnr?)`|
         - |VectorCode-`cacher_backend.buf_job_count(bufnr?)`|
         - |VectorCode-`cacher_backend.make_prompt_component(bufnr?,-component_cb?)`|
+        - |VectorCode-built-in-query-callbacks|
 
 
 INSTALLATION                           *VectorCode-neovim-plugin-installation*
@@ -383,8 +384,9 @@ documents. Default: `1`; - `debounce`: debounce time in milliseconds. Default:
 `10`; - `notify`: whether to show notifications when a query is completed.
 Default: `false`; - `query_cb`: a callback function that accepts the buffer ID
 and returns the query message(s). Default:
-`require("vectorcode.utils").make_surrounding_lines_cb(-1)`; - `events`: list
-of autocommand events that triggers the query. Default: `{"BufWritePost",
+`require("vectorcode.utils").make_surrounding_lines_cb(-1)`. See
+|VectorCode-this-section| for a list of built-in query callbacks; - `events`:
+list of autocommand events that triggers the query. Default: `{"BufWritePost",
 "InsertEnter", "BufReadPost"}`; - `run_on_register`: whether to run the query
 when the buffer is registered. Default: `false`; - `single_job`: boolean. If
 this is set to `true`, there will only be one running job for each buffer, and
@@ -472,6 +474,27 @@ etc. for the component. The default is the following:
 retrieved documents; - `content`: The retrieval results concatenated together
 into a string. Each result is formatted by `component_cb`.
 
+
+BUILT-IN QUERY CALLBACKS
+
+When using async cache, the query message is constructed by a function that
+takes the buffer ID as the only parameter, and return a string or a list of
+strings. The `vectorcode.utils` module provides the following callback
+constructor for you to play around with it, but you can easily build your own!
+
+- `require("vectorcode.utils").make_surrounding_lines_cb(line_count)`: returns a
+    callback that uses `line_count` lines around the cursor as the query. When
+    `line_count` is negative, it uses the full buffer;
+- `require("vectorcode.utils").make_lsp_document_symbol_cb()`: returns a
+    callback which uses the `textDocument/documentSymbol` method to retrieve a
+    list of symbols in the current document. This will fallback to
+    `make_surrounding_lines_cb(-1)` when there’s no LSP that supports the
+    `documentSymbol` method;
+- `require("vectorcode.utils").make_changes_cb(max_num)`: returns a callback
+    that fetches `max_num` unique items from the `:changes` list. This will also
+    fallback to `make_surrounding_lines_cb(-1)`. The default value for `max_num`
+    is 50.
+
 Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
 
 vim:tw=78:ts=8:noet:ft=help:norl:

docs/neovim.md

@@ -31,6 +31,7 @@
     * [`cacher_backend.buf_is_enabled(bufnr?)`](#cacher_backendbuf_is_enabledbufnr)
     * [`cacher_backend.buf_job_count(bufnr?)`](#cacher_backendbuf_job_countbufnr)
     * [`cacher_backend.make_prompt_component(bufnr?, component_cb?)`](#cacher_backendmake_prompt_componentbufnr-component_cb)
+    * [Built-in Query Callbacks](#built-in-query-callbacks)
 
 <!-- mtoc-end -->
 
@@ -341,7 +342,9 @@ The following are the available options for this function:
   - `n_query`: number of retrieved documents. Default: `1`;
   - `debounce`: debounce time in milliseconds. Default: `10`;
   - `notify`: whether to show notifications when a query is completed. Default: `false`;
-  - `query_cb`: a callback function that accepts the buffer ID and returns the query message(s). Default: `require("vectorcode.utils").make_surrounding_lines_cb(-1)`;
+  - `query_cb`: a callback function that accepts the buffer ID and returns the query message(s). 
+    Default: `require("vectorcode.utils").make_surrounding_lines_cb(-1)`. See 
+    [this section](#built-in-query-callbacks) for a list of built-in query callbacks;
   - `events`: list of autocommand events that triggers the query. Default: `{"BufWritePost", "InsertEnter", "BufReadPost"}`;
   - `run_on_register`: whether to run the query when the buffer is registered.
     Default: `false`;
@@ -419,3 +422,23 @@ end
 - `count`: number of retrieved documents;
 - `content`: The retrieval results concatenated together into a string. Each
   result is formatted by `component_cb`.
+
+#### Built-in Query Callbacks
+
+When using async cache, the query message is constructed by a function that
+takes the buffer ID as the only parameter, and return a string or a list of
+strings. The `vectorcode.utils` module provides the following callback
+constructor for you to play around with it, but you can easily build your own!
+
+- `require("vectorcode.utils").make_surrounding_lines_cb(line_count)`: returns a
+  callback that uses `line_count` lines around the cursor as the query. When
+  `line_count` is negative, it uses the full buffer;
+- `require("vectorcode.utils").make_lsp_document_symbol_cb()`: returns a
+  callback which uses the `textDocument/documentSymbol` method to retrieve a
+  list of symbols in the current document. This will fallback to
+  `make_surrounding_lines_cb(-1)` when there's no LSP that supports the
+  `documentSymbol` method;
+- `require("vectorcode.utils").make_changes_cb(max_num)`: returns a callback
+  that fetches `max_num` unique items from the `:changes` list. This will also
+  fallback to `make_surrounding_lines_cb(-1)`. The default value for `max_num`
+  is 50.

lua/vectorcode/utils.lua

@@ -100,4 +100,57 @@ function M.find_root(path)
   return vim.fs.root(path, ".vectorcode") or vim.fs.root(path, ".git")
 end
 
+---@param str string
+---@param sep string?
+---@return string[]
+local function split(str, sep)
+  if sep == nil then
+    sep = " "
+  end
+  local result = {}
+  local pattern = "([^" .. sep .. "]+)"
+  for part in string.gmatch(str, pattern) do
+    table.insert(result, part)
+  end
+  return result
+end
+
+--- This function build a `VectorCode.QueryCallback` by extracting recent changes from the `:changes` command.
+---@param max_num integer? Default is 50
+---@return VectorCode.QueryCallback
+function M.make_changes_cb(max_num)
+  if max_num == nil then
+    max_num = 50
+  end
+  return function(bufnr)
+    ---@type string?
+    local raw_changes = vim.api.nvim_exec2("changes", { output = true }).output
+    if raw_changes == nil then
+      -- fallback to other cb
+      return M.make_surrounding_lines_cb(-1)(bufnr)
+    end
+    local lines = vim.tbl_map(function(s)
+      local res = string.gsub(s, "^[%d%s]+", "")
+      return res
+    end, split(raw_changes, "\n"))
+    local results = {}
+    local seen = {} -- deduplicate
+    for i = #lines - 1, 2, -1 do
+      if #results <= max_num then
+        if not seen[lines[i]] then
+          table.insert(results, lines[i])
+          seen[lines[i]] = true
+        end
+      else
+        break
+      end
+    end
+    if #results == 0 then
+      -- fallback to other cb
+      return M.make_surrounding_lines_cb(-1)(bufnr)
+    end
+    return results
+  end
+end
+
 return M