feat(nvim): jump to a unique definition or open the picker

README.md

@@ -292,6 +292,7 @@ vim.keymap.set('n', 'ff', function() require('fff').find_files() end, { desc = '
 require('fff').find_files()                        -- find files in current repo
 require('fff').live_grep()                         -- live content grep
 require('fff').live_grep_under_cursor()            -- grep <cword> in normal, selection in visual
+require('fff').go_to_definition()                  -- jump to one declaration, or open the picker
 require('fff').scan_files()                        -- force rescan
 require('fff').refresh_git_status()                -- refresh git status
 require('fff').find_files_in_dir(path)             -- find in a specific dir
@@ -302,6 +303,21 @@ require('fff').file_search(query, opts)            -- fuzzy search files / dirs
 require('fff').content_search(query, opts)         -- programmatic grep
 ```
 
+#### `go_to_definition(opts)`
+
+Searches saved files in the active FFF index for declarations that match the word under the cursor. Pass `cwd` to search another directory. If the search completes with exactly one match that declares the query as a whole name, it jumps there. Otherwise, it opens the definition-only picker with the query filled in. An incomplete index or search opens the picker too.
+
+Uses FFF's declaration matcher without an LSP server. Picker matches can include part of a name, so `user_file` can find `fn test_user_file`; a direct jump never targets a longer name such as `fn length()` for `len`. Returns `true` for a direct jump and `false` otherwise.
+
+```lua
+vim.keymap.set('n', '<D-g>', function() require('fff').go_to_definition() end, { desc = 'FFF go to definition' })
+
+-- Optional query, directory, and picker overrides:
+require('fff').go_to_definition({ query = 'UserFile', cwd = '/path/to/project' })
+```
+
+Also accepts `title`, `layout`, and `grep` options. This API always searches definitions, even when `grep.classify_definitions` is disabled.
+
 #### `file_search(query, opts)`
 
 Returns a structured result `{ items, scores, total_matched, total_files?, total_dirs?, location? }`. Each item has a `type` field (`"file"` or `"directory"`) and `name` / `relative_path`. File items also expose `size`, `modified`, `git_status`, `is_binary`, and frecency scores.

crates/fff-nvim/src/lib.rs

@@ -1185,9 +1185,16 @@ fn live_grep_with_options(
         return Err(error::to_lua_error(Error::FilePickerMissing));
     };
     let parsed_query = FFFQuery::parse(query, NvimGrepConfig);
+    let is_index_ready = picker.has_content_indexing()
+        && picker.bigram_index().is_some()
+        && !picker.is_scan_active();
     let mut result = picker.grep(&parsed_query, options);
     if options.classify_definitions == fff::DefinitionMode::Classify {
         result.matches.sort_by_key(|m| !m.is_definition);
     }
-    lua_types::GrepResultLua::new(result, picker).into_lua(lua)
+    let result = lua_types::GrepResultLua::new(result, picker).into_lua(lua)?;
+    if let LuaValue::Table(table) = &result {
+        table.set("is_index_ready", is_index_ready)?;
+    }
+    Ok(result)
 }

crates/fff-nvim/src/lua_types.rs

@@ -236,6 +236,10 @@ impl IntoLua for MixedSearchResultLua<'_> {
 impl IntoLua for GrepResultLua<'_> {
     fn into_lua(self, lua: &Lua) -> LuaResult<LuaValue> {
         let table = lua.create_table()?;
+        table.set(
+            "base_path",
+            self.picker.base_path().to_string_lossy().as_ref(),
+        )?;
 
         // Convert grep match items — each includes file metadata + match metadata
         let items_table = lua.create_table()?;

doc/fff.nvim.txt

@@ -88,6 +88,7 @@ PUBLIC API ~
     require('fff').find_files()                        -- find files in current repo
     require('fff').live_grep()                         -- live content grep
     require('fff').live_grep_under_cursor()            -- grep <cword> in normal, selection in visual
+    require('fff').go_to_definition()                  -- jump to one declaration, or open the picker
     require('fff').scan_files()                        -- force rescan
     require('fff').refresh_git_status()                -- refresh git status
     require('fff').find_files_in_dir(path)             -- find in a specific dir
@@ -99,6 +100,31 @@ PUBLIC API ~
 <
 
 
+GO_TO_DEFINITION(OPTS)                              *fff.go_to_definition()*
+
+Searches saved files in the active FFF index for declarations that match the
+word under the cursor. Pass `cwd` to search another directory.
+If the search completes with exactly one match that declares the query as a
+whole name, it jumps there. Otherwise, it opens the definition-only picker
+with the query filled in. An incomplete index or search opens the picker too.
+
+Uses FFF's declaration matcher without an LSP server. Picker matches can
+include part of a name, so `user_file` can find `fn test_user_file`; a direct
+jump never targets a longer name such as `fn length()` for `len`. Returns
+`true` for a direct jump and `false` otherwise.
+
+>lua
+    vim.keymap.set('n', '<D-g>', function()
+      require('fff').go_to_definition()
+    end, { desc = 'FFF go to definition' })
+
+    require('fff').go_to_definition({ query = 'UserFile', cwd = '/path/to/project' })
+<
+
+Also accepts `title`, `layout`, and `grep` options. This API always searches
+definitions, even when `grep.classify_definitions` is disabled.
+
+
 FILE_SEARCH(QUERY, OPTS)
 
 Returns a structured result `{ items, scores, total_matched, total_files?,

lua/fff/main.lua

@@ -1,4 +1,5 @@
 local M = {}
+local declares_exact_name
 
 M.state = { initialized = false }
 
@@ -672,4 +673,88 @@ function M.open_file_under_cursor(open_cb)
   end)
 end
 
+--- Jump to a unique declaration; otherwise open the definition picker.
+--- @param opts? {query?: string, cwd?: string, title?: string, layout?: table, grep?: table}
+--- @return boolean jumped Whether a declaration was opened without the picker.
+function M.go_to_definition(opts)
+  vim.validate({ opts = { opts, 'table', true } })
+  opts = vim.deepcopy(opts or {})
+  vim.validate({
+    query = { opts.query, 'string', true },
+    cwd = { opts.cwd, 'string', true },
+    title = { opts.title, 'string', true },
+    layout = { opts.layout, 'table', true },
+    grep = { opts.grep, 'table', true },
+  })
+
+  opts.query = opts.query or vim.fn.expand('<cword>')
+  opts.title = opts.title or 'Definitions'
+  opts.grep = opts.grep or {}
+  opts.grep.modes = { 'definition_only' }
+  opts.grep.classify_definitions = 'definition_only'
+  local config = require('fff.conf').get()
+  local root, same_root
+  if opts.cwd and opts.cwd ~= '' then
+    root = vim.uv.fs_realpath(vim.fn.expand(opts.cwd))
+    if not root or vim.fn.isdirectory(root) ~= 1 then
+      vim.notify('FFF go_to_definition: cwd does not exist', vim.log.levels.ERROR)
+      return false
+    end
+    same_root = vim.uv.fs_realpath(config.base_path) == root
+  end
+
+  local fuzzy = require('fff.core').ensure_initialized()
+  local ready, progress = pcall(fuzzy.get_scan_progress)
+  if opts.query ~= '' and ready and progress.is_index_ready and same_root ~= false then
+    local grep_config = vim.tbl_deep_extend('force', config.grep, opts.grep, {
+      max_matches_per_file = 2,
+      trim_whitespace = false,
+      time_budget_ms = 150,
+      enforce_time_budget = true,
+    })
+    local ok, result =
+      pcall(require('fff.picker_ui.grep_renderer').search, opts.query, 0, 2, grep_config, 'definition_only')
+    -- A partial page or index cannot prove that a declaration is unique.
+    if
+      ok
+      and result.is_index_ready
+      and #result.items == 1
+      and #(result.items[1].match_ranges or {}) == 1
+      and result.next_file_offset == 0
+      and (not root or vim.uv.fs_realpath(result.base_path) == root)
+      and declares_exact_name(result.items[1], opts.query)
+    then
+      local item = result.items[1]
+      local path = vim.fs.joinpath(result.base_path, item.relative_path)
+      vim.cmd("normal! m'")
+      if vim.fn.bufadd(path) ~= vim.api.nvim_get_current_buf() then open_resolved_file(path, item.relative_path) end
+      require('fff.location_utils').jump_to_location({ line = item.line_number, col = item.col + 1 })
+      vim.cmd('normal! zv')
+      return true
+    end
+  end
+
+  M.live_grep({
+    query = opts.query,
+    cwd = root or config.base_path,
+    title = opts.title,
+    layout = opts.layout,
+    grep = opts.grep,
+  })
+  return false
+end
+
+local function is_identifier_byte(byte) return byte ~= nil and (byte >= 128 or string.char(byte):match('[%w_]') ~= nil) end
+
+-- The matcher is a substring search, so `len` also finds `fn length()`.
+-- A direct jump requires the declared identifier to equal the query.
+function declares_exact_name(item, query)
+  local line, range = item.line_content, item.match_ranges[1]
+  if type(line) ~= 'string' or type(range) ~= 'table' then return false end
+  local start, stop = range[1], range[2]
+  if type(start) ~= 'number' or type(stop) ~= 'number' then return false end
+  if line:sub(start + 1, stop) ~= query then return false end
+  return not is_identifier_byte(line:byte(start)) and not is_identifier_byte(line:byte(stop + 1))
+end
+
 return M

lua/fff/picker_ui/grep_renderer.lua

@@ -13,6 +13,8 @@ local tresitter_highlight = require('fff.treesitter_hl')
 ---@field is_definition boolean
 
 ---@class fff.grep.SearchResult
+---@field base_path string Root of the index that produced these matches
+---@field is_index_ready boolean Whether this index has completed its initial scan
 ---@field items fff.grep.Match[] Array of grep match items
 ---@field total_matched number Total matches found in this call
 ---@field total_files_searched number Files actually searched in this call