Struct CacheManager 

pub struct CacheManager { /* private fields */ }

Manages the Reflex cache directory

Implementations

impl CacheManager

pub fn new(root: impl AsRef<Path>) -> Self

Create a new cache manager for the given root directory

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

Initialize the cache directory structure if it doesn’t exist

pub fn exists(&self) -> bool

Check if cache exists and is valid

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

Validate cache integrity and detect corruption

Performs basic integrity checks on the cache:

• Verifies all required files exist
• Checks SQLite database can be opened
• Validates binary file headers (trigrams.bin, content.bin)

Returns Ok(()) if cache is valid, Err with details if corrupted.

pub fn path(&self) -> &Path

Get the path to the cache directory

pub fn workspace_root(&self) -> PathBuf

Get the workspace root directory (parent of .reflex/)

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

Clear the entire cache

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

Force SQLite WAL (Write-Ahead Log) checkpoint

Ensures all data written in transactions is flushed to the main database file. This is critical when spawning background processes that open new connections, as they need to see the committed data immediately.

Uses TRUNCATE mode to completely flush and reset the WAL file.

pub fn load_all_hashes(&self) -> Result<HashMap<String, String>>

Load all file hashes across all branches from SQLite

Used by background indexer to get hashes for all indexed files. Returns the most recent hash for each file across all branches.

pub fn load_hashes_for_branch( &self, branch: &str, ) -> Result<HashMap<String, String>>

Load file hashes for a specific branch from SQLite

Used by indexer and query engine to get hashes for the current branch. This ensures branch-specific incremental indexing and symbol cache lookups.

pub fn save_hashes(&self, _hashes: &HashMap<String, String>) -> Result<()>

👎Deprecated: Hashes are now stored in file_branches table via record_branch_file()

Save file hashes for incremental indexing

DEPRECATED: Hashes are now saved via record_branch_file() or batch_record_branch_files(). This method is kept for backward compatibility but does nothing.

pub fn update_file( &self, path: &str, language: &str, line_count: usize, ) -> Result<()>

Update file metadata in the files table

Note: File content hashes are stored separately in the file_branches table via record_branch_file() or batch_record_branch_files().

pub fn batch_update_files( &self, files: &[(String, String, usize)], ) -> Result<()>

Batch update multiple files in a single transaction for performance

Note: File content hashes are stored separately in the file_branches table via batch_update_files_and_branch().

pub fn batch_update_files_and_branch( &self, files: &[(String, String, usize)], branch_files: &[(String, String)], branch: &str, commit_sha: Option<&str>, ) -> Result<()>

Batch update files AND record their hashes for a branch in a SINGLE transaction

This is the recommended method for indexing as it ensures atomicity: if files are inserted, their branch hashes are guaranteed to be inserted too.

pub fn update_stats(&self, branch: &str) -> Result<()>

Update statistics after indexing by calculating totals from database for a specific branch

Counts only files indexed for the given branch, not all files across all branches.

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

Update cache schema hash in statistics table

This should be called after every index operation to ensure the cache is marked as compatible with the current binary version.

pub fn list_files(&self) -> Result<Vec<IndexedFile>>

Get list of all indexed files

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

Get statistics about the current cache

Returns statistics for the current git branch if in a git repo, or global statistics if not in a git repo.

pub fn record_branch_file( &self, path: &str, branch: &str, hash: &str, commit_sha: Option<&str>, ) -> Result<()>

Record a file’s hash for a specific branch

pub fn batch_record_branch_files( &self, files: &[(String, String)], branch: &str, commit_sha: Option<&str>, ) -> Result<()>

Batch record multiple files for a specific branch in a single transaction

IMPORTANT: Files must already exist in the files table before calling this method. For atomic insertion of both files and branch hashes, use batch_update_files_and_branch() instead.

pub fn get_branch_files(&self, branch: &str) -> Result<HashMap<String, String>>

Get all files indexed for a specific branch

Returns a HashMap of path → hash for all files in the branch.

pub fn branch_exists(&self, branch: &str) -> Result<bool>

Check if a branch has any indexed files

Fast existence check using LIMIT 1 for O(1) performance.

pub fn get_branch_info(&self, branch: &str) -> Result<BranchInfo>

Get branch metadata (commit, last_indexed, file_count, dirty status)

pub fn update_branch_metadata( &self, branch: &str, commit_sha: Option<&str>, file_count: usize, is_dirty: bool, ) -> Result<()>

Update branch metadata after indexing

Uses UPDATE instead of INSERT OR REPLACE to preserve branch_id and prevent CASCADE DELETE on file_branches table.

pub fn find_file_with_hash( &self, hash: &str, ) -> Result<Option<(String, String)>>

Find a file with a specific hash (for symbol reuse optimization)

Returns the path and branch where this hash was first seen, enabling reuse of parsed symbols across branches.

pub fn get_file_id(&self, path: &str) -> Result<Option<i64>>

Get file ID by path

Returns the integer ID for a file path, or None if not found.

pub fn batch_get_file_ids( &self, paths: &[String], ) -> Result<HashMap<String, i64>>

Batch get file IDs for multiple paths

Returns a HashMap of path → file_id for all found paths. Paths not in the database are omitted from the result.

Automatically chunks large batches to avoid SQLite parameter limits (999 max).

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

Check if cache compaction should run

Returns true if 24+ hours have passed since last compaction (or never compacted). Compaction threshold: 86400 seconds (24 hours)

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

Update last_compaction timestamp in statistics table

Called after successful compaction to record when it ran.

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

Compact the cache by removing deleted files and reclaiming disk space

This operation:

1. Identifies files in the database that no longer exist on disk
2. Deletes those files from all database tables (CASCADE handles related data)
3. Runs VACUUM to reclaim disk space from deleted rows
4. Updates the last_compaction timestamp

Returns a CompactionReport with statistics about the operation. Safe to run concurrently with queries (uses SQLite transactions).

Trait Implementations

impl Clone for CacheManager

fn clone(&self) -> CacheManager

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.