feat(navigation): gf navigation for file references and include expressions

[StanAngeloff]

Summary

Adds gf / <C-w>f navigation support to .chat buffers. When the cursor is on an @./file reference or a {{ include('path') }} expression, pressing gf opens the referenced file, and <C-w>f opens it in a split.

• Resolve @./file references to absolute paths via the existing include() machinery
• Resolve {{ include('path') }} expressions by evaluating with a capturing stub
• Frontmatter variables are available in expressions (e.g. {{ include(my_var) }})
• Falls back to Vim's default v:fname behavior when cursor is not on an include expression

Architecture

New infrastructure (shared with future LSP hover plan)

end_col on flemma.ast.Position — The AST position type previously had start_col but not end_col. Both expression segments ({{ expr }}) and file reference segments (@./file) now track their ending column. For file references, end_col excludes trailing punctuation (e.g. the comma in @./file.txt, more text). This is needed for precise cursor-to-segment matching.

find_segment_at_position(doc, lnum, col) in ast/query.lua — A new query function that finds the segment (and its parent message) at a given 1-indexed cursor position. The algorithm handles mixed segment types on the same line: column-aware segments (expressions, file refs) get precise matching, while column-less segments (plain text) serve as fallbacks when no column-specific match is found. This prevents text segments from shadowing expression segments on the same line.

Navigation module additions

resolve_include_path(bufnr) — The core resolution function. It:

1. Gets the cursor position and finds the segment under it via find_segment_at_position
2. Bails early if the segment isn't an expression
3. Evaluates frontmatter to populate the environment with user variables
4. Installs a capturing include() stub that records the resolved path without performing any I/O (no file reads, no MIME detection, no circular-include checks)
5. Evaluates the expression via pcall(eval.eval_expression, ...) — if it calls include(), we capture the path; if it doesn't (e.g. {{ 2 + 2 }}), we return nil
6. Returns the absolute resolved path, or nil

resolve_include_path_expr() — A thin wrapper called by Vim's includeexpr option. Returns the resolved path or falls back to vim.v.fname.

Wiring

apply_chat_buffer_settings in ui/init.lua sets includeexpr to v:lua.require("flemma.navigation").resolve_include_path_expr(). The require happens lazily at gf-press time (not at buffer setup), so navigation.lua is not added to ui/init.lua's top-level requires.

Logging

Debug and trace logging throughout resolve_include_path covering: cursor position, segment lookup, expression code, frontmatter diagnostics, include() capture details, eval failures, and resolved path. Follows the project convention of "navigation: ..." prefixed messages.

Files changed

File	Change
lua/flemma/ast/nodes.lua	Add end_col? integer to Position type
lua/flemma/ast/query.lua	Add find_segment_at_position() with fallback pattern
lua/flemma/parser.lua	Compute end_col for expression and file-reference segments
lua/flemma/navigation.lua	Add resolve_include_path, resolve_include_path_expr, logging
lua/flemma/ui/init.lua	Wire includeexpr buffer option
tests/flemma/ast_spec.lua	9 new specs for end_col and find_segment_at_position
tests/flemma/includeexpr_spec.lua	6 new integration specs for path resolution
tests/fixtures/include_target.txt	Simple fixture for integration tests
.changeset/includeexpr-navigation.md	Minor changeset

Test plan

• make qa passes (luacheck, LuaLS types, inline-requires lint, full test suite)
• Manual: open a .chat file, place cursor on @./some-file.txt, press gf — file opens
• Manual: place cursor on {{ include('./some-file.txt') }}, press gf — file opens
• Manual: place cursor on plain text, press gf — default Vim behavior (no error)
• Manual: frontmatter defines a variable, expression uses it in include(var), gf resolves correctly

🤖 Generated with Claude Code