fff_search/
lib.rs

1//! # FFF Search — High-performance file finder core
2//!
3//! This crate provides the core search engine for [FFF (Fast File Finder)](https://github.com/dmtrKovalenko/fff.nvim).
4//! It includes filesystem indexing with real-time watching, fuzzy matching powered
5//! by [frizbee](https://docs.rs/neo_frizbee), frecency scoring backed by LMDB,
6//! and multi-mode grep search.
7//!
8//! ## Architecture
9//!
10//! - [`file_picker::FilePicker`] — Main entry point. Indexes a directory tree in a
11//!   background thread, maintains a sorted file list, watches the filesystem for
12//!   changes, and performs fuzzy search with frecency-weighted scoring.
13//! - [`frecency::FrecencyTracker`] — LMDB-backed database that tracks file access
14//!   and modification patterns for intelligent result ranking.
15//! - [`query_tracker::QueryTracker`] — Tracks search query history and provides
16//!   "combo-boost" scoring for repeatedly matched files.
17//! - [`grep`] — Live grep search supporting regex, plain-text, and fuzzy modes
18//!   with optional constraint filtering.
19//! - [`git`] — Git status caching and repository detection.
20//!
21//! ## Shared State
22//!
23//! [`SharedPicker`], [`SharedFrecency`], and [`SharedQueryTracker`] are
24//! newtype wrappers around `Arc<RwLock<Option<T>>>` for thread-safe shared
25//! access. They provide `read()` / `write()` methods with built-in error
26//! conversion and convenience helpers like `wait_for_scan()`.
27//!
28//! ## Quick Start
29//!
30//! ```
31//! use fff_search::file_picker::FilePicker;
32//! use fff_search::frecency::FrecencyTracker;
33//! use fff_search::query_tracker::QueryTracker;
34//! use fff_search::{
35//!     FFFMode, FilePickerOptions, FuzzySearchOptions, PaginationArgs, QueryParser,
36//!     SharedFrecency, SharedPicker, SharedQueryTracker,
37//! };
38//!
39//! let shared_picker = SharedPicker::default();
40//! let shared_frecency = SharedFrecency::default();
41//! let shared_query_tracker = SharedQueryTracker::default();
42//!
43//! let tmp = std::env::temp_dir().join("fff-doctest");
44//! std::fs::create_dir_all(&tmp).unwrap();
45//!
46//! // 1. Optionally initialize frecency and query tracker databases
47//! let frecency = FrecencyTracker::new(tmp.join("frecency"), false)?;
48//! shared_frecency.init(frecency)?;
49//!
50//! let query_tracker = QueryTracker::new(tmp.join("queries"), false)?;
51//! shared_query_tracker.init(query_tracker)?;
52//!
53//! // 2. Init the file picker (spawns background scan + watcher)
54//! FilePicker::new_with_shared_state(
55//!     shared_picker.clone(),
56//!     shared_frecency.clone(),
57//!     FilePickerOptions {
58//!         base_path: ".".into(),
59//!         mode: FFFMode::Ai,
60//!         ..Default::default()
61//!     },
62//! )?;
63//!
64//! // 3. Wait for scan
65//! shared_picker.wait_for_scan(std::time::Duration::from_secs(10));
66//!
67//! // 4. Search: lock the picker and query tracker
68//! let picker_guard = shared_picker.read()?;
69//! let picker = picker_guard.as_ref().unwrap();
70//! let qt_guard = shared_query_tracker.read()?;
71//!
72//! // 5. Parse the query and perform fuzzy search
73//! let parser = QueryParser::default();
74//! let query = parser.parse("lib.rs");
75//!
76//! let results = picker.fuzzy_search(
77//!     &query,
78//!     qt_guard.as_ref(),
79//!     FuzzySearchOptions {
80//!         max_threads: 0,
81//!         current_file: None,
82//!         pagination: PaginationArgs { offset: 0, limit: 50 },
83//!         ..Default::default()
84//!     },
85//! );
86//!
87//! assert!(results.total_matched > 0);
88//! assert!(results.items.first().unwrap().relative_path(picker).ends_with("lib.rs"));
89//!
90//! let _ = std::fs::remove_dir_all(&tmp);
91//! # Ok::<(), Box<dyn std::error::Error>>(())
92//! ```
93
94mod background_watcher;
95mod bigram_filter;
96pub mod bigram_query;
97mod constraints;
98mod db_healthcheck;
99mod error;
100mod score;
101mod sort_buffer;
102// this is pub only for benchmarks
103pub mod case_insensitive_memmem;
104
105pub(crate) mod simd_path;
106
107/// Core file picker: filesystem indexing, background watching, and fuzzy search.
108///
109/// See [`FilePicker`](file_picker::FilePicker) for the main entry point.
110pub mod file_picker;
111
112/// Frecency (frequency + recency) database for file access scoring.
113///
114/// Backed by LMDB for persistent, crash-safe storage.
115pub mod frecency;
116
117/// Git status caching and repository detection utilities.
118pub mod git;
119
120/// Live grep search with regex, plain-text, and fuzzy matching modes.
121///
122/// Supports constraint filtering (file extensions, path segments, globs)
123/// and parallel execution via rayon.
124pub mod grep;
125
126/// Tracing/logging initialization and panic hook setup.
127pub mod log;
128
129/// Path manipulation utilities: cross platform canonicalization, tilde expansion, and
130/// directory distance penalties for search scoring.
131pub mod path_utils;
132
133/// Search query history tracker for combo-boost scoring.
134///
135/// Records which files a user selects for each query, enabling the scorer
136/// to boost files that were previously chosen for similar searches.
137pub mod query_tracker;
138
139/// Core data types shared across the crate.
140pub mod types;
141
142mod ignore;
143/// Thread-safe shared handles for [`FilePicker`], [`FrecencyTracker`],
144/// and [`QueryTracker`].
145pub mod shared;
146
147pub use bigram_filter::*;
148pub use db_healthcheck::{DbHealth, DbHealthChecker};
149pub use error::{Error, Result};
150pub use fff_query_parser::*;
151pub use file_picker::*;
152pub use frecency::*;
153pub use grep::*;
154pub use query_tracker::*;
155pub use shared::*;
156pub use types::*;
fff_search/lib.rs

fff_search/
lib.rs
