Struct Greplm 

pub struct Greplm { /* private fields */ }

A handle to a greplm project (a directory and its .greplm index).

Implementations

impl Greplm

pub fn open(root: impl AsRef<Path>) -> Result<Greplm>

Open (and lazily initialize) the index for root.

pub fn discover(start: impl AsRef<Path>) -> Result<Greplm>

Find the nearest ancestor of start containing a .greplm directory, falling back to start itself if none is found.

pub fn root(&self) -> &Path

pub fn config(&self) -> &Config

pub fn ensure_initialized(&self) -> Result<()>

Ensure the .greplm directory exists with a default config and gitignore.

pub fn index_guard(&self) -> MutexGuard<'_, ()>

Acquire the index-mutation lock. Held by index for the duration of a build, and exposed so the daemon can serialize a searcher hot-swap (manifest read + publish) against indexing and against other swaps. Without that, two concurrent swaps (the watcher and a strict-freshness query reacting to the same edit) can store out of order, letting an older searcher clobber a newer one and leaving the index stale until the next file event.

A poisoned lock just means a prior holder panicked — on-disk state is still consistent (atomic writes), so recover the guard and proceed.

pub fn index(&self, force: bool) -> Result<IndexStats>

Build or refresh the index.

pub fn ensure_indexed(&self) -> Result<bool>

Ensure a usable, current-schema index exists, building it if absent, empty, or left unreadable by an on-disk format change. Returns true if a (re)build happened. This is the self-healing entry point for query paths: a fresh checkout or a post-upgrade stale index transparently builds instead of erroring with “run greplm index first”.

Cheap when a good index already exists (one manifest read). The actual rebuild-on-corrupt logic lives in Indexer::index_incremental, which falls back to a full rebuild on an unreadable/outdated manifest.

pub fn is_dirty(&self) -> Result<bool>

Stat-only freshness probe: does any file on disk differ from what the index recorded (new, modified by size/mtime, or deleted)? No content hashing and no reads — just the same cheap pre-check the incremental indexer uses. The daemon calls this to guarantee read-after-write consistency: if dirty, it reindexes before answering.

pub fn compact(&self) -> Result<IndexStats>

Merge all segments into a single compact segment, dropping tombstoned documents. Falls back to a full rebuild if the merge cannot proceed.

pub fn searcher(&self) -> Result<Searcher>

Open a searcher over the current index.

pub fn searcher_reusing(&self, prev: &Searcher) -> Result<Searcher>

Open a searcher over the current index, sharing unchanged segments and the warm content cache with prev (see Searcher::open_reusing). The daemon uses this so a hot-swap after an incremental index re-reads only what actually changed instead of re-parsing every segment.

pub fn search_or_grep(&self, query: &SearchQuery) -> Result<Vec<SearchHit>>

Content search that always returns results: it queries the index, and if the index is missing or errors, transparently falls back to an index-free walk+scan (grep parity). The fallback is logged at WARN.

pub fn status(&self) -> Result<Status>

Report index status.

pub fn clean(&self) -> Result<()>

Remove the entire .greplm directory.

pub fn watch<F: FnMut(&IndexStats)>( &self, debounce: Duration, on_change: F, ) -> Result<()>

Watch the project tree and re-index incrementally on changes.

on_change is called after each successful incremental update. This call blocks until an error occurs or the watcher is dropped.

pub fn socket_path(&self) -> PathBuf

Path to the daemon’s Unix socket for this project.

pub fn record_savings( &self, kind: &str, files: &BTreeSet<String>, returned_chars: u64, results: u64, )

Record a query’s token savings (grep+read baseline vs. returned payload). Best-effort; never fails a query.

pub fn savings_report(&self) -> SavingsReport

Aggregate the recorded token-savings log.