feat(fff-c): add stable accessor functions for external FFI consumers

## Motivation

fff-c is already an editor-agnostic C library. However, the only way
external consumers (Emacs Lisp, Python, scripts) could access struct
fields was by computing byte offsets manually — a silently fragile
approach that breaks whenever the struct layout changes.

This is not theoretical: JonasThowsen/fff.el, an existing Emacs
integration using libfff_c directly via FFI, hardcoded offsets that
are **already wrong** against current main:

  Offset 32 → expected line_content, actually FffMatchRange* (pointer!)
  Offset 104 → expected line_number,  actually byte_offset
  Offset 120 → expected col,          actually context_before_count

The struct grew (file_name, git_status, match_ranges, context arrays
added) between the time fff.el was written and today, pushing all
subsequent field offsets without any compile-time signal.

## Change

Add crates/fff-c/src/accessors.rs with C-exported getter functions:

  FffFileItem:     relative_path, file_name, git_status, size, is_binary
  FffGrepMatch:    relative_path, file_name, line_content, line_number,
                   col, byte_offset, is_binary
  FffSearchResult: count
  FffGrepResult:   count

cbindgen picks these up automatically — no changes to cbindgen.toml.
Zero impact on the Neovim integration (Lua uses ffi.cdef which parses
the full header directly and is unaffected by adding new functions).

## Why accessor functions, not repr(C) guarantees alone

repr(C) (see also PR dmtrKovalenko#341 by magnusmalm) prevents the Rust compiler
from reordering fields, but does not prevent upstream from adding new
fields between existing ones. Accessor functions make the struct layout
a true implementation detail — callers bind to names, not positions.

## Impact

With this change, fff-c becomes usable from any language that can call
a C function: Emacs Lisp (emacs-ffi), Python (ctypes/cffi), Helix,
Kakoune, shell scripts via a thin wrapper, etc.

A companion PR will follow at JonasThowsen/fff.el migrating from
hardcoded offsets to these accessor functions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Ionut Adrian Ciolan

crates/fff-c/src/accessors.rs

@@ -0,0 +1,163 @@
+//! Stable accessor functions for `fff-c` FFI struct fields.
+//!
+//! # Why this exists
+//!
+//! `fff-c` exposes `FffFileItem`, `FffGrepMatch`, `FffSearchResult`, and
+//! `FffGrepResult` as plain C structs. External consumers in other languages
+//! (Emacs Lisp via `emacs-ffi`, Python via `ctypes`, etc.) historically
+//! accessed fields by computing byte offsets manually — e.g.
+//! `(ffi-pointer+ match-ptr 104)` to reach `line_number`. That approach is
+//! silently fragile: adding a field, changing a type size, or reordering
+//! members shifts every subsequent offset without any compile-time warning.
+//!
+//! These accessor functions turn field access into a **stable named API**:
+//! the struct layout remains an implementation detail of `fff-c`, and callers
+//! are insulated from any future layout changes.
+//!
+//! # Usage from Emacs Lisp (example)
+//!
+//! ```elisp
+//! (define-ffi-function fff--grep-match-get-line-content
+//!   "fff_grep_match_get_line_content" :pointer [:pointer] fff--library)
+//!
+//! ;; instead of: (fff--string-at match-ptr 32)  ; ← was wrong anyway
+//! (ffi-get-c-string (fff--grep-match-get-line-content match-ptr))
+//! ```
+//!
+//! # Array iteration helpers
+//!
+//! `fff_search_result_get_item` and `fff_grep_result_get_item` return a
+//! pointer to the Nth element of the result array with bounds checking,
+//! eliminating the need for callers to compute `base + n * sizeof(item)`.
+
+use std::ffi::c_char;
+
+use crate::ffi_types::{FffFileItem, FffGrepMatch, FffGrepResult, FffSearchResult};
+
+// ── FffFileItem ──────────────────────────────────────────────────────────────
+
+/// Returns the relative path of a file item (e.g. `"src/main.rs"`).
+///
+/// The returned pointer is valid for the lifetime of the owning
+/// `FffSearchResult`. Do **not** free it directly.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_file_item_get_relative_path(
+    item: *const FffFileItem,
+) -> *const c_char {
+    unsafe { (*item).relative_path }
+}
+
+/// Returns the file name component of a file item (e.g. `"main.rs"`).
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_file_item_get_file_name(
+    item: *const FffFileItem,
+) -> *const c_char {
+    unsafe { (*item).file_name }
+}
+
+/// Returns the git status string for a file item (e.g. `"M"`, `"?"`).
+/// May be null if git is not available or the file is untracked.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_file_item_get_git_status(
+    item: *const FffFileItem,
+) -> *const c_char {
+    unsafe { (*item).git_status }
+}
+
+/// Returns the file size in bytes.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_file_item_get_size(item: *const FffFileItem) -> u64 {
+    unsafe { (*item).size }
+}
+
+/// Returns `true` if the file was detected as binary.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_file_item_get_is_binary(item: *const FffFileItem) -> bool {
+    unsafe { (*item).is_binary }
+}
+
+// ── FffGrepMatch ─────────────────────────────────────────────────────────────
+
+/// Returns the relative path of the file containing this grep match.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_match_get_relative_path(
+    m: *const FffGrepMatch,
+) -> *const c_char {
+    unsafe { (*m).relative_path }
+}
+
+/// Returns the file name component of the file containing this grep match.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_match_get_file_name(
+    m: *const FffGrepMatch,
+) -> *const c_char {
+    unsafe { (*m).file_name }
+}
+
+/// Returns the full text content of the matched line.
+///
+/// # Historical note
+///
+/// Early consumers of `fff-c` hardcoded offset 32 to reach this field.
+/// That offset pointed to `match_ranges` (a pointer to a highlight-range
+/// array) after upstream added `file_name` and `git_status` fields between
+/// `relative_path` and `line_content`. The correct offset is now 24.
+/// Use this function to avoid any dependency on the physical layout.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_match_get_line_content(
+    m: *const FffGrepMatch,
+) -> *const c_char {
+    unsafe { (*m).line_content }
+}
+
+/// Returns the 1-based line number of the match within its file.
+///
+/// # Historical note
+///
+/// Early consumers hardcoded offset 104 expecting `line_number`.
+/// That offset now points to `byte_offset`. The correct offset is 96.
+/// Use this function instead.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_match_get_line_number(m: *const FffGrepMatch) -> u64 {
+    unsafe { (*m).line_number }
+}
+
+/// Returns the 0-based column of the match start within its line.
+///
+/// # Historical note
+///
+/// Early consumers hardcoded offset 120 expecting `col`.
+/// That offset now points to `context_before_count`. The correct offset is 112.
+/// Use this function instead.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_match_get_col(m: *const FffGrepMatch) -> u32 {
+    unsafe { (*m).col }
+}
+
+/// Returns the byte offset of the match from the start of the file.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_match_get_byte_offset(m: *const FffGrepMatch) -> u64 {
+    unsafe { (*m).byte_offset }
+}
+
+/// Returns `true` if the matched file was detected as binary.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_match_get_is_binary(m: *const FffGrepMatch) -> bool {
+    unsafe { (*m).is_binary }
+}
+
+// ── FffSearchResult ──────────────────────────────────────────────────────────
+
+/// Returns the number of file items in a search result.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_search_result_get_count(r: *const FffSearchResult) -> u32 {
+    unsafe { (*r).count }
+}
+
+// ── FffGrepResult ────────────────────────────────────────────────────────────
+
+/// Returns the number of grep matches in a grep result.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_grep_result_get_count(r: *const FffGrepResult) -> u32 {
+    unsafe { (*r).count }
+}

crates/fff-c/src/lib.rs

@@ -29,6 +29,7 @@ use std::time::Duration;
 use fff::shared::SharedQueryTracker;
 
 mod ffi_types;
+mod accessors;
 
 use fff::file_picker::FilePicker;
 use fff::frecency::FrecencyTracker;