Skip to main content

reflex/
cache.rs

1//! Cache management and memory-mapped I/O
2//!
3//! The cache module handles the `.reflex/` directory structure:
4//! - `meta.db`: Metadata, file fingerprints, dependencies and the symbol cache (SQLite)
5//! - `content.bin`: Memory-mapped file contents (binary)
6//! - `trigrams.bin`: Trigram inverted index (per-file varint blocks, V4 format)
7//! - `config.toml`: Index settings (TOML text)
8
9use anyhow::{Context, Result};
10use rusqlite::{Connection, OptionalExtension};
11use std::collections::HashMap;
12use std::fs::File;
13use std::path::{Path, PathBuf};
14
15use crate::models::IndexedFile;
16
17/// Default cache directory name
18pub const CACHE_DIR: &str = ".reflex";
19
20/// File names within the cache directory
21pub const META_DB: &str = "meta.db";
22#[deprecated(note = "tokens.bin is no longer written")]
23pub const TOKENS_BIN: &str = "tokens.bin";
24#[deprecated(note = "hashes.json is no longer written; hashes live in meta.db")]
25pub const HASHES_JSON: &str = "hashes.json";
26pub const CONFIG_TOML: &str = "config.toml";
27/// `statistics` key: the `--languages` of the last `rfx index` run that passed one
28/// (JSON list). Older binaries ignore it.
29pub const LANGUAGES_OVERRIDE_KEY: &str = "languages_override";
30
31/// Open a SQLite database with Reflex's standard pragmas.
32///
33/// Every connection to `meta.db` (and to the symbol cache, which lives in the same
34/// file) MUST go through this helper. Plain `Connection::open` leaves SQLite at its
35/// defaults, which caused three separate production failures:
36///
37/// 1. **No `busy_timeout`** — the default is 0, so `BEGIN IMMEDIATE` returned
38///    `database is locked` *instantly* whenever the background symbol indexer held a
39///    write. Agents saw a raw SQLite error instead of a retry.
40/// 2. **No `journal_mode=WAL`** — readers blocked writers and vice versa, and
41///    [`CacheManager::checkpoint_wal`] was issuing `wal_checkpoint(TRUNCATE)` against a
42///    rollback-journal database, where it does nothing.
43/// 3. **No `foreign_keys=ON`** — SQLite disables foreign keys per connection by
44///    default, so the `ON DELETE CASCADE` clauses in the schema never fired and
45///    deleting a row from `files` orphaned its `file_branches` / `file_dependencies` /
46///    `file_exports` rows.
47///
48/// Pragma order is load-bearing: `journal_mode=WAL` itself can return `SQLITE_BUSY`
49/// when another connection is attached, so `busy_timeout` must be set first.
50///
51/// Set `REFLEX_SQLITE_JOURNAL=delete` to opt out of WAL on network filesystems, where
52/// WAL requires shared-memory support that NFS/SMB do not reliably provide.
53pub fn open_meta_db(db_path: impl AsRef<Path>) -> Result<Connection> {
54    let db_path = db_path.as_ref();
55    let conn = Connection::open(db_path)
56        .with_context(|| format!("Failed to open {}", db_path.display()))?;
57
58    // Must come first: the journal_mode change below can itself hit a busy database.
59    conn.busy_timeout(std::time::Duration::from_millis(SQLITE_BUSY_TIMEOUT_MS))
60        .context("Failed to set busy_timeout")?;
61
62    let journal_mode = std::env::var("REFLEX_SQLITE_JOURNAL")
63        .unwrap_or_else(|_| "WAL".to_string())
64        .to_uppercase();
65
66    // query_row, not execute: `PRAGMA journal_mode` returns the resulting mode as a row.
67    if let Err(e) = conn.query_row(
68        &format!("PRAGMA journal_mode={}", journal_mode),
69        [],
70        |row| row.get::<_, String>(0),
71    ) {
72        // A read-only or network filesystem can refuse WAL. Degrading to the default
73        // journal is correct here — losing concurrency beats failing to open the cache.
74        log::warn!(
75            "Could not set journal_mode={} on {}: {} (continuing with the default journal)",
76            journal_mode,
77            db_path.display(),
78            e
79        );
80    }
81
82    conn.execute_batch("PRAGMA foreign_keys=ON;")
83        .context("Failed to enable foreign keys")?;
84
85    Ok(conn)
86}
87
88/// How long a SQLite connection waits for a competing writer before giving up.
89///
90/// The background symbol indexer writes in batches; 5s comfortably covers one batch.
91/// A pass that holds the database for longer than this is caught earlier and more
92/// clearly by the `BackgroundIndexer::is_running` gate in `Indexer::index`.
93const SQLITE_BUSY_TIMEOUT_MS: u64 = 5_000;
94
95/// Manages the Reflex cache directory
96#[derive(Clone)]
97pub struct CacheManager {
98    cache_path: PathBuf,
99}
100
101impl CacheManager {
102    /// Create a new cache manager for the given root directory
103    pub fn new(root: impl AsRef<Path>) -> Self {
104        let cache_path = root.as_ref().join(CACHE_DIR);
105        Self { cache_path }
106    }
107
108    /// Initialize the cache directory structure if it doesn't exist
109    pub fn init(&self) -> Result<()> {
110        log::info!("Initializing cache at {:?}", self.cache_path);
111
112        if !self.cache_path.exists() {
113            std::fs::create_dir_all(&self.cache_path)?;
114        }
115
116        // Create meta.db with schema
117        self.init_meta_db()?;
118
119        // Create default config.toml
120        self.init_config_toml()?;
121
122        log::info!("Cache initialized successfully");
123        Ok(())
124    }
125
126    /// Create `config.toml` if it is missing: what `init` does besides the schema,
127    /// for a cache whose schema this binary already completed a run on.
128    pub(crate) fn ensure_config(&self) -> Result<()> {
129        self.init_config_toml()
130    }
131
132    /// Initialize meta.db with SQLite schema
133    fn init_meta_db(&self) -> Result<()> {
134        let db_path = self.cache_path.join(META_DB);
135
136        // Always run: every statement is `IF NOT EXISTS`, so this is a no-op on
137        // a complete database and a repair on a half-built one. (An indexer
138        // killed during schema creation used to leave meta.db with some tables
139        // missing; the old "skip if the file exists" check then made every later
140        // run fail with `no such table: file_branches`.) One transaction so a
141        // kill mid-way leaves either the old state or the full schema.
142        let conn = open_meta_db(&db_path).context("Failed to create meta.db")?;
143        conn.execute_batch("BEGIN IMMEDIATE")
144            .context("Failed to begin meta.db schema transaction")?;
145
146        // Create files table.
147        //
148        // The last four columns are the working-tree fingerprint: what freshness
149        // compares the tree against. Before 2.0.0 the baseline was the indexed
150        // COMMIT, so a dirty tree could never be reported fresh, however many times
151        // it was re-indexed. `hash` is the blake3 of the bytes that went into
152        // content.bin; `size`/`mtime_ns` let a status check skip the hash for files
153        // that have not been touched; `dirty_at_index` marks paths `git status`
154        // listed at index time, which must be re-checked even once git reports them
155        // clean again (an edit reverted after it was indexed).
156        conn.execute(
157            "CREATE TABLE IF NOT EXISTS files (
158                id INTEGER PRIMARY KEY AUTOINCREMENT,
159                path TEXT NOT NULL UNIQUE,
160                last_indexed INTEGER NOT NULL,
161                language TEXT NOT NULL,
162                token_count INTEGER DEFAULT 0,
163                line_count INTEGER DEFAULT 0,
164                size INTEGER NOT NULL DEFAULT 0,
165                mtime_ns INTEGER NOT NULL DEFAULT 0,
166                hash TEXT NOT NULL DEFAULT '',
167                dirty_at_index INTEGER NOT NULL DEFAULT 0,
168                walk_seq INTEGER NOT NULL DEFAULT 0,
169                vendored INTEGER NOT NULL DEFAULT 0
170            )",
171            [],
172        )?;
173        Self::migrate_files_columns(&conn)?;
174
175        conn.execute(
176            "CREATE INDEX IF NOT EXISTS idx_files_path ON files(path)",
177            [],
178        )?;
179        // Walk-order probes of a library update (`Indexer::update_paths`).
180        conn.execute(
181            "CREATE INDEX IF NOT EXISTS idx_files_walk_seq ON files(walk_seq)",
182            [],
183        )?;
184
185        // Create statistics table
186        conn.execute(
187            "CREATE TABLE IF NOT EXISTS statistics (
188                key TEXT PRIMARY KEY,
189                value TEXT NOT NULL,
190                updated_at INTEGER NOT NULL
191            )",
192            [],
193        )?;
194
195        // Initialize default statistics. `OR IGNORE`: an existing cache keeps its
196        // `total_files` (its `updated_at` is the "Last updated" time) and its
197        // `last_compaction`. Resetting them on every run made the unlocked
198        // background compaction start on every `rfx` command.
199        let now = chrono::Utc::now().timestamp();
200        conn.execute(
201            "INSERT OR IGNORE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
202            ["total_files", "0", &now.to_string()],
203        )?;
204        // Who wrote this cache. The old `cache_version = "1"` row was never read by
205        // anything; this replaces it with something actionable, so a refusal can name
206        // the version that owns the cache instead of just a hash.
207        conn.execute(
208            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
209            [
210                "writer_version",
211                env!("CARGO_PKG_VERSION"),
212                &now.to_string(),
213            ],
214        )?;
215        if let Some(sha) = option_env!("REFLEX_GIT_SHA") {
216            conn.execute(
217                "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
218                ["writer_git_sha", sha, &now.to_string()],
219            )?;
220        }
221
222        // Store cache schema hash for automatic invalidation detection
223        // This hash is computed at build time from cache-critical source files.
224        //
225        // `OR IGNORE`: only a NEW cache is stamped here. An existing cache keeps the
226        // hash of the binary that last completed an index, until
227        // `update_schema_hash` at the end of the next complete run. Stamping it here
228        // meant the indexer's "schema changed → full rebuild" check could never fire.
229        let schema_hash = env!("CACHE_SCHEMA_HASH");
230        conn.execute(
231            "INSERT OR IGNORE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
232            ["schema_hash", schema_hash, &now.to_string()],
233        )?;
234
235        // Initialize last_compaction timestamp (0 = never compacted)
236        conn.execute(
237            "INSERT OR IGNORE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
238            ["last_compaction", "0", &now.to_string()],
239        )?;
240
241        // Create config table
242        conn.execute(
243            "CREATE TABLE IF NOT EXISTS config (
244                key TEXT PRIMARY KEY,
245                value TEXT NOT NULL
246            )",
247            [],
248        )?;
249
250        // Create branch tracking tables for git-aware indexing
251        conn.execute(
252            "CREATE TABLE IF NOT EXISTS file_branches (
253                file_id INTEGER NOT NULL,
254                branch_id INTEGER NOT NULL,
255                hash TEXT NOT NULL,
256                last_indexed INTEGER NOT NULL,
257                PRIMARY KEY (file_id, branch_id),
258                FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE,
259                FOREIGN KEY (branch_id) REFERENCES branches(id) ON DELETE CASCADE
260            )",
261            [],
262        )?;
263
264        conn.execute(
265            "CREATE INDEX IF NOT EXISTS idx_branch_lookup ON file_branches(branch_id, file_id)",
266            [],
267        )?;
268
269        conn.execute(
270            "CREATE INDEX IF NOT EXISTS idx_hash_lookup ON file_branches(hash)",
271            [],
272        )?;
273
274        // Create branches metadata table
275        conn.execute(
276            "CREATE TABLE IF NOT EXISTS branches (
277                id INTEGER PRIMARY KEY AUTOINCREMENT,
278                name TEXT NOT NULL UNIQUE,
279                commit_sha TEXT NOT NULL,
280                last_indexed INTEGER NOT NULL,
281                file_count INTEGER DEFAULT 0,
282                is_dirty INTEGER DEFAULT 0
283            )",
284            [],
285        )?;
286
287        // Create file dependencies table for tracking imports/includes
288        conn.execute(
289            "CREATE TABLE IF NOT EXISTS file_dependencies (
290                id INTEGER PRIMARY KEY AUTOINCREMENT,
291                file_id INTEGER NOT NULL,
292                imported_path TEXT NOT NULL,
293                resolved_file_id INTEGER,
294                import_type TEXT NOT NULL,
295                line_number INTEGER NOT NULL,
296                imported_symbols TEXT,
297                resolved_package TEXT,
298                resolved_member TEXT,
299                FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE,
300                FOREIGN KEY (resolved_file_id) REFERENCES files(id) ON DELETE SET NULL
301            )",
302            [],
303        )?;
304
305        // Which files make up each package an import can name (`go:<dir>`,
306        // `jvm:<package>`, `cs:<namespace>`). A per-file fact, written when the file
307        // is extracted and deleted with it, so adding a file to a package needs no
308        // import to be resolved again.
309        conn.execute(
310            "CREATE TABLE IF NOT EXISTS package_members (
311                package TEXT NOT NULL,
312                member TEXT NOT NULL,
313                file_id INTEGER NOT NULL,
314                PRIMARY KEY (package, member, file_id),
315                FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
316            ) WITHOUT ROWID",
317            [],
318        )?;
319
320        conn.execute(
321            "CREATE INDEX IF NOT EXISTS idx_package_members_file ON package_members(file_id)",
322            [],
323        )?;
324
325        // The import graph: one row per (import, file it reaches). File-resolved
326        // imports reach one file; package imports reach every member file
327        // (`package` is the key they reached it by). A Python `from pkg import a`
328        // that resolved to `pkg/__init__.py` also reaches `pkg/a.py` or
329        // `pkg/a/__init__.py` when `a` is a submodule. Vendored files are neither
330        // end of an edge (`crate::vendor`). Recreated every time: a view holds no
331        // data, and `IF NOT EXISTS` would keep an older definition.
332        conn.execute_batch(
333            "DROP VIEW IF EXISTS import_edges;
334             CREATE VIEW import_edges AS
335             SELECT e.* FROM (
336               SELECT id AS dep_id, file_id AS src, resolved_file_id AS dst, import_type,
337                      NULL AS package
338                 FROM file_dependencies
339                WHERE resolved_file_id IS NOT NULL
340               UNION ALL
341               SELECT DISTINCT d.id, d.file_id, m.file_id, d.import_type, d.resolved_package
342                 FROM file_dependencies d
343                 JOIN package_members m
344                   ON m.package = d.resolved_package
345                  AND m.member = COALESCE(d.resolved_member, '')
346                WHERE d.resolved_package IS NOT NULL
347                  AND m.file_id != d.file_id
348               UNION ALL
349               SELECT DISTINCT d.id, d.file_id, sub.id, d.import_type, NULL
350                 FROM file_dependencies d
351                 JOIN files t ON t.id = d.resolved_file_id
352                 JOIN json_each(d.imported_symbols) s
353                 JOIN files sub
354                   ON sub.path IN (substr(t.path, 1, length(t.path) - 11) || s.value || '.py',
355                                   substr(t.path, 1, length(t.path) - 11) || s.value || '/__init__.py')
356                WHERE d.imported_symbols IS NOT NULL
357                  AND substr(t.path, -11) = '__init__.py'
358                  AND (length(t.path) = 11 OR substr(t.path, -12, 1) = '/')
359                  AND sub.id != d.file_id
360             ) e
361             JOIN files s ON s.id = e.src AND s.vendored = 0
362             JOIN files t ON t.id = e.dst AND t.vendored = 0;",
363        )?;
364
365        conn.execute(
366            "CREATE INDEX IF NOT EXISTS idx_deps_file ON file_dependencies(file_id)",
367            [],
368        )?;
369
370        conn.execute(
371            "CREATE INDEX IF NOT EXISTS idx_deps_resolved ON file_dependencies(resolved_file_id)",
372            [],
373        )?;
374
375        conn.execute(
376            "CREATE INDEX IF NOT EXISTS idx_deps_type ON file_dependencies(import_type)",
377            [],
378        )?;
379
380        Self::migrate_dependency_columns(&conn)?;
381        conn.execute(
382            "CREATE INDEX IF NOT EXISTS idx_deps_package ON file_dependencies(resolved_package)",
383            [],
384        )?;
385
386        // Create file exports table for tracking barrel re-exports
387        conn.execute(
388            "CREATE TABLE IF NOT EXISTS file_exports (
389                id INTEGER PRIMARY KEY AUTOINCREMENT,
390                file_id INTEGER NOT NULL,
391                exported_symbol TEXT,
392                source_path TEXT NOT NULL,
393                resolved_source_id INTEGER,
394                line_number INTEGER NOT NULL,
395                FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE,
396                FOREIGN KEY (resolved_source_id) REFERENCES files(id) ON DELETE SET NULL
397            )",
398            [],
399        )?;
400
401        conn.execute(
402            "CREATE INDEX IF NOT EXISTS idx_exports_file ON file_exports(file_id)",
403            [],
404        )?;
405
406        conn.execute(
407            "CREATE INDEX IF NOT EXISTS idx_exports_resolved ON file_exports(resolved_source_id)",
408            [],
409        )?;
410
411        conn.execute(
412            "CREATE INDEX IF NOT EXISTS idx_exports_symbol ON file_exports(exported_symbol)",
413            [],
414        )?;
415
416        conn.execute_batch("COMMIT")
417            .context("Failed to commit meta.db schema transaction")?;
418
419        log::debug!("Created meta.db with schema");
420        Ok(())
421    }
422
423    /// Add the fingerprint columns to a `files` table written before 2.0.0.
424    ///
425    /// `CREATE TABLE IF NOT EXISTS` leaves an existing table alone, and the first
426    /// non-`--force` `rfx index` on an old cache would otherwise fail its INSERT.
427    /// The schema hash already forces that index to rebuild every row, so the
428    /// columns only need to exist; their defaults are overwritten immediately.
429    fn migrate_files_columns(conn: &Connection) -> Result<()> {
430        const WANTED: [(&str, &str); 6] = [
431            ("size", "INTEGER NOT NULL DEFAULT 0"),
432            ("mtime_ns", "INTEGER NOT NULL DEFAULT 0"),
433            ("hash", "TEXT NOT NULL DEFAULT ''"),
434            ("dirty_at_index", "INTEGER NOT NULL DEFAULT 0"),
435            ("walk_seq", "INTEGER NOT NULL DEFAULT 0"),
436            ("vendored", "INTEGER NOT NULL DEFAULT 0"),
437        ];
438        let mut stmt = conn.prepare("SELECT name FROM pragma_table_info('files')")?;
439        let present: std::collections::HashSet<String> = stmt
440            .query_map([], |row| row.get::<_, String>(0))?
441            .collect::<Result<_, _>>()?;
442        for (name, decl) in WANTED {
443            if !present.contains(name) {
444                log::info!("meta.db: adding files.{} (older cache)", name);
445                conn.execute(
446                    &format!("ALTER TABLE files ADD COLUMN {} {}", name, decl),
447                    [],
448                )?;
449            }
450        }
451        Ok(())
452    }
453
454    /// Add the package-resolution columns (2.2.0) to an older `file_dependencies`,
455    /// for the same reason as [`Self::migrate_files_columns`]: the schema hash makes
456    /// the next index write every row again, but the columns must exist first.
457    fn migrate_dependency_columns(conn: &Connection) -> Result<()> {
458        let mut stmt = conn.prepare("SELECT name FROM pragma_table_info('file_dependencies')")?;
459        let present: std::collections::HashSet<String> = stmt
460            .query_map([], |row| row.get::<_, String>(0))?
461            .collect::<Result<_, _>>()?;
462        for name in ["resolved_package", "resolved_member"] {
463            if !present.contains(name) {
464                log::info!(
465                    "meta.db: adding file_dependencies.{} (pre-2.2.0 cache)",
466                    name
467                );
468                conn.execute(
469                    &format!("ALTER TABLE file_dependencies ADD COLUMN {} TEXT", name),
470                    [],
471                )?;
472            }
473        }
474        Ok(())
475    }
476
477    /// `path → fingerprint` for exactly the given paths, in 900-path chunks.
478    ///
479    /// The git freshness path asks only about the paths `git status` (and the
480    /// dirty-at-index set) name, never the whole table.
481    pub fn fingerprints_for(&self, paths: &[&str]) -> Result<HashMap<String, FileFingerprint>> {
482        let db_path = self.cache_path.join(META_DB);
483        if paths.is_empty() || !db_path.exists() {
484            return Ok(HashMap::new());
485        }
486        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
487        const BATCH_SIZE: usize = 900;
488        let mut out = HashMap::with_capacity(paths.len());
489        for chunk in paths.chunks(BATCH_SIZE) {
490            let placeholders = chunk.iter().map(|_| "?").collect::<Vec<_>>().join(", ");
491            let sql = format!(
492                "SELECT path, size, mtime_ns, hash FROM files WHERE path IN ({})",
493                placeholders
494            );
495            let mut stmt = conn.prepare(&sql)?;
496            let rows = stmt.query_map(rusqlite::params_from_iter(chunk.iter()), |row| {
497                Ok((
498                    row.get::<_, String>(0)?,
499                    FileFingerprint {
500                        size: row.get::<_, i64>(1)? as u64,
501                        mtime_ns: row.get::<_, i64>(2)?,
502                        hash: row.get::<_, String>(3)?,
503                    },
504                ))
505            })?;
506            for row in rows {
507                let (path, fp) = row?;
508                out.insert(path, fp);
509            }
510        }
511        Ok(out)
512    }
513
514    /// Every indexed path with its fingerprint.
515    ///
516    /// Used outside git, where the tree is walked and every file compared; the
517    /// query handle memoises the result until the index is rewritten.
518    pub fn load_fingerprints(&self) -> Result<HashMap<String, FileFingerprint>> {
519        let db_path = self.cache_path.join(META_DB);
520        if !db_path.exists() {
521            return Ok(HashMap::new());
522        }
523        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
524        let mut stmt = conn.prepare("SELECT path, size, mtime_ns, hash FROM files")?;
525        let rows = stmt.query_map([], |row| {
526            Ok((
527                row.get::<_, String>(0)?,
528                FileFingerprint {
529                    size: row.get::<_, i64>(1)? as u64,
530                    mtime_ns: row.get::<_, i64>(2)?,
531                    hash: row.get::<_, String>(3)?,
532                },
533            ))
534        })?;
535        rows.collect::<Result<HashMap<_, _>, _>>()
536            .context("Failed to read file fingerprints")
537    }
538
539    /// Initialize config.toml with defaults
540    fn init_config_toml(&self) -> Result<()> {
541        let config_path = self.cache_path.join(CONFIG_TOML);
542
543        if config_path.exists() {
544            return Ok(());
545        }
546
547        let default_config = r#"[index]
548languages = []  # Empty = all supported languages
549text_tier = true  # Also index docs, config and every other non-binary file
550# "tracked" (default): every non-binary file that is not gitignored and not under a
551#   dot-directory — ripgrep's defaults (hidden = true walks dot-directories). Lock and generated files are indexed but excluded from
552#   searches unless asked for (include_locks / include_generated / lang).
553# "allowlist": code plus a fixed docs/config extension list.
554mode = "tracked"
555hidden = false  # true also walks dot-directories (.githooks/), never .git/ or .reflex/
556max_file_size = 10485760  # 10 MB
557follow_symlinks = false
558
559[index.include]
560patterns = []
561
562[index.exclude]
563patterns = []
564
565# Vendored code (gitignore rules): searchable, but not in the import graph. Reflex
566# finds vendor/modules.txt, Composer, cargo vendor, node_modules, site-packages and
567# third_party/ itself; "!dir/" marks a directory as project code.
568[index.vendored]
569patterns = []
570
571[performance]
572parallel_threads = 0  # 0 = auto (80% of available cores, max 32), or set a specific number
573symbol_threads = 0  # background symbol pass; 0 = auto (50% of available cores, max 32)
574
575# AI provider settings for `rfx ask` / `rfx pulse` live in ~/.reflex/config.toml
576# (run `rfx llm config`), not here.
577"#;
578
579        std::fs::write(&config_path, default_config)?;
580
581        log::debug!("Created default config.toml");
582        Ok(())
583    }
584
585    /// Check if cache exists and is valid
586    pub fn exists(&self) -> bool {
587        self.cache_path.exists() && self.cache_path.join(META_DB).exists()
588    }
589
590    /// Validate cache integrity and detect corruption
591    ///
592    /// Performs basic integrity checks on the cache:
593    /// - Verifies all required files exist
594    /// - Checks SQLite database can be opened
595    /// - Validates binary file headers (trigrams.bin, content.bin)
596    ///
597    /// Returns Ok(()) if cache is valid, Err with details if corrupted.
598    pub fn validate(&self) -> Result<()> {
599        let start = std::time::Instant::now();
600
601        // Check if cache directory exists
602        if !self.cache_path.exists() {
603            anyhow::bail!(
604                "Cache directory does not exist: {}",
605                self.cache_path.display()
606            );
607        }
608
609        // Check meta.db exists and can be opened
610        let db_path = self.cache_path.join(META_DB);
611        if !db_path.exists() {
612            anyhow::bail!("Database file missing: {}", db_path.display());
613        }
614
615        // Try to open database
616        let conn =
617            open_meta_db(&db_path).context("Failed to open meta.db - database may be corrupted")?;
618
619        // Verify schema exists
620        let tables: Result<Vec<String>, _> = conn
621            .prepare("SELECT name FROM sqlite_master WHERE type='table'")
622            .and_then(|mut stmt| {
623                stmt.query_map([], |row| row.get(0))
624                    .map(|rows| rows.collect())
625            })
626            .and_then(|result| result);
627
628        match tables {
629            Ok(table_list) => {
630                // Check for required tables
631                let required_tables = vec![
632                    "files",
633                    "statistics",
634                    "config",
635                    "file_branches",
636                    "branches",
637                    "file_dependencies",
638                    "file_exports",
639                ];
640                for table in &required_tables {
641                    if !table_list.iter().any(|t| t == table) {
642                        anyhow::bail!("Required table '{}' missing from database schema", table);
643                    }
644                }
645            }
646            Err(e) => {
647                anyhow::bail!("Failed to read database schema: {}", e);
648            }
649        }
650
651        // Run SQLite integrity check (fast quick_check)
652        // Use quick_check instead of integrity_check for speed (<10ms vs 100ms+)
653        let integrity_result: String =
654            conn.query_row("PRAGMA quick_check", [], |row| row.get(0))?;
655
656        if integrity_result != "ok" {
657            log::warn!("Database integrity check failed: {}", integrity_result);
658            anyhow::bail!(
659                "Database integrity check failed: {}. Cache may be corrupted. \
660                 Run 'rfx index' to rebuild cache.",
661                integrity_result
662            );
663        }
664
665        // The stores the manifest names (or the fixed names of a cache without
666        // one); messages use the logical names.
667        let summary = crate::snapshot::store_summary(&self.cache_path);
668
669        // Check trigrams.bin if it exists
670        let trigrams_path = summary.trigram_files[0].clone();
671        if trigrams_path.exists() {
672            use std::io::Read;
673
674            match File::open(&trigrams_path) {
675                Ok(mut file) => {
676                    let mut header = [0u8; 4];
677                    match file.read_exact(&mut header) {
678                        Ok(_) => {
679                            // Check magic bytes
680                            if &header != b"RFTG" {
681                                log::warn!(
682                                    "trigrams.bin has invalid magic bytes - may be corrupted"
683                                );
684                                anyhow::bail!(
685                                    "trigrams.bin appears to be corrupted (invalid magic bytes)"
686                                );
687                            }
688                        }
689                        Err(_) => {
690                            anyhow::bail!("trigrams.bin is too small - appears to be corrupted");
691                        }
692                    }
693                }
694                Err(e) => {
695                    anyhow::bail!("Failed to open trigrams.bin: {}", e);
696                }
697            }
698        }
699
700        // Check content.bin if it exists
701        let content_path = summary.content_files[0].clone();
702        if content_path.exists() {
703            use std::io::Read;
704
705            match File::open(&content_path) {
706                Ok(mut file) => {
707                    let mut header = [0u8; 4];
708                    match file.read_exact(&mut header) {
709                        Ok(_) => {
710                            // Check magic bytes
711                            if &header != b"RFCT" {
712                                log::warn!(
713                                    "content.bin has invalid magic bytes - may be corrupted"
714                                );
715                                anyhow::bail!(
716                                    "content.bin appears to be corrupted (invalid magic bytes)"
717                                );
718                            }
719                        }
720                        Err(_) => {
721                            anyhow::bail!("content.bin is too small - appears to be corrupted");
722                        }
723                    }
724                }
725                Err(e) => {
726                    anyhow::bail!("Failed to open content.bin: {}", e);
727                }
728            }
729        }
730
731        // NOT checked here any more: the schema hash.
732        //
733        // `validate()` runs on EVERY search (query/mod.rs), and a bail here becomes
734        // ReflexError::CacheCorrupted, which the MCP layer answers by force-rebuilding
735        // the index. With several Reflex versions sharing one `.reflex/` — three
736        // `rfx mcp` servers from three Claude Code sessions, in the field report —
737        // each one saw a mismatch, each force-rebuilt, and they streamed into
738        // content.bin concurrently. That is what produced `content.bin is too small`.
739        //
740        // A version mismatch is not corruption. Readers are now allowed through and
741        // the mismatch surfaces via `get_index_status` as stale with
742        // can_trust_results: false, naming the owner version. WRITERS refuse — see
743        // `assert_writable`. Structural checks above (magic bytes, short files,
744        // quick_check) still bail, because those really are corruption.
745
746        log::debug!("Cache validation passed (took {:?})", start.elapsed());
747        Ok(())
748    }
749
750    /// Get the path to the cache directory
751    pub fn path(&self) -> &Path {
752        &self.cache_path
753    }
754
755    /// Get the workspace root directory (parent of .reflex/)
756    pub fn workspace_root(&self) -> PathBuf {
757        self.cache_path
758            .parent()
759            .expect(".reflex directory should have a parent")
760            .to_path_buf()
761    }
762
763    /// The config every index run in this workspace uses: `.reflex/config.toml`,
764    /// with `languages` replaced by `languages` when it is not empty, else by the
765    /// `--languages` of the last `rfx index` run that passed one.
766    ///
767    /// `rfx index`, automatic updates, `index_project`, `POST /index`, `rfx watch`
768    /// and interactive mode all start here, so they index the same file set the
769    /// freshness check expects.
770    pub fn effective_index_config(
771        &self,
772        languages: &[crate::models::Language],
773    ) -> Result<crate::models::IndexConfig> {
774        let mut config = self.load_index_config()?;
775        if !languages.is_empty() {
776            config.languages = languages.to_vec();
777        } else if let Some(saved) = self.languages_override() {
778            config.languages = saved;
779        }
780        Ok(config)
781    }
782
783    /// The `--languages` of the last `rfx index` run that passed one, if any.
784    fn languages_override(&self) -> Option<Vec<crate::models::Language>> {
785        let db_path = self.cache_path.join(META_DB);
786        if !db_path.exists() {
787            return None;
788        }
789        let conn = open_meta_db(&db_path).ok()?;
790        let raw = crate::meta_update::get_statistic(&conn, LANGUAGES_OVERRIDE_KEY)
791            .ok()
792            .flatten()?;
793        serde_json::from_str(&raw).ok()
794    }
795
796    /// Record the `--languages` of an `rfx index` run (empty: none was passed),
797    /// so later automatic updates index the same languages.
798    pub fn set_languages_override(&self, languages: &[crate::models::Language]) -> Result<()> {
799        let conn = open_meta_db(self.cache_path.join(META_DB))?;
800        if languages.is_empty() {
801            conn.execute(
802                "DELETE FROM statistics WHERE key = ?",
803                [LANGUAGES_OVERRIDE_KEY],
804            )?;
805        } else {
806            crate::meta_update::set_statistic(
807                &conn,
808                LANGUAGES_OVERRIDE_KEY,
809                &serde_json::to_string(languages)?,
810                chrono::Utc::now().timestamp(),
811            )?;
812        }
813        Ok(())
814    }
815
816    /// Load IndexConfig from `.reflex/config.toml` if it exists.
817    ///
818    /// Returns `IndexConfig::default()` when the file is absent or a section
819    /// is missing.  Parse errors are surfaced so the user gets a clear message
820    /// rather than silently falling back to defaults.
821    pub fn load_index_config(&self) -> Result<crate::models::IndexConfig> {
822        use crate::models::{IndexConfig, Language};
823
824        let config_path = self.cache_path.join(CONFIG_TOML);
825        if !config_path.exists() {
826            return Ok(IndexConfig::default());
827        }
828
829        let raw = std::fs::read_to_string(&config_path)
830            .with_context(|| format!("Failed to read {}", config_path.display()))?;
831
832        let toml_val: toml::Value = toml::from_str(&raw)
833            .with_context(|| format!("Failed to parse {}", config_path.display()))?;
834
835        let mut cfg = IndexConfig::default();
836
837        if let Some(index_tbl) = toml_val.get("index") {
838            if let Some(langs) = index_tbl.get("languages").and_then(|v| v.as_array()) {
839                let parsed: Vec<Language> = langs
840                    .iter()
841                    .filter_map(|v| v.as_str())
842                    .filter_map(|s| {
843                        Language::from_name(s).or_else(|| {
844                            log::warn!(
845                                "Unknown language '{}' in config.toml [index] section — ignoring",
846                                s
847                            );
848                            None
849                        })
850                    })
851                    .collect();
852                if !parsed.is_empty() {
853                    cfg.languages = parsed;
854                }
855            }
856            if let Some(text_tier) = index_tbl.get("text_tier").and_then(|v| v.as_bool()) {
857                cfg.text_tier = text_tier;
858            }
859            if let Some(mode) = index_tbl.get("mode").and_then(|v| v.as_str()) {
860                match crate::models::IndexMode::from_name(mode) {
861                    Some(m) => cfg.mode = m,
862                    None => log::warn!(
863                        "Unknown [index] mode '{}' in config.toml (expected \"tracked\" or \
864                         \"allowlist\") — using \"tracked\"",
865                        mode
866                    ),
867                }
868            }
869            if let Some(hidden) = index_tbl.get("hidden").and_then(|v| v.as_bool()) {
870                cfg.hidden = hidden;
871            }
872
873            if let Some(max_size) = index_tbl.get("max_file_size").and_then(|v| v.as_integer()) {
874                cfg.max_file_size = max_size as usize;
875            }
876            if let Some(follow) = index_tbl.get("follow_symlinks").and_then(|v| v.as_bool()) {
877                cfg.follow_symlinks = follow;
878            }
879            if let Some(include) = index_tbl
880                .get("include")
881                .and_then(|v| v.get("patterns"))
882                .and_then(|v| v.as_array())
883            {
884                cfg.include_patterns = include
885                    .iter()
886                    .filter_map(|v| v.as_str().map(String::from))
887                    .collect();
888            }
889            if let Some(exclude) = index_tbl
890                .get("exclude")
891                .and_then(|v| v.get("patterns"))
892                .and_then(|v| v.as_array())
893            {
894                cfg.exclude_patterns = exclude
895                    .iter()
896                    .filter_map(|v| v.as_str().map(String::from))
897                    .collect();
898            }
899            if let Some(vendored) = index_tbl
900                .get("vendored")
901                .and_then(|v| v.get("patterns"))
902                .and_then(|v| v.as_array())
903            {
904                cfg.vendored_patterns = vendored
905                    .iter()
906                    .filter_map(|v| v.as_str().map(String::from))
907                    .collect();
908            }
909        }
910
911        if let Some(perf) = toml_val.get("performance")
912            && let Some(threads) = perf.get("parallel_threads").and_then(|v| v.as_integer())
913        {
914            cfg.parallel_threads = threads as usize;
915        }
916        if let Some(perf) = toml_val.get("performance")
917            && let Some(threads) = perf.get("symbol_threads").and_then(|v| v.as_integer())
918        {
919            cfg.symbol_threads = threads.max(0) as usize;
920        }
921
922        log::debug!("Loaded IndexConfig from config.toml: {:?}", cfg);
923        Ok(cfg)
924    }
925
926    /// Clear the entire cache
927    pub fn clear(&self) -> Result<()> {
928        log::info!("Clearing cache at {:?}", self.cache_path);
929
930        if !self.cache_path.exists() {
931            return Ok(());
932        }
933
934        // No query in this process may keep serving from the files about to go.
935        crate::query::invalidate_caches(&self.workspace_root());
936
937        // Hold the workspace index lock while deleting so we never pull
938        // content.bin out from under a running indexer. Everything except the
939        // lock file goes while the lock is held; the lock file and the (now
940        // empty) directory are removed afterwards, best-effort, so callers
941        // that expect `.reflex/` to vanish keep working.
942        let lock =
943            crate::atomic_write::IndexLock::try_acquire(&self.cache_path)?.ok_or_else(|| {
944                crate::errors::ReflexError::IndexLocked(
945                    crate::atomic_write::IndexLock::lock_path(&self.cache_path)
946                        .display()
947                        .to_string(),
948                )
949            })?;
950
951        for entry in std::fs::read_dir(&self.cache_path)? {
952            let entry = entry?;
953            let path = entry.path();
954            if path.file_name().and_then(|n| n.to_str())
955                == Some(crate::atomic_write::INDEX_LOCK_FILE)
956            {
957                continue;
958            }
959            if path.is_dir() {
960                std::fs::remove_dir_all(&path)?;
961            } else {
962                std::fs::remove_file(&path)?;
963            }
964        }
965
966        let lock_path = lock.path().to_path_buf();
967        drop(lock);
968        let _ = std::fs::remove_file(&lock_path);
969        let _ = std::fs::remove_dir(&self.cache_path);
970
971        Ok(())
972    }
973
974    /// Force SQLite WAL (Write-Ahead Log) checkpoint
975    ///
976    /// Ensures all data written in transactions is flushed to the main database file.
977    /// This is critical when spawning background processes that open new connections,
978    /// as they need to see the committed data immediately.
979    ///
980    /// Uses TRUNCATE mode to completely flush and reset the WAL file.
981    pub fn checkpoint_wal(&self) -> Result<()> {
982        let db_path = self.cache_path.join(META_DB);
983
984        if !db_path.exists() {
985            // No database to checkpoint
986            return Ok(());
987        }
988
989        let conn = open_meta_db(&db_path).context("Failed to open meta.db for WAL checkpoint")?;
990
991        // PRAGMA wal_checkpoint(TRUNCATE) forces a full checkpoint and truncates the WAL
992        // This ensures background processes see all committed data
993        // Note: Returns (busy, log_pages, checkpointed_pages) - use query instead of execute
994        conn.query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |row| {
995            let busy: i64 = row.get(0)?;
996            let log_pages: i64 = row.get(1)?;
997            let checkpointed: i64 = row.get(2)?;
998            log::debug!(
999                "WAL checkpoint completed: busy={}, log_pages={}, checkpointed_pages={}",
1000                busy,
1001                log_pages,
1002                checkpointed
1003            );
1004            Ok(())
1005        })
1006        .context("Failed to execute WAL checkpoint")?;
1007
1008        log::debug!("Executed WAL checkpoint (TRUNCATE) on meta.db");
1009        Ok(())
1010    }
1011
1012    /// `path → (file_id, hash)` for every indexed file, in one query.
1013    ///
1014    /// What the background symbol pass needs to decide, without touching SQLite
1015    /// again, which files are already cached and which ids to write. The hash is
1016    /// `files.hash`, the hash of the bytes in the stores: a branch row's hash can
1017    /// name another version of the file once other branches' rows are kept.
1018    pub fn load_all_file_rows(&self) -> Result<HashMap<String, (i64, String)>> {
1019        let db_path = self.cache_path.join(META_DB);
1020        if !db_path.exists() {
1021            return Ok(HashMap::new());
1022        }
1023        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1024        let mut stmt = conn.prepare("SELECT path, id, hash FROM files")?;
1025        let rows: HashMap<String, (i64, String)> = stmt
1026            .query_map([], |row| {
1027                Ok((
1028                    row.get(0)?,
1029                    (row.get::<_, i64>(1)?, row.get::<_, String>(2)?),
1030                ))
1031            })?
1032            .collect::<Result<HashMap<_, _>, _>>()?;
1033        Ok(rows)
1034    }
1035
1036    pub fn load_all_hashes(&self) -> Result<HashMap<String, String>> {
1037        let db_path = self.cache_path.join(META_DB);
1038
1039        if !db_path.exists() {
1040            return Ok(HashMap::new());
1041        }
1042
1043        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1044
1045        // Get all hashes from file_branches, joined with files to get paths
1046        // If a file appears in multiple branches, we'll get multiple entries
1047        // (HashMap will keep the last one, which is fine for background indexer)
1048        let mut stmt = conn.prepare(
1049            "SELECT f.path, fb.hash
1050             FROM file_branches fb
1051             JOIN files f ON fb.file_id = f.id",
1052        )?;
1053        let hashes: HashMap<String, String> = stmt
1054            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?
1055            .collect::<Result<HashMap<_, _>, _>>()?;
1056
1057        log::debug!(
1058            "Loaded {} file hashes across all branches from SQLite",
1059            hashes.len()
1060        );
1061        Ok(hashes)
1062    }
1063
1064    /// Load file hashes for a specific branch from SQLite
1065    ///
1066    /// Used by indexer and query engine to get hashes for the current branch.
1067    /// This ensures branch-specific incremental indexing and symbol cache lookups.
1068    pub fn load_hashes_for_branch(&self, branch: &str) -> Result<HashMap<String, String>> {
1069        let db_path = self.cache_path.join(META_DB);
1070
1071        if !db_path.exists() {
1072            return Ok(HashMap::new());
1073        }
1074
1075        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1076
1077        // Get hashes for specific branch only
1078        let mut stmt = conn.prepare(
1079            "SELECT f.path, fb.hash
1080             FROM file_branches fb
1081             JOIN files f ON fb.file_id = f.id
1082             JOIN branches b ON fb.branch_id = b.id
1083             WHERE b.name = ?",
1084        )?;
1085        let hashes: HashMap<String, String> = stmt
1086            .query_map([branch], |row| Ok((row.get(0)?, row.get(1)?)))?
1087            .collect::<Result<HashMap<_, _>, _>>()?;
1088
1089        log::debug!(
1090            "Loaded {} file hashes for branch '{}' from SQLite",
1091            hashes.len(),
1092            branch
1093        );
1094        Ok(hashes)
1095    }
1096
1097    /// `path → (file_id, hash)` for the given paths only, `hash` = `files.hash`.
1098    ///
1099    /// The symbol path used to load every hash on the branch (a three-way join over
1100    /// the whole index) and then look up every candidate's file id in a second
1101    /// query. A `--symbols` query touches tens of files; this asks for exactly
1102    /// those, in 900-path chunks, on a connection the caller already holds. The
1103    /// key is the hash of the stored bytes, so a checkout without a reindex can
1104    /// never cache one version's symbols under another version's hash.
1105    pub fn file_rows_on(
1106        conn: &Connection,
1107        paths: &[String],
1108    ) -> Result<HashMap<String, (i64, String)>> {
1109        const BATCH_SIZE: usize = 900;
1110        let mut out = HashMap::with_capacity(paths.len());
1111        for chunk in paths.chunks(BATCH_SIZE) {
1112            let placeholders = chunk.iter().map(|_| "?").collect::<Vec<_>>().join(", ");
1113            let sql = format!(
1114                "SELECT path, id, hash FROM files WHERE path IN ({})",
1115                placeholders
1116            );
1117            let mut stmt = conn.prepare(&sql)?;
1118            let rows = stmt.query_map(rusqlite::params_from_iter(chunk.iter()), |row| {
1119                Ok((
1120                    row.get::<_, String>(0)?,
1121                    row.get::<_, i64>(1)?,
1122                    row.get::<_, String>(2)?,
1123                ))
1124            })?;
1125            for row in rows {
1126                let (path, id, hash) = row?;
1127                out.insert(path, (id, hash));
1128            }
1129        }
1130        Ok(out)
1131    }
1132
1133    /// Save file hashes for incremental indexing
1134    ///
1135    /// DEPRECATED: Hashes are now saved via record_branch_file() or batch_record_branch_files().
1136    /// This method is kept for backward compatibility but does nothing.
1137    #[deprecated(note = "Hashes are now stored in file_branches table via record_branch_file()")]
1138    pub fn save_hashes(&self, _hashes: &HashMap<String, String>) -> Result<()> {
1139        // No-op: hashes are now persisted to SQLite in record_branch_file()
1140        Ok(())
1141    }
1142
1143    /// Update file metadata in the files table
1144    ///
1145    /// Note: File content hashes are stored separately in the file_branches table
1146    /// via record_branch_file() or batch_record_branch_files().
1147    pub fn update_file(&self, path: &str, language: &str, line_count: usize) -> Result<()> {
1148        let db_path = self.cache_path.join(META_DB);
1149        let conn = open_meta_db(&db_path).context("Failed to open meta.db for file update")?;
1150
1151        let now = chrono::Utc::now().timestamp();
1152
1153        conn.execute(
1154            "INSERT OR REPLACE INTO files (path, last_indexed, language, line_count)
1155             VALUES (?, ?, ?, ?)",
1156            [path, &now.to_string(), language, &line_count.to_string()],
1157        )?;
1158
1159        Ok(())
1160    }
1161
1162    /// Batch update multiple files in a single transaction for performance
1163    ///
1164    /// Note: File content hashes are stored separately in the file_branches table
1165    /// via batch_update_files_and_branch().
1166    pub fn batch_update_files(&self, files: &[(String, String, usize)]) -> Result<()> {
1167        let db_path = self.cache_path.join(META_DB);
1168        let mut conn = open_meta_db(&db_path).context("Failed to open meta.db for batch update")?;
1169
1170        let now = chrono::Utc::now().timestamp();
1171        let now_str = now.to_string();
1172
1173        // Use a transaction for batch inserts
1174        let tx = conn.transaction()?;
1175
1176        for (path, language, line_count) in files {
1177            tx.execute(
1178                "INSERT OR REPLACE INTO files (path, last_indexed, language, line_count)
1179                 VALUES (?, ?, ?, ?)",
1180                [
1181                    path.as_str(),
1182                    &now_str,
1183                    language.as_str(),
1184                    &line_count.to_string(),
1185                ],
1186            )?;
1187        }
1188
1189        tx.commit()?;
1190        Ok(())
1191    }
1192
1193    /// Update statistics after indexing by calculating totals from database for a specific branch
1194    ///
1195    /// Counts only files indexed for the given branch, not all files across all branches.
1196    pub fn update_stats(&self, branch: &str) -> Result<()> {
1197        let db_path = self.cache_path.join(META_DB);
1198        let conn = open_meta_db(&db_path).context("Failed to open meta.db for stats update")?;
1199        Self::update_stats_on(&conn, branch)
1200    }
1201
1202    /// Record `total_files` (and its `updated_at`, the "Last updated" time) as `n`:
1203    /// what [`Self::update_stats_on`] counts, for a caller that knows every file
1204    /// has its branch row.
1205    pub(crate) fn set_total_files_on(conn: &Connection, n: usize, now: i64) -> Result<()> {
1206        conn.execute(
1207            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1208            ["total_files", &n.to_string(), &now.to_string()],
1209        )?;
1210        Ok(())
1211    }
1212
1213    /// [`Self::update_stats`] on an open connection (inside the caller's transaction).
1214    pub(crate) fn update_stats_on(conn: &Connection, branch: &str) -> Result<()> {
1215        // Count files for specific branch only (branch-aware statistics)
1216        let total_files: usize = conn
1217            .query_row(
1218                "SELECT COUNT(DISTINCT fb.file_id)
1219             FROM file_branches fb
1220             JOIN branches b ON fb.branch_id = b.id
1221             WHERE b.name = ?",
1222                [branch],
1223                |row| row.get(0),
1224            )
1225            .unwrap_or(0);
1226
1227        let now = chrono::Utc::now().timestamp();
1228
1229        conn.execute(
1230            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1231            ["total_files", &total_files.to_string(), &now.to_string()],
1232        )?;
1233
1234        log::debug!(
1235            "Updated statistics for branch '{}': {} files",
1236            branch,
1237            total_files
1238        );
1239        Ok(())
1240    }
1241
1242    /// Check if the stored schema hash matches the current binary's hash.
1243    /// Returns Ok(true) if they match, Ok(false) if they don't, Err on DB errors.
1244    pub fn check_schema_hash(&self) -> Result<bool> {
1245        let db_path = self.cache_path.join(META_DB);
1246        if !db_path.exists() {
1247            return Ok(false);
1248        }
1249        let conn = open_meta_db(&db_path)?;
1250        Self::check_schema_hash_on(&conn)
1251    }
1252
1253    fn check_schema_hash_on(conn: &Connection) -> Result<bool> {
1254        let current = env!("CACHE_SCHEMA_HASH");
1255        let stored: Option<String> = conn
1256            .query_row(
1257                "SELECT value FROM statistics WHERE key = 'schema_hash'",
1258                [],
1259                |row| row.get(0),
1260            )
1261            .optional()?;
1262        Ok(stored.as_deref() == Some(current))
1263    }
1264
1265    /// Whether this cache's dependency, export and symbol rows were written by
1266    /// this binary's extraction code (see `build.rs`, `EXTRACTION_HASH`).
1267    pub fn check_extraction_hash(&self) -> Result<bool> {
1268        let db_path = self.cache_path.join(META_DB);
1269        if !db_path.exists() {
1270            return Ok(false);
1271        }
1272        let conn = open_meta_db(&db_path)?;
1273        let stored: Option<String> = conn
1274            .query_row(
1275                "SELECT value FROM statistics WHERE key = 'extraction_hash'",
1276                [],
1277                |row| row.get(0),
1278            )
1279            .optional()?;
1280        Ok(stored.as_deref() == Some(env!("EXTRACTION_HASH")))
1281    }
1282
1283    /// Stamp the extraction hash; called at the end of a complete index run.
1284    pub fn update_extraction_hash(&self) -> Result<()> {
1285        let conn = open_meta_db(self.cache_path.join(META_DB))
1286            .context("Failed to open meta.db for extraction hash update")?;
1287        Self::update_extraction_hash_on(&conn)
1288    }
1289
1290    /// [`Self::update_extraction_hash`] on an open connection.
1291    pub(crate) fn update_extraction_hash_on(conn: &Connection) -> Result<()> {
1292        conn.execute(
1293            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1294            [
1295                "extraction_hash",
1296                env!("EXTRACTION_HASH"),
1297                &chrono::Utc::now().timestamp().to_string(),
1298            ],
1299        )?;
1300        Ok(())
1301    }
1302
1303    /// Delete every symbol cache row; returns how many. A cache without the
1304    /// symbols table (no symbol pass has run) has nothing to delete.
1305    pub fn clear_symbol_cache(&self) -> Result<usize> {
1306        let db_path = self.cache_path.join(META_DB);
1307        if !db_path.exists() {
1308            return Ok(0);
1309        }
1310        let conn = open_meta_db(&db_path)?;
1311        let has_table: bool = conn
1312            .query_row(
1313                "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'symbols'",
1314                [],
1315                |row| row.get::<_, i64>(0),
1316            )
1317            .map(|n| n > 0)?;
1318        if !has_table {
1319            return Ok(0);
1320        }
1321        Ok(conn.execute("DELETE FROM symbols", [])?)
1322    }
1323
1324    /// Everything the freshness check reads from `meta.db`, on ONE connection.
1325    ///
1326    /// The per-query status check used to open three connections (`check_schema_hash`,
1327    /// `branch_exists`, `get_branch_info`); on a 35 MB database each open is not free.
1328    /// `branch` is `None` outside git, in which case only the schema is read.
1329    pub fn status_reads(&self, branch: Option<&str>) -> Result<StatusReads> {
1330        let db_path = self.cache_path.join(META_DB);
1331        if !db_path.exists() {
1332            return Ok(StatusReads {
1333                schema_ok: false,
1334                owner: None,
1335                branch_indexed: false,
1336                branch_info: None,
1337                dirty_at_index: Vec::new(),
1338                rule_files: None,
1339            });
1340        }
1341        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1342
1343        let schema_ok = Self::check_schema_hash_on(&conn).unwrap_or(true);
1344        if !schema_ok {
1345            return Ok(StatusReads {
1346                schema_ok,
1347                owner: Self::cache_owner_on(&conn),
1348                branch_indexed: false,
1349                branch_info: None,
1350                dirty_at_index: Vec::new(),
1351                rule_files: None,
1352            });
1353        }
1354
1355        let rule_files = crate::meta_update::get_statistic(&conn, crate::indexer::RULE_FILES_KEY)
1356            .ok()
1357            .flatten();
1358        let Some(branch) = branch else {
1359            return Ok(StatusReads {
1360                schema_ok,
1361                owner: None,
1362                branch_indexed: false,
1363                branch_info: None,
1364                dirty_at_index: Vec::new(),
1365                rule_files,
1366            });
1367        };
1368
1369        let branch_indexed = Self::branch_exists_on(&conn, branch);
1370        // The `files` table (and content.bin) is global: the baseline is the tree
1371        // the LAST run indexed, whichever branch that was. Its row says which
1372        // commit and when. The current branch's own row is not the baseline:
1373        // after `checkout main` from an indexed side branch, main's row still
1374        // names main's commit, and comparing against it reported `fresh` while the
1375        // index held the side branch's files (2.0.3). Freshness is judged by file
1376        // content, so a branch switch that leaves every byte unchanged is fresh.
1377        let synced =
1378            crate::meta_update::get_statistic(&conn, crate::meta_update::SYNCED_BRANCH_KEY)
1379                .ok()
1380                .flatten();
1381        let branch_info = match synced
1382            .as_deref()
1383            .and_then(|b| Self::get_branch_info_on(&conn, b).ok())
1384        {
1385            Some(info) => Some(info),
1386            None if branch_indexed => Self::get_branch_info_on(&conn, branch).ok(),
1387            None => Self::latest_branch_info_on(&conn).ok(),
1388        };
1389
1390        Ok(StatusReads {
1391            schema_ok,
1392            owner: None,
1393            branch_indexed,
1394            branch_info,
1395            dirty_at_index: Self::dirty_at_index_on(&conn).unwrap_or_default(),
1396            rule_files,
1397        })
1398    }
1399
1400    /// Paths that `git status` listed when the index was last written.
1401    fn dirty_at_index_on(conn: &Connection) -> Result<Vec<String>> {
1402        let mut stmt = conn.prepare("SELECT path FROM files WHERE dirty_at_index = 1")?;
1403        let rows = stmt.query_map([], |row| row.get::<_, String>(0))?;
1404        Ok(rows.collect::<Result<Vec<_>, _>>()?)
1405    }
1406
1407    /// Who wrote this cache: `(version, git_sha)`, when the cache records it.
1408    ///
1409    /// `None` for a cache written before 1.7.2, or none at all.
1410    pub fn cache_owner(&self) -> Option<(String, Option<String>)> {
1411        let db_path = self.cache_path.join(META_DB);
1412        if !db_path.exists() {
1413            return None;
1414        }
1415        let conn = open_meta_db(&db_path).ok()?;
1416        Self::cache_owner_on(&conn)
1417    }
1418
1419    fn cache_owner_on(conn: &Connection) -> Option<(String, Option<String>)> {
1420        let get = |key: &str| -> Option<String> {
1421            conn.query_row("SELECT value FROM statistics WHERE key = ?", [key], |row| {
1422                row.get(0)
1423            })
1424            .optional()
1425            .ok()
1426            .flatten()
1427        };
1428        get("writer_version").map(|v| (v, get("writer_git_sha")))
1429    }
1430
1431    /// Refuse to write a cache a DIFFERENT RELEASED VERSION owns.
1432    ///
1433    /// Cross-version writers into one `.reflex/` is a corruption vector: the field
1434    /// report had three `rfx mcp` servers at two versions sharing a cache, and 1.6.0
1435    /// had already produced `content.bin is too small`.
1436    ///
1437    /// Scoped deliberately narrowly, to the one case that is actually unsafe and
1438    /// actually detectable:
1439    ///
1440    /// * A differing SCHEMA HASH alone is NOT refused. It flips on any change to
1441    ///   cache-critical sources, so it fires for every user on every upgrade and for
1442    ///   every developer on every branch switch. A full rebuild is what it already
1443    ///   triggers, it happens under the workspace `IndexLock`, and it truncates the
1444    ///   binary stores — which is safe.
1445    /// * An UNSTAMPED cache is adopted, not refused. Everything written before 1.7.2
1446    ///   is unstamped, so refusing would break every upgrade.
1447    /// * A cache stamped by a different released version IS refused, because that is
1448    ///   the multi-version-sharing case, and only there can the error name who owns it.
1449    ///
1450    /// `force` (which clears the cache first) and `REFLEX_ALLOW_SCHEMA_REBUILD=1`
1451    /// always pass — taking ownership is what force means.
1452    pub fn assert_writable(&self, force: bool) -> Result<()> {
1453        if force || std::env::var("REFLEX_ALLOW_SCHEMA_REBUILD").is_ok() {
1454            return Ok(());
1455        }
1456
1457        if !self.cache_path.join(META_DB).exists() {
1458            return Ok(());
1459        }
1460
1461        let Some((owner_version, owner_sha)) = self.cache_owner() else {
1462            // Unstamped: written before 1.7.2. Adopt it.
1463            return Ok(());
1464        };
1465
1466        if owner_version == env!("CARGO_PKG_VERSION") {
1467            return Ok(());
1468        }
1469
1470        Err(crate::errors::ReflexError::CacheVersionMismatch {
1471            owner_version,
1472            owner_sha: owner_sha
1473                .map(|s| format!(" (sha {})", &s[..s.len().min(7)]))
1474                .unwrap_or_default(),
1475            this_version: env!("CARGO_PKG_VERSION").to_string(),
1476        }
1477        .into())
1478    }
1479
1480    /// Update cache schema hash in statistics table
1481    ///
1482    /// This should be called after every index operation to ensure the cache
1483    /// is marked as compatible with the current binary version.
1484    pub fn update_schema_hash(&self) -> Result<()> {
1485        let db_path = self.cache_path.join(META_DB);
1486        let conn =
1487            open_meta_db(&db_path).context("Failed to open meta.db for schema hash update")?;
1488        Self::update_schema_hash_on(&conn)
1489    }
1490
1491    /// [`Self::update_schema_hash`] on an open connection.
1492    pub(crate) fn update_schema_hash_on(conn: &Connection) -> Result<()> {
1493        let schema_hash = env!("CACHE_SCHEMA_HASH");
1494        let now = chrono::Utc::now().timestamp();
1495
1496        conn.execute(
1497            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1498            ["schema_hash", schema_hash, &now.to_string()],
1499        )?;
1500        // Keep ownership in step with the hash, so a refusal can always name a version.
1501        conn.execute(
1502            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1503            [
1504                "writer_version",
1505                env!("CARGO_PKG_VERSION"),
1506                &now.to_string(),
1507            ],
1508        )?;
1509        if let Some(sha) = option_env!("REFLEX_GIT_SHA") {
1510            conn.execute(
1511                "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
1512                ["writer_git_sha", sha, &now.to_string()],
1513            )?;
1514        }
1515
1516        log::debug!("Updated schema hash to: {}", schema_hash);
1517        Ok(())
1518    }
1519
1520    /// Get list of all indexed files
1521    pub fn list_files(&self) -> Result<Vec<IndexedFile>> {
1522        let db_path = self.cache_path.join(META_DB);
1523
1524        if !db_path.exists() {
1525            return Ok(Vec::new());
1526        }
1527
1528        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1529
1530        let mut stmt =
1531            conn.prepare("SELECT path, language, last_indexed FROM files ORDER BY path")?;
1532
1533        let files = stmt
1534            .query_map([], |row| {
1535                let path: String = row.get(0)?;
1536                let language: String = row.get(1)?;
1537                let last_indexed: i64 = row.get(2)?;
1538
1539                Ok(IndexedFile {
1540                    path,
1541                    language,
1542                    last_indexed: chrono::DateTime::from_timestamp(last_indexed, 0)
1543                        .unwrap_or_else(chrono::Utc::now)
1544                        .to_rfc3339(),
1545                })
1546            })?
1547            .collect::<Result<Vec<_>, _>>()?;
1548
1549        Ok(files)
1550    }
1551
1552    /// Get statistics about the current cache
1553    ///
1554    /// Returns statistics for the current git branch if in a git repo,
1555    /// or global statistics if not in a git repo.
1556    pub fn stats(&self) -> Result<crate::models::IndexStats> {
1557        let db_path = self.cache_path.join(META_DB);
1558
1559        if !db_path.exists() {
1560            // Cache not initialized
1561            return Ok(crate::models::IndexStats {
1562                total_files: 0,
1563                index_size_bytes: 0,
1564                last_updated: chrono::Utc::now().to_rfc3339(),
1565                files_by_language: std::collections::HashMap::new(),
1566                lines_by_language: std::collections::HashMap::new(),
1567                ..Default::default()
1568            });
1569        }
1570
1571        // Determine current branch for branch-aware statistics
1572        let workspace_root = self.workspace_root();
1573        let current_branch = if crate::git::is_git_repo(&workspace_root) {
1574            crate::git::get_git_state(&workspace_root)
1575                .ok()
1576                .map(|state| state.branch)
1577        } else {
1578            Some("_default".to_string())
1579        };
1580        self.stats_on_branch(current_branch)
1581    }
1582
1583    /// [`stats`](Self::stats) for a branch the caller already knows (`"_default"`
1584    /// outside git), without running git again.
1585    pub fn stats_on_branch(
1586        &self,
1587        current_branch: Option<String>,
1588    ) -> Result<crate::models::IndexStats> {
1589        let db_path = self.cache_path.join(META_DB);
1590        if !db_path.exists() {
1591            return self.stats();
1592        }
1593        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
1594
1595        log::debug!("stats(): current_branch = {:?}", current_branch);
1596
1597        // Read total files (branch-aware)
1598        let total_files: usize = if let Some(ref branch) = current_branch {
1599            log::debug!("stats(): Counting files for branch '{}'", branch);
1600
1601            // Debug: Check all branches (two full scans: only when debug is on)
1602            let debug = log::log_enabled!(log::Level::Debug);
1603            let branches: Vec<(i64, String, i64)> = if !debug {
1604                Vec::new()
1605            } else {
1606                conn.prepare("SELECT id, name, file_count FROM branches")
1607                    .and_then(|mut stmt| {
1608                        stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
1609                            .map(|rows| rows.collect())
1610                    })
1611                    .and_then(|result| result)
1612                    .unwrap_or_default()
1613            };
1614
1615            for (id, name, count) in &branches {
1616                log::debug!(
1617                    "stats(): Branch ID={}, Name='{}', FileCount={}",
1618                    id,
1619                    name,
1620                    count
1621                );
1622            }
1623
1624            // Debug: Count file_branches per branch
1625            let fb_counts: Vec<(String, i64)> = if !debug {
1626                Vec::new()
1627            } else {
1628                conn.prepare(
1629                    "SELECT b.name, COUNT(*) FROM file_branches fb
1630                 JOIN branches b ON fb.branch_id = b.id
1631                 GROUP BY b.name",
1632                )
1633                .and_then(|mut stmt| {
1634                    stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
1635                        .map(|rows| rows.collect())
1636                })
1637                .and_then(|result| result)
1638                .unwrap_or_default()
1639            };
1640
1641            for (name, count) in &fb_counts {
1642                log::debug!(
1643                    "stats(): file_branches count for branch '{}': {}",
1644                    name,
1645                    count
1646                );
1647            }
1648
1649            // Count files for current branch only
1650            let count: usize = conn
1651                .query_row(
1652                    "SELECT COUNT(DISTINCT fb.file_id)
1653                 FROM file_branches fb
1654                 JOIN branches b ON fb.branch_id = b.id
1655                 WHERE b.name = ?",
1656                    [branch],
1657                    |row| row.get(0),
1658                )
1659                .unwrap_or(0);
1660
1661            log::debug!("stats(): Query returned total_files = {}", count);
1662            count
1663        } else {
1664            // No branch info - should not happen, but return 0
1665            log::warn!("stats(): No current_branch detected!");
1666            0
1667        };
1668
1669        // Read last updated timestamp
1670        let last_updated: String = conn
1671            .query_row(
1672                "SELECT updated_at FROM statistics WHERE key = 'total_files'",
1673                [],
1674                |row| {
1675                    let timestamp: i64 = row.get(0)?;
1676                    Ok(chrono::DateTime::from_timestamp(timestamp, 0)
1677                        .unwrap_or_else(chrono::Utc::now)
1678                        .to_rfc3339())
1679                },
1680            )
1681            .unwrap_or_else(|_| chrono::Utc::now().to_rfc3339());
1682
1683        let (index_size_bytes, trigram_index_bytes, corpus_bytes) = self.store_sizes();
1684
1685        // Get file count breakdown by language (branch-aware if possible)
1686        let mut files_by_language = std::collections::HashMap::new();
1687        if let Some(ref branch) = current_branch {
1688            // Query files for current branch only
1689            let mut stmt = conn.prepare(
1690                "SELECT f.language, COUNT(DISTINCT f.id)
1691                 FROM files f
1692                 JOIN file_branches fb ON f.id = fb.file_id
1693                 JOIN branches b ON fb.branch_id = b.id
1694                 WHERE b.name = ?
1695                 GROUP BY f.language",
1696            )?;
1697            let lang_counts = stmt.query_map([branch], |row| {
1698                let language: String = row.get(0)?;
1699                let count: i64 = row.get(1)?;
1700                Ok((language, count as usize))
1701            })?;
1702
1703            for result in lang_counts {
1704                let (language, count) = result?;
1705                files_by_language.insert(language, count);
1706            }
1707        } else {
1708            // Fallback: query all files
1709            let mut stmt =
1710                conn.prepare("SELECT language, COUNT(*) FROM files GROUP BY language")?;
1711            let lang_counts = stmt.query_map([], |row| {
1712                let language: String = row.get(0)?;
1713                let count: i64 = row.get(1)?;
1714                Ok((language, count as usize))
1715            })?;
1716
1717            for result in lang_counts {
1718                let (language, count) = result?;
1719                files_by_language.insert(language, count);
1720            }
1721        }
1722
1723        // Get line count breakdown by language (branch-aware if possible)
1724        let mut lines_by_language = std::collections::HashMap::new();
1725        if let Some(ref branch) = current_branch {
1726            // Query lines for current branch only
1727            let mut stmt = conn.prepare(
1728                "SELECT f.language, SUM(f.line_count)
1729                 FROM files f
1730                 JOIN file_branches fb ON f.id = fb.file_id
1731                 JOIN branches b ON fb.branch_id = b.id
1732                 WHERE b.name = ?
1733                 GROUP BY f.language",
1734            )?;
1735            let line_counts = stmt.query_map([branch], |row| {
1736                let language: String = row.get(0)?;
1737                let count: i64 = row.get(1)?;
1738                Ok((language, count as usize))
1739            })?;
1740
1741            for result in line_counts {
1742                let (language, count) = result?;
1743                lines_by_language.insert(language, count);
1744            }
1745        } else {
1746            // Fallback: query all files
1747            let mut stmt =
1748                conn.prepare("SELECT language, SUM(line_count) FROM files GROUP BY language")?;
1749            let line_counts = stmt.query_map([], |row| {
1750                let language: String = row.get(0)?;
1751                let count: i64 = row.get(1)?;
1752                Ok((language, count as usize))
1753            })?;
1754
1755            for result in line_counts {
1756                let (language, count) = result?;
1757                lines_by_language.insert(language, count);
1758            }
1759        }
1760
1761        Ok(crate::models::IndexStats {
1762            total_files,
1763            index_size_bytes,
1764            last_updated,
1765            files_by_language,
1766            lines_by_language,
1767            corpus_bytes,
1768            trigram_index_bytes,
1769            ..Default::default()
1770        })
1771    }
1772
1773    /// On-disk size of the cache, of its trigram stores, and the live corpus
1774    /// bytes (see `stats_on_branch`).
1775    pub(crate) fn store_sizes(&self) -> (u64, u64, u64) {
1776        // Calculate total cache size (all binary files)
1777        let mut index_size_bytes: u64 = 0;
1778        let mut trigram_index_bytes: u64 = 0;
1779
1780        let summary = crate::snapshot::store_summary(&self.cache_path);
1781        for file_path in [
1782            self.cache_path.join(META_DB),
1783            self.cache_path.join(CONFIG_TOML),
1784        ]
1785        .iter()
1786        .chain(summary.files())
1787        {
1788            if let Ok(metadata) = std::fs::metadata(file_path) {
1789                index_size_bytes += metadata.len();
1790            }
1791        }
1792        for file_path in &summary.trigram_files {
1793            if let Ok(metadata) = std::fs::metadata(file_path) {
1794                trigram_index_bytes += metadata.len();
1795            }
1796        }
1797
1798        // Raw corpus size: the manifest records the live text bytes. A cache
1799        // without one: content.bin stores the concatenated file bytes directly
1800        // after its 32-byte header, and `index_offset` (bytes 16..24) marks where
1801        // they end. Read just the header; never load the store.
1802        let corpus_bytes: u64 = summary.live_corpus_bytes.unwrap_or_else(|| {
1803            use std::io::Read;
1804            std::fs::File::open(&summary.content_files[0])
1805                .ok()
1806                .and_then(|mut f| {
1807                    let mut header = [0u8; 32];
1808                    f.read_exact(&mut header).ok()?;
1809                    if &header[..4] != b"RFCT" {
1810                        return None;
1811                    }
1812                    let index_offset = u64::from_le_bytes(header[16..24].try_into().ok()?);
1813                    Some(index_offset.saturating_sub(32))
1814                })
1815                .unwrap_or(0)
1816        });
1817
1818        (index_size_bytes, trigram_index_bytes, corpus_bytes)
1819    }
1820
1821    /// [`Self::stats_on_branch`] for a branch whose `file_branches` rows name every
1822    /// file (the index run just synced them): the same numbers from `files` alone,
1823    /// one scan instead of three joins.
1824    pub(crate) fn stats_synced(&self) -> Result<crate::models::IndexStats> {
1825        let conn = open_meta_db(self.cache_path.join(META_DB)).context("Failed to open meta.db")?;
1826        let mut files_by_language = std::collections::HashMap::new();
1827        let mut lines_by_language = std::collections::HashMap::new();
1828        let mut total_files = 0usize;
1829        {
1830            let mut stmt = conn.prepare(
1831                "SELECT language, COUNT(*), SUM(line_count) FROM files GROUP BY language",
1832            )?;
1833            let rows = stmt.query_map([], |row| {
1834                Ok((
1835                    row.get::<_, String>(0)?,
1836                    row.get::<_, i64>(1)? as usize,
1837                    row.get::<_, i64>(2)? as usize,
1838                ))
1839            })?;
1840            for row in rows {
1841                let (language, files, lines) = row?;
1842                total_files += files;
1843                files_by_language.insert(language.clone(), files);
1844                lines_by_language.insert(language, lines);
1845            }
1846        }
1847        let last_updated: String = conn
1848            .query_row(
1849                "SELECT updated_at FROM statistics WHERE key = 'total_files'",
1850                [],
1851                |row| {
1852                    let timestamp: i64 = row.get(0)?;
1853                    Ok(chrono::DateTime::from_timestamp(timestamp, 0)
1854                        .unwrap_or_else(chrono::Utc::now)
1855                        .to_rfc3339())
1856                },
1857            )
1858            .unwrap_or_else(|_| chrono::Utc::now().to_rfc3339());
1859        let (index_size_bytes, trigram_index_bytes, corpus_bytes) = self.store_sizes();
1860        Ok(crate::models::IndexStats {
1861            total_files,
1862            index_size_bytes,
1863            last_updated,
1864            files_by_language,
1865            lines_by_language,
1866            corpus_bytes,
1867            trigram_index_bytes,
1868            ..Default::default()
1869        })
1870    }
1871
1872    // ===== Branch-aware indexing methods =====
1873
1874    /// Get or create a branch ID by name
1875    ///
1876    /// Returns the numeric branch ID, creating a new entry if needed.
1877    pub(crate) fn get_or_create_branch_id(
1878        &self,
1879        conn: &Connection,
1880        branch_name: &str,
1881        commit_sha: Option<&str>,
1882    ) -> Result<i64> {
1883        // Try to get existing branch
1884        let existing_id: Option<i64> = conn
1885            .query_row(
1886                "SELECT id FROM branches WHERE name = ?",
1887                [branch_name],
1888                |row| row.get(0),
1889            )
1890            .optional()?;
1891
1892        if let Some(id) = existing_id {
1893            return Ok(id);
1894        }
1895
1896        // Create new branch entry
1897        let now = chrono::Utc::now().timestamp();
1898        conn.execute(
1899            "INSERT INTO branches (name, commit_sha, last_indexed, file_count, is_dirty)
1900             VALUES (?, ?, ?, 0, 0)",
1901            [
1902                branch_name,
1903                commit_sha.unwrap_or("unknown"),
1904                &now.to_string(),
1905            ],
1906        )?;
1907
1908        // Get the ID we just created
1909        let id: i64 = conn.last_insert_rowid();
1910        Ok(id)
1911    }
1912
1913    /// Record a file's hash for a specific branch
1914    pub fn record_branch_file(
1915        &self,
1916        path: &str,
1917        branch: &str,
1918        hash: &str,
1919        commit_sha: Option<&str>,
1920    ) -> Result<()> {
1921        let db_path = self.cache_path.join(META_DB);
1922        let conn =
1923            open_meta_db(&db_path).context("Failed to open meta.db for branch file recording")?;
1924
1925        // Lookup file_id from path
1926        let file_id: i64 = conn
1927            .query_row("SELECT id FROM files WHERE path = ?", [path], |row| {
1928                row.get(0)
1929            })
1930            .context(format!("File not found in index: {}", path))?;
1931
1932        // Get or create branch_id
1933        let branch_id = self.get_or_create_branch_id(&conn, branch, commit_sha)?;
1934
1935        let now = chrono::Utc::now().timestamp();
1936
1937        // Insert using proper INTEGER types (not strings!)
1938        conn.execute(
1939            "INSERT OR REPLACE INTO file_branches (file_id, branch_id, hash, last_indexed)
1940             VALUES (?, ?, ?, ?)",
1941            rusqlite::params![file_id, branch_id, hash, now],
1942        )?;
1943
1944        Ok(())
1945    }
1946
1947    /// Batch record multiple files for a specific branch in a single transaction
1948    ///
1949    /// IMPORTANT: Files must already exist in the `files` table before calling this method.
1950    /// For atomic insertion of both files and branch hashes, use `batch_update_files_and_branch()` instead.
1951    pub fn batch_record_branch_files(
1952        &self,
1953        files: &[(String, String)], // (path, hash)
1954        branch: &str,
1955        commit_sha: Option<&str>,
1956    ) -> Result<()> {
1957        log::info!(
1958            "batch_record_branch_files: Processing {} files for branch '{}'",
1959            files.len(),
1960            branch
1961        );
1962
1963        let db_path = self.cache_path.join(META_DB);
1964        let mut conn =
1965            open_meta_db(&db_path).context("Failed to open meta.db for batch branch recording")?;
1966
1967        let now = chrono::Utc::now().timestamp();
1968
1969        // Use a transaction for batch inserts
1970        let tx = conn.transaction()?;
1971
1972        // Get or create branch_id (use transaction connection)
1973        let branch_id = self.get_or_create_branch_id(&tx, branch, commit_sha)?;
1974        log::debug!("Got branch_id={} for branch '{}'", branch_id, branch);
1975
1976        let mut inserted = 0;
1977        for (path, hash) in files {
1978            // Lookup file_id from path
1979            log::trace!("Looking up file_id for path: {}", path);
1980            let file_id: i64 = tx
1981                .query_row(
1982                    "SELECT id FROM files WHERE path = ?",
1983                    [path.as_str()],
1984                    |row| row.get(0),
1985                )
1986                .context(format!("File not found in index: {}", path))?;
1987            log::trace!("Found file_id={} for path: {}", file_id, path);
1988
1989            // Insert using proper INTEGER types (not strings!)
1990            tx.execute(
1991                "INSERT OR REPLACE INTO file_branches (file_id, branch_id, hash, last_indexed)
1992                 VALUES (?, ?, ?, ?)",
1993                rusqlite::params![file_id, branch_id, hash.as_str(), now],
1994            )?;
1995            inserted += 1;
1996        }
1997
1998        log::info!("Inserted {} file_branches entries", inserted);
1999        tx.commit()?;
2000        log::info!("Transaction committed successfully");
2001        Ok(())
2002    }
2003
2004    /// Get all files indexed for a specific branch
2005    ///
2006    /// Returns a HashMap of path → hash for all files in the branch.
2007    pub fn get_branch_files(&self, branch: &str) -> Result<HashMap<String, String>> {
2008        let db_path = self.cache_path.join(META_DB);
2009
2010        if !db_path.exists() {
2011            return Ok(HashMap::new());
2012        }
2013
2014        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2015
2016        let mut stmt = conn.prepare(
2017            "SELECT f.path, fb.hash
2018             FROM file_branches fb
2019             JOIN files f ON fb.file_id = f.id
2020             JOIN branches b ON fb.branch_id = b.id
2021             WHERE b.name = ?",
2022        )?;
2023        let files: HashMap<String, String> = stmt
2024            .query_map([branch], |row| Ok((row.get(0)?, row.get(1)?)))?
2025            .collect::<Result<HashMap<_, _>, _>>()?;
2026
2027        log::debug!(
2028            "Loaded {} files for branch '{}' from file_branches table",
2029            files.len(),
2030            branch
2031        );
2032        Ok(files)
2033    }
2034
2035    /// Check if a branch has any indexed files
2036    ///
2037    /// Fast existence check using LIMIT 1 for O(1) performance.
2038    pub fn branch_exists(&self, branch: &str) -> Result<bool> {
2039        let db_path = self.cache_path.join(META_DB);
2040
2041        if !db_path.exists() {
2042            return Ok(false);
2043        }
2044
2045        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2046        Ok(Self::branch_exists_on(&conn, branch))
2047    }
2048
2049    fn branch_exists_on(conn: &Connection, branch: &str) -> bool {
2050        let count: i64 = conn
2051            .query_row(
2052                "SELECT COUNT(*)
2053                 FROM file_branches fb
2054                 JOIN branches b ON fb.branch_id = b.id
2055                 WHERE b.name = ?
2056                 LIMIT 1",
2057                [branch],
2058                |row| row.get(0),
2059            )
2060            .unwrap_or(0);
2061        count > 0
2062    }
2063
2064    /// Get branch metadata (commit, last_indexed, file_count, dirty status)
2065    pub fn get_branch_info(&self, branch: &str) -> Result<BranchInfo> {
2066        let db_path = self.cache_path.join(META_DB);
2067
2068        if !db_path.exists() {
2069            anyhow::bail!("Database not initialized");
2070        }
2071
2072        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2073        Self::get_branch_info_on(&conn, branch)
2074    }
2075
2076    /// The most recently written branch row, whatever its name.
2077    pub(crate) fn latest_branch_info_on(conn: &Connection) -> Result<BranchInfo> {
2078        let info = conn.query_row(
2079            "SELECT name, commit_sha, last_indexed, file_count, is_dirty FROM branches
2080             ORDER BY last_indexed DESC LIMIT 1",
2081            [],
2082            |row| {
2083                Ok(BranchInfo {
2084                    branch: row.get(0)?,
2085                    commit_sha: row.get(1)?,
2086                    last_indexed: row.get(2)?,
2087                    file_count: row.get(3)?,
2088                    is_dirty: row.get::<_, i64>(4)? != 0,
2089                })
2090            },
2091        )?;
2092        Ok(info)
2093    }
2094
2095    fn get_branch_info_on(conn: &Connection, branch: &str) -> Result<BranchInfo> {
2096        let info = conn.query_row(
2097            "SELECT commit_sha, last_indexed, file_count, is_dirty FROM branches WHERE name = ?",
2098            [branch],
2099            |row| {
2100                Ok(BranchInfo {
2101                    branch: branch.to_string(),
2102                    commit_sha: row.get(0)?,
2103                    last_indexed: row.get(1)?,
2104                    file_count: row.get(2)?,
2105                    is_dirty: row.get::<_, i64>(3)? != 0,
2106                })
2107            },
2108        )?;
2109
2110        Ok(info)
2111    }
2112
2113    /// Update branch metadata after indexing
2114    ///
2115    /// Uses UPDATE instead of INSERT OR REPLACE to preserve branch_id and prevent
2116    /// CASCADE DELETE on file_branches table.
2117    pub fn update_branch_metadata(
2118        &self,
2119        branch: &str,
2120        commit_sha: Option<&str>,
2121        file_count: usize,
2122        is_dirty: bool,
2123    ) -> Result<()> {
2124        let db_path = self.cache_path.join(META_DB);
2125        let conn =
2126            open_meta_db(&db_path).context("Failed to open meta.db for branch metadata update")?;
2127        Self::update_branch_metadata_on(&conn, branch, commit_sha, file_count, is_dirty)
2128    }
2129
2130    /// [`Self::update_branch_metadata`] on an open connection.
2131    pub(crate) fn update_branch_metadata_on(
2132        conn: &Connection,
2133        branch: &str,
2134        commit_sha: Option<&str>,
2135        file_count: usize,
2136        is_dirty: bool,
2137    ) -> Result<()> {
2138        let now = chrono::Utc::now().timestamp();
2139        let is_dirty_int = if is_dirty { 1 } else { 0 };
2140
2141        // Try UPDATE first to preserve branch_id (prevents CASCADE DELETE)
2142        let rows_updated = conn.execute(
2143            "UPDATE branches
2144             SET commit_sha = ?, last_indexed = ?, file_count = ?, is_dirty = ?
2145             WHERE name = ?",
2146            rusqlite::params![
2147                commit_sha.unwrap_or("unknown"),
2148                now,
2149                file_count,
2150                is_dirty_int,
2151                branch
2152            ],
2153        )?;
2154
2155        // If no rows updated (branch doesn't exist yet), INSERT new one
2156        if rows_updated == 0 {
2157            conn.execute(
2158                "INSERT INTO branches (name, commit_sha, last_indexed, file_count, is_dirty)
2159                 VALUES (?, ?, ?, ?, ?)",
2160                rusqlite::params![
2161                    branch,
2162                    commit_sha.unwrap_or("unknown"),
2163                    now,
2164                    file_count,
2165                    is_dirty_int
2166                ],
2167            )?;
2168        }
2169
2170        log::debug!(
2171            "Updated branch metadata for '{}': commit={}, files={}, dirty={}",
2172            branch,
2173            commit_sha.unwrap_or("unknown"),
2174            file_count,
2175            is_dirty
2176        );
2177        Ok(())
2178    }
2179
2180    /// Find a file with a specific hash (for symbol reuse optimization)
2181    ///
2182    /// Returns the path and branch where this hash was first seen,
2183    /// enabling reuse of parsed symbols across branches.
2184    pub fn find_file_with_hash(&self, hash: &str) -> Result<Option<(String, String)>> {
2185        let db_path = self.cache_path.join(META_DB);
2186
2187        if !db_path.exists() {
2188            return Ok(None);
2189        }
2190
2191        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2192
2193        let result = conn
2194            .query_row(
2195                "SELECT f.path, b.name
2196                 FROM file_branches fb
2197                 JOIN files f ON fb.file_id = f.id
2198                 JOIN branches b ON fb.branch_id = b.id
2199                 WHERE fb.hash = ?
2200                 LIMIT 1",
2201                [hash],
2202                |row| Ok((row.get(0)?, row.get(1)?)),
2203            )
2204            .optional()?;
2205
2206        Ok(result)
2207    }
2208
2209    /// Get file ID by path
2210    ///
2211    /// Returns the integer ID for a file path, or None if not found.
2212    pub fn get_file_id(&self, path: &str) -> Result<Option<i64>> {
2213        let db_path = self.cache_path.join(META_DB);
2214
2215        if !db_path.exists() {
2216            return Ok(None);
2217        }
2218
2219        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2220
2221        let result = conn
2222            .query_row("SELECT id FROM files WHERE path = ?", [path], |row| {
2223                row.get(0)
2224            })
2225            .optional()?;
2226
2227        Ok(result)
2228    }
2229
2230    /// Batch get file IDs for multiple paths
2231    ///
2232    /// Returns a HashMap of path → file_id for all found paths.
2233    /// Paths not in the database are omitted from the result.
2234    ///
2235    /// Automatically chunks large batches to avoid SQLite parameter limits (999 max).
2236    pub fn batch_get_file_ids(&self, paths: &[String]) -> Result<HashMap<String, i64>> {
2237        let db_path = self.cache_path.join(META_DB);
2238
2239        if !db_path.exists() {
2240            return Ok(HashMap::new());
2241        }
2242
2243        let conn = open_meta_db(&db_path).context("Failed to open meta.db")?;
2244
2245        // SQLite has a limit of 999 parameters by default
2246        // Chunk requests to stay well under that limit
2247        const BATCH_SIZE: usize = 900;
2248
2249        let mut results = HashMap::new();
2250
2251        for chunk in paths.chunks(BATCH_SIZE) {
2252            // Build IN clause for this chunk
2253            let placeholders = chunk.iter().map(|_| "?").collect::<Vec<_>>().join(", ");
2254
2255            let query = format!(
2256                "SELECT path, id FROM files WHERE path IN ({})",
2257                placeholders
2258            );
2259
2260            let params: Vec<&str> = chunk.iter().map(|s| s.as_str()).collect();
2261            let mut stmt = conn.prepare(&query)?;
2262
2263            let chunk_results = stmt
2264                .query_map(rusqlite::params_from_iter(params), |row| {
2265                    Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
2266                })?
2267                .collect::<Result<HashMap<_, _>, _>>()?;
2268
2269            results.extend(chunk_results);
2270        }
2271
2272        log::debug!(
2273            "Batch loaded {} file IDs (out of {} requested, {} chunks)",
2274            results.len(),
2275            paths.len(),
2276            paths.len().div_ceil(BATCH_SIZE)
2277        );
2278        Ok(results)
2279    }
2280
2281    // ===== Cache compaction methods =====
2282
2283    /// Check if cache compaction should run
2284    ///
2285    /// Returns true if 24+ hours have passed since last compaction (or never compacted).
2286    /// Compaction threshold: 86400 seconds (24 hours)
2287    pub fn should_compact(&self) -> Result<bool> {
2288        let db_path = self.cache_path.join(META_DB);
2289
2290        if !db_path.exists() {
2291            // No database means no compaction needed
2292            return Ok(false);
2293        }
2294
2295        let conn = open_meta_db(&db_path).context("Failed to open meta.db for compaction check")?;
2296
2297        // Get last_compaction timestamp (defaults to "0" if not found)
2298        let last_compaction: i64 = conn
2299            .query_row(
2300                "SELECT value FROM statistics WHERE key = 'last_compaction'",
2301                [],
2302                |row| {
2303                    let value: String = row.get(0)?;
2304                    Ok(value.parse::<i64>().unwrap_or(0))
2305                },
2306            )
2307            .unwrap_or(0);
2308
2309        // Get current timestamp
2310        let now = chrono::Utc::now().timestamp();
2311
2312        // Compaction threshold: 24 hours (86400 seconds)
2313        const COMPACTION_THRESHOLD_SECS: i64 = 86400;
2314
2315        let elapsed_secs = now - last_compaction;
2316        let should_run = elapsed_secs >= COMPACTION_THRESHOLD_SECS;
2317
2318        log::debug!(
2319            "Compaction check: last={}, now={}, elapsed={}s, should_compact={}",
2320            last_compaction,
2321            now,
2322            elapsed_secs,
2323            should_run
2324        );
2325
2326        Ok(should_run)
2327    }
2328
2329    /// Update last_compaction timestamp in statistics table
2330    ///
2331    /// Called after successful compaction to record when it ran.
2332    pub fn update_compaction_timestamp(&self) -> Result<()> {
2333        let db_path = self.cache_path.join(META_DB);
2334        let conn = open_meta_db(&db_path)
2335            .context("Failed to open meta.db for compaction timestamp update")?;
2336
2337        let now = chrono::Utc::now().timestamp();
2338
2339        conn.execute(
2340            "INSERT OR REPLACE INTO statistics (key, value, updated_at) VALUES (?, ?, ?)",
2341            ["last_compaction", &now.to_string(), &now.to_string()],
2342        )?;
2343
2344        log::debug!("Updated last_compaction timestamp to: {}", now);
2345        Ok(())
2346    }
2347
2348    /// Compact the cache by removing deleted files and reclaiming disk space
2349    ///
2350    /// This operation:
2351    /// 1. Identifies files in the database that no longer exist on disk
2352    /// 2. Deletes those files from all database tables (CASCADE handles related data)
2353    /// 3. Runs VACUUM to reclaim disk space from deleted rows
2354    /// 4. Updates the last_compaction timestamp
2355    ///
2356    /// Returns a CompactionReport with statistics about the operation.
2357    /// Safe to run concurrently with queries (uses SQLite transactions).
2358    pub fn compact(&self) -> Result<crate::models::CompactionReport> {
2359        let start_time = std::time::Instant::now();
2360        log::info!("Starting cache compaction...");
2361
2362        // Get initial cache size
2363        let size_before = self.calculate_cache_size()?;
2364
2365        // Deleted files are NOT removed here. An index run removes a file's row
2366        // and tombstones it in the stores in one publish; removing only the row
2367        // left the stores returning the file while the freshness check (which
2368        // compares rows with the disk) could no longer see the deletion.
2369        let free_pages: i64 = {
2370            let conn = open_meta_db(self.cache_path.join(META_DB))?;
2371            conn.query_row("PRAGMA freelist_count", [], |r| r.get(0))
2372                .unwrap_or(0)
2373        };
2374        if free_pages > 0 {
2375            self.vacuum_database()?;
2376            log::info!("Completed VACUUM operation ({} free pages)", free_pages);
2377        }
2378
2379        let size_after = self.calculate_cache_size()?;
2380        let space_saved = size_before.saturating_sub(size_after);
2381        self.update_compaction_timestamp()?;
2382        let duration_ms = start_time.elapsed().as_millis() as u64;
2383        log::info!(
2384            "Cache compaction completed: {} bytes saved, took {}ms",
2385            space_saved,
2386            duration_ms
2387        );
2388
2389        Ok(crate::models::CompactionReport {
2390            files_removed: 0,
2391            space_saved_bytes: space_saved,
2392            duration_ms,
2393        })
2394    }
2395
2396    /// Run VACUUM on SQLite database to reclaim disk space
2397    ///
2398    /// VACUUM rebuilds the database file, removing free pages and compacting the file.
2399    /// This can take several seconds on large databases but significantly reduces disk usage.
2400    fn vacuum_database(&self) -> Result<()> {
2401        let db_path = self.cache_path.join(META_DB);
2402        let conn = open_meta_db(&db_path).context("Failed to open meta.db for VACUUM")?;
2403
2404        // VACUUM cannot run inside a transaction
2405        // It rebuilds the entire database file
2406        conn.execute("VACUUM", [])?;
2407
2408        log::debug!("VACUUM completed successfully");
2409        Ok(())
2410    }
2411
2412    /// Calculate total cache size in bytes
2413    ///
2414    /// Sums up the size of all cache files:
2415    /// - meta.db (SQLite database)
2416    /// - trigrams.bin (inverted index)
2417    /// - content.bin (file contents)
2418    /// - config.toml (configuration)
2419    fn calculate_cache_size(&self) -> Result<u64> {
2420        let mut total_size: u64 = 0;
2421
2422        let summary = crate::snapshot::store_summary(&self.cache_path);
2423        for file_path in [
2424            self.cache_path.join(META_DB),
2425            self.cache_path.join(CONFIG_TOML),
2426        ]
2427        .iter()
2428        .chain(summary.files())
2429        {
2430            if let Ok(metadata) = std::fs::metadata(file_path) {
2431                total_size += metadata.len();
2432            }
2433        }
2434
2435        Ok(total_size)
2436    }
2437}
2438
2439/// Result of [`CacheManager::status_reads`].
2440#[derive(Debug, Clone)]
2441pub struct StatusReads {
2442    /// The stored schema hash matches this binary.
2443    pub schema_ok: bool,
2444    /// `(version, git_sha)` of the writer, read only when `schema_ok` is false.
2445    pub owner: Option<(String, Option<String>)>,
2446    /// The current branch has indexed files.
2447    pub branch_indexed: bool,
2448    /// Branch metadata, when the branch is indexed.
2449    pub branch_info: Option<BranchInfo>,
2450    /// Paths `git status` listed when the index was written. They must be
2451    /// re-checked by content even when git now reports them clean.
2452    pub dirty_at_index: Vec<String>,
2453    /// The rule-file record of the last index run (`indexer::RULE_FILES_KEY`),
2454    /// when the schema matches.
2455    pub rule_files: Option<String>,
2456}
2457
2458/// One `files` row as the indexer writes it.
2459#[derive(Debug, Clone)]
2460pub struct FileRow {
2461    /// Workspace-relative path with forward slashes.
2462    pub path: String,
2463    /// blake3 of the bytes written to content.bin.
2464    pub hash: String,
2465    /// `format!("{:?}", Language)`.
2466    pub language: String,
2467    pub line_count: usize,
2468    pub size: u64,
2469    /// See [`mtime_ns`]; `0` when unknown, which forces a hash on the next check.
2470    pub mtime_ns: i64,
2471    /// `git status` listed this path when it was indexed.
2472    pub dirty: bool,
2473    /// Position in walk order (see [`WALK_SEQ_GAP`]). Every output that used to
2474    /// list files by `files.id` sorts by this instead: a full build numbers files
2475    /// in walk order, and ids stay stable across updates.
2476    pub walk_seq: i64,
2477}
2478
2479/// Spacing of `files.walk_seq` in a full build (`position * WALK_SEQ_GAP`), so a
2480/// file added later can take a value between its neighbours without renumbering.
2481pub const WALK_SEQ_GAP: i64 = 1 << 20;
2482
2483/// What freshness compares a file on disk against.
2484#[derive(Debug, Clone, PartialEq, Eq)]
2485pub struct FileFingerprint {
2486    pub size: u64,
2487    pub mtime_ns: i64,
2488    pub hash: String,
2489}
2490
2491impl FileFingerprint {
2492    /// Whether `md` describes a file that has not been touched since indexing.
2493    ///
2494    /// A mismatch is not proof of change (a `touch`, an edit reverted byte for
2495    /// byte); the caller then hashes. `mtime_ns == 0` means "unknown", never equal.
2496    pub fn stat_matches(&self, md: &std::fs::Metadata) -> bool {
2497        self.mtime_ns != 0 && self.size == md.len() && self.mtime_ns == mtime_ns(md)
2498    }
2499}
2500
2501/// Modification time as nanoseconds since the Unix epoch, `0` when unavailable.
2502/// The size and mtime a walk records for a file: all that change detection and a
2503/// stored fingerprint need (24 bytes, where a `Metadata` is ~150; a walk keeps one
2504/// per file).
2505#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2506pub struct FileStat {
2507    len: u64,
2508    modified: Option<std::time::SystemTime>,
2509}
2510
2511impl FileStat {
2512    pub fn of(md: &std::fs::Metadata) -> Self {
2513        Self {
2514            len: md.len(),
2515            modified: md.modified().ok(),
2516        }
2517    }
2518
2519    pub fn size(&self) -> u64 {
2520        self.len
2521    }
2522
2523    /// See [`mtime_ns`].
2524    pub fn mtime_ns(&self) -> i64 {
2525        self.modified
2526            .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
2527            .map(|d| d.as_nanos().min(i64::MAX as u128) as i64)
2528            .unwrap_or(0)
2529    }
2530
2531    /// See [`recorded_mtime_ns`].
2532    pub fn recorded_mtime_ns(&self, run_start: std::time::SystemTime) -> i64 {
2533        match self.modified {
2534            Some(t) if t < run_start => self.mtime_ns(),
2535            _ => 0,
2536        }
2537    }
2538}
2539
2540pub fn mtime_ns(md: &std::fs::Metadata) -> i64 {
2541    md.modified()
2542        .ok()
2543        .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
2544        .map(|d| d.as_nanos().min(i64::MAX as u128) as i64)
2545        .unwrap_or(0)
2546}
2547
2548/// The mtime to record for a file read during an index run that began at `run_start`.
2549///
2550/// A write landing in the same clock tick as the read could leave the index with the
2551/// old bytes and the new mtime (git's "racy" case). A file modified at or after the
2552/// run started records `0`, so the next status check hashes it instead of trusting
2553/// the stat.
2554pub fn recorded_mtime_ns(md: &std::fs::Metadata, run_start: std::time::SystemTime) -> i64 {
2555    match md.modified() {
2556        Ok(t) if t < run_start => mtime_ns(md),
2557        _ => 0,
2558    }
2559}
2560
2561/// Branch metadata information
2562#[derive(Debug, Clone)]
2563pub struct BranchInfo {
2564    pub branch: String,
2565    pub commit_sha: String,
2566    pub last_indexed: i64,
2567    pub file_count: usize,
2568    pub is_dirty: bool,
2569}
2570
2571#[cfg(test)]
2572mod tests {
2573    use super::*;
2574    use tempfile::TempDir;
2575
2576    #[test]
2577    fn test_cache_init() {
2578        let temp = TempDir::new().unwrap();
2579        let cache = CacheManager::new(temp.path());
2580
2581        assert!(!cache.exists());
2582        cache.init().unwrap();
2583        assert!(cache.exists());
2584        assert!(cache.path().exists());
2585
2586        // Verify all expected files were created
2587        assert!(cache.path().join(META_DB).exists());
2588        assert!(cache.path().join(CONFIG_TOML).exists());
2589    }
2590
2591    #[test]
2592    fn test_cache_init_idempotent() {
2593        let temp = TempDir::new().unwrap();
2594        let cache = CacheManager::new(temp.path());
2595
2596        // Initialize twice - should not error
2597        cache.init().unwrap();
2598        cache.init().unwrap();
2599
2600        assert!(cache.exists());
2601    }
2602
2603    #[test]
2604    fn test_cache_clear() {
2605        let temp = TempDir::new().unwrap();
2606        let cache = CacheManager::new(temp.path());
2607
2608        cache.init().unwrap();
2609        assert!(cache.exists());
2610
2611        cache.clear().unwrap();
2612        assert!(!cache.exists());
2613    }
2614
2615    #[test]
2616    fn test_cache_clear_nonexistent() {
2617        let temp = TempDir::new().unwrap();
2618        let cache = CacheManager::new(temp.path());
2619
2620        // Clearing non-existent cache should not error
2621        assert!(!cache.exists());
2622        cache.clear().unwrap();
2623        assert!(!cache.exists());
2624    }
2625
2626    #[test]
2627    fn test_load_all_hashes_empty() {
2628        let temp = TempDir::new().unwrap();
2629        let cache = CacheManager::new(temp.path());
2630
2631        cache.init().unwrap();
2632        let hashes = cache.load_all_hashes().unwrap();
2633        assert_eq!(hashes.len(), 0);
2634    }
2635
2636    #[test]
2637    fn test_load_all_hashes_before_init() {
2638        let temp = TempDir::new().unwrap();
2639        let cache = CacheManager::new(temp.path());
2640
2641        // Loading hashes before init should return empty map
2642        let hashes = cache.load_all_hashes().unwrap();
2643        assert_eq!(hashes.len(), 0);
2644    }
2645
2646    #[test]
2647    fn test_load_hashes_for_branch_empty() {
2648        let temp = TempDir::new().unwrap();
2649        let cache = CacheManager::new(temp.path());
2650
2651        cache.init().unwrap();
2652        let hashes = cache.load_hashes_for_branch("main").unwrap();
2653        assert_eq!(hashes.len(), 0);
2654    }
2655
2656    #[test]
2657    fn test_update_file() {
2658        let temp = TempDir::new().unwrap();
2659        let cache = CacheManager::new(temp.path());
2660
2661        cache.init().unwrap();
2662        cache.update_file("src/main.rs", "rust", 100).unwrap();
2663
2664        // Verify file was stored (check via list_files)
2665        let files = cache.list_files().unwrap();
2666        assert_eq!(files.len(), 1);
2667        assert_eq!(files[0].path, "src/main.rs");
2668        assert_eq!(files[0].language, "rust");
2669    }
2670
2671    #[test]
2672    fn test_update_file_multiple() {
2673        let temp = TempDir::new().unwrap();
2674        let cache = CacheManager::new(temp.path());
2675
2676        cache.init().unwrap();
2677        cache.update_file("src/main.rs", "rust", 100).unwrap();
2678        cache.update_file("src/lib.rs", "rust", 200).unwrap();
2679        cache.update_file("README.md", "markdown", 50).unwrap();
2680
2681        // Verify files were stored
2682        let files = cache.list_files().unwrap();
2683        assert_eq!(files.len(), 3);
2684    }
2685
2686    #[test]
2687    fn test_update_file_replace() {
2688        let temp = TempDir::new().unwrap();
2689        let cache = CacheManager::new(temp.path());
2690
2691        cache.init().unwrap();
2692        cache.update_file("src/main.rs", "rust", 100).unwrap();
2693        cache.update_file("src/main.rs", "rust", 150).unwrap();
2694
2695        // Second update should replace the first
2696        let files = cache.list_files().unwrap();
2697        assert_eq!(files.len(), 1);
2698        assert_eq!(files[0].path, "src/main.rs");
2699    }
2700
2701    #[test]
2702    fn test_batch_update_files() {
2703        let temp = TempDir::new().unwrap();
2704        let cache = CacheManager::new(temp.path());
2705
2706        cache.init().unwrap();
2707
2708        let files = vec![
2709            ("src/main.rs".to_string(), "rust".to_string(), 100),
2710            ("src/lib.rs".to_string(), "rust".to_string(), 200),
2711            ("test.py".to_string(), "python".to_string(), 50),
2712        ];
2713
2714        cache.batch_update_files(&files).unwrap();
2715
2716        // Verify files were stored
2717        let stored_files = cache.list_files().unwrap();
2718        assert_eq!(stored_files.len(), 3);
2719    }
2720
2721    #[test]
2722    fn test_update_stats() {
2723        let temp = TempDir::new().unwrap();
2724        let cache = CacheManager::new(temp.path());
2725
2726        cache.init().unwrap();
2727        cache.update_file("src/main.rs", "rust", 100).unwrap();
2728        cache.update_file("src/lib.rs", "rust", 200).unwrap();
2729
2730        // Record files for a test branch
2731        cache
2732            .record_branch_file("src/main.rs", "_default", "hash1", None)
2733            .unwrap();
2734        cache
2735            .record_branch_file("src/lib.rs", "_default", "hash2", None)
2736            .unwrap();
2737        cache.update_stats("_default").unwrap();
2738
2739        let stats = cache.stats().unwrap();
2740        assert_eq!(stats.total_files, 2);
2741    }
2742
2743    #[test]
2744    fn test_stats_empty_cache() {
2745        let temp = TempDir::new().unwrap();
2746        let cache = CacheManager::new(temp.path());
2747
2748        cache.init().unwrap();
2749        let stats = cache.stats().unwrap();
2750
2751        assert_eq!(stats.total_files, 0);
2752        assert_eq!(stats.files_by_language.len(), 0);
2753    }
2754
2755    #[test]
2756    fn test_stats_before_init() {
2757        let temp = TempDir::new().unwrap();
2758        let cache = CacheManager::new(temp.path());
2759
2760        // Stats before init should return zeros
2761        let stats = cache.stats().unwrap();
2762        assert_eq!(stats.total_files, 0);
2763    }
2764
2765    #[test]
2766    fn test_stats_by_language() {
2767        let temp = TempDir::new().unwrap();
2768        let cache = CacheManager::new(temp.path());
2769
2770        cache.init().unwrap();
2771        cache.update_file("main.rs", "Rust", 100).unwrap();
2772        cache.update_file("lib.rs", "Rust", 200).unwrap();
2773        cache.update_file("script.py", "Python", 50).unwrap();
2774        cache.update_file("test.py", "Python", 80).unwrap();
2775
2776        // Record files for a test branch
2777        cache
2778            .record_branch_file("main.rs", "_default", "hash1", None)
2779            .unwrap();
2780        cache
2781            .record_branch_file("lib.rs", "_default", "hash2", None)
2782            .unwrap();
2783        cache
2784            .record_branch_file("script.py", "_default", "hash3", None)
2785            .unwrap();
2786        cache
2787            .record_branch_file("test.py", "_default", "hash4", None)
2788            .unwrap();
2789        cache.update_stats("_default").unwrap();
2790
2791        let stats = cache.stats().unwrap();
2792        assert_eq!(stats.files_by_language.get("Rust"), Some(&2));
2793        assert_eq!(stats.files_by_language.get("Python"), Some(&2));
2794        assert_eq!(stats.lines_by_language.get("Rust"), Some(&300)); // 100 + 200
2795        assert_eq!(stats.lines_by_language.get("Python"), Some(&130)); // 50 + 80
2796    }
2797
2798    #[test]
2799    fn test_list_files_empty() {
2800        let temp = TempDir::new().unwrap();
2801        let cache = CacheManager::new(temp.path());
2802
2803        cache.init().unwrap();
2804        let files = cache.list_files().unwrap();
2805        assert_eq!(files.len(), 0);
2806    }
2807
2808    #[test]
2809    fn test_list_files() {
2810        let temp = TempDir::new().unwrap();
2811        let cache = CacheManager::new(temp.path());
2812
2813        cache.init().unwrap();
2814        cache.update_file("src/main.rs", "rust", 100).unwrap();
2815        cache.update_file("src/lib.rs", "rust", 200).unwrap();
2816
2817        let files = cache.list_files().unwrap();
2818        assert_eq!(files.len(), 2);
2819
2820        // Files should be sorted by path
2821        assert_eq!(files[0].path, "src/lib.rs");
2822        assert_eq!(files[1].path, "src/main.rs");
2823
2824        assert_eq!(files[0].language, "rust");
2825    }
2826
2827    #[test]
2828    fn test_list_files_before_init() {
2829        let temp = TempDir::new().unwrap();
2830        let cache = CacheManager::new(temp.path());
2831
2832        // Listing files before init should return empty vec
2833        let files = cache.list_files().unwrap();
2834        assert_eq!(files.len(), 0);
2835    }
2836
2837    #[test]
2838    fn test_branch_exists() {
2839        let temp = TempDir::new().unwrap();
2840        let cache = CacheManager::new(temp.path());
2841
2842        cache.init().unwrap();
2843
2844        assert!(!cache.branch_exists("main").unwrap());
2845
2846        // Add file to index first (required for record_branch_file)
2847        cache.update_file("src/main.rs", "rust", 100).unwrap();
2848        cache
2849            .record_branch_file("src/main.rs", "main", "hash1", Some("commit123"))
2850            .unwrap();
2851
2852        assert!(cache.branch_exists("main").unwrap());
2853        assert!(!cache.branch_exists("feature-branch").unwrap());
2854    }
2855
2856    #[test]
2857    fn test_record_branch_file() {
2858        let temp = TempDir::new().unwrap();
2859        let cache = CacheManager::new(temp.path());
2860
2861        cache.init().unwrap();
2862        // Add file to index first (required for record_branch_file)
2863        cache.update_file("src/main.rs", "rust", 100).unwrap();
2864        cache
2865            .record_branch_file("src/main.rs", "main", "hash1", Some("commit123"))
2866            .unwrap();
2867
2868        let files = cache.get_branch_files("main").unwrap();
2869        assert_eq!(files.len(), 1);
2870        assert_eq!(files.get("src/main.rs"), Some(&"hash1".to_string()));
2871    }
2872
2873    #[test]
2874    fn test_get_branch_files_empty() {
2875        let temp = TempDir::new().unwrap();
2876        let cache = CacheManager::new(temp.path());
2877
2878        cache.init().unwrap();
2879        let files = cache.get_branch_files("nonexistent").unwrap();
2880        assert_eq!(files.len(), 0);
2881    }
2882
2883    #[test]
2884    fn test_batch_record_branch_files() {
2885        let temp = TempDir::new().unwrap();
2886        let cache = CacheManager::new(temp.path());
2887
2888        cache.init().unwrap();
2889
2890        // Add files to index first (required for batch_record_branch_files)
2891        let file_metadata = vec![
2892            ("src/main.rs".to_string(), "rust".to_string(), 100),
2893            ("src/lib.rs".to_string(), "rust".to_string(), 200),
2894            ("README.md".to_string(), "markdown".to_string(), 50),
2895        ];
2896        cache.batch_update_files(&file_metadata).unwrap();
2897
2898        let files = vec![
2899            ("src/main.rs".to_string(), "hash1".to_string()),
2900            ("src/lib.rs".to_string(), "hash2".to_string()),
2901            ("README.md".to_string(), "hash3".to_string()),
2902        ];
2903
2904        cache
2905            .batch_record_branch_files(&files, "main", Some("commit123"))
2906            .unwrap();
2907
2908        let branch_files = cache.get_branch_files("main").unwrap();
2909        assert_eq!(branch_files.len(), 3);
2910        assert_eq!(branch_files.get("src/main.rs"), Some(&"hash1".to_string()));
2911        assert_eq!(branch_files.get("src/lib.rs"), Some(&"hash2".to_string()));
2912        assert_eq!(branch_files.get("README.md"), Some(&"hash3".to_string()));
2913    }
2914
2915    #[test]
2916    fn test_update_branch_metadata() {
2917        let temp = TempDir::new().unwrap();
2918        let cache = CacheManager::new(temp.path());
2919
2920        cache.init().unwrap();
2921        cache
2922            .update_branch_metadata("main", Some("commit123"), 10, false)
2923            .unwrap();
2924
2925        let info = cache.get_branch_info("main").unwrap();
2926        assert_eq!(info.branch, "main");
2927        assert_eq!(info.commit_sha, "commit123");
2928        assert_eq!(info.file_count, 10);
2929        assert!(!info.is_dirty);
2930    }
2931
2932    #[test]
2933    fn test_update_branch_metadata_dirty() {
2934        let temp = TempDir::new().unwrap();
2935        let cache = CacheManager::new(temp.path());
2936
2937        cache.init().unwrap();
2938        cache
2939            .update_branch_metadata("feature", Some("commit456"), 5, true)
2940            .unwrap();
2941
2942        let info = cache.get_branch_info("feature").unwrap();
2943        assert!(info.is_dirty);
2944    }
2945
2946    #[test]
2947    fn test_find_file_with_hash() {
2948        let temp = TempDir::new().unwrap();
2949        let cache = CacheManager::new(temp.path());
2950
2951        cache.init().unwrap();
2952        // Add file to index first (required for record_branch_file)
2953        cache.update_file("src/main.rs", "rust", 100).unwrap();
2954        cache
2955            .record_branch_file("src/main.rs", "main", "unique_hash", Some("commit123"))
2956            .unwrap();
2957
2958        let result = cache.find_file_with_hash("unique_hash").unwrap();
2959        assert!(result.is_some());
2960
2961        let (path, branch) = result.unwrap();
2962        assert_eq!(path, "src/main.rs");
2963        assert_eq!(branch, "main");
2964    }
2965
2966    #[test]
2967    fn test_find_file_with_hash_not_found() {
2968        let temp = TempDir::new().unwrap();
2969        let cache = CacheManager::new(temp.path());
2970
2971        cache.init().unwrap();
2972
2973        let result = cache.find_file_with_hash("nonexistent_hash").unwrap();
2974        assert!(result.is_none());
2975    }
2976
2977    #[test]
2978    fn test_config_toml_created() {
2979        let temp = TempDir::new().unwrap();
2980        let cache = CacheManager::new(temp.path());
2981
2982        cache.init().unwrap();
2983
2984        let config_path = cache.path().join(CONFIG_TOML);
2985        let config_content = std::fs::read_to_string(&config_path).unwrap();
2986
2987        // Verify config contains expected sections
2988        assert!(config_content.contains("[index]"));
2989        assert!(config_content.contains("[performance]"));
2990        assert!(config_content.contains("max_file_size"));
2991        assert!(config_content.contains("symbol_threads"));
2992        // Keys nothing reads must not be advertised.
2993        for dead in [
2994            "[search]",
2995            "default_limit",
2996            "fuzzy_threshold",
2997            "compression_level",
2998            "[semantic]",
2999        ] {
3000            assert!(
3001                !config_content.contains(dead),
3002                "template advertises unused {dead}"
3003            );
3004        }
3005    }
3006
3007    #[test]
3008    fn test_meta_db_schema() {
3009        let temp = TempDir::new().unwrap();
3010        let cache = CacheManager::new(temp.path());
3011
3012        cache.init().unwrap();
3013
3014        let db_path = cache.path().join(META_DB);
3015        let conn = open_meta_db(&db_path).unwrap();
3016
3017        // Verify tables exist
3018        let tables: Vec<String> = conn
3019            .prepare("SELECT name FROM sqlite_master WHERE type='table'")
3020            .unwrap()
3021            .query_map([], |row| row.get(0))
3022            .unwrap()
3023            .collect::<Result<Vec<_>, _>>()
3024            .unwrap();
3025
3026        assert!(tables.contains(&"files".to_string()));
3027        assert!(tables.contains(&"statistics".to_string()));
3028        assert!(tables.contains(&"config".to_string()));
3029        assert!(tables.contains(&"file_branches".to_string()));
3030        assert!(tables.contains(&"branches".to_string()));
3031        assert!(tables.contains(&"file_dependencies".to_string()));
3032        assert!(tables.contains(&"file_exports".to_string()));
3033    }
3034
3035    #[test]
3036    fn test_concurrent_file_updates() {
3037        use std::thread;
3038
3039        let temp = TempDir::new().unwrap();
3040        let cache_path = temp.path().to_path_buf();
3041
3042        let cache = CacheManager::new(&cache_path);
3043        cache.init().unwrap();
3044
3045        // Spawn multiple threads updating different files
3046        let handles: Vec<_> = (0..10)
3047            .map(|i| {
3048                let path = cache_path.clone();
3049                thread::spawn(move || {
3050                    let cache = CacheManager::new(&path);
3051                    cache
3052                        .update_file(&format!("file_{}.rs", i), "rust", i * 10)
3053                        .unwrap();
3054                })
3055            })
3056            .collect();
3057
3058        for handle in handles {
3059            handle.join().unwrap();
3060        }
3061
3062        let cache = CacheManager::new(&cache_path);
3063        let files = cache.list_files().unwrap();
3064        assert_eq!(files.len(), 10);
3065    }
3066
3067    // ===== Corruption Detection Tests =====
3068
3069    #[test]
3070    fn test_validate_corrupted_database() {
3071        use std::io::Write;
3072
3073        let temp = TempDir::new().unwrap();
3074        let cache = CacheManager::new(temp.path());
3075
3076        cache.init().unwrap();
3077
3078        // Corrupt the database by overwriting it with invalid data
3079        let db_path = cache.path().join(META_DB);
3080        let mut file = File::create(&db_path).unwrap();
3081        file.write_all(b"CORRUPTED DATA").unwrap();
3082
3083        // Validation should fail due to database corruption
3084        let result = cache.validate();
3085        assert!(result.is_err());
3086        let err_msg = result.unwrap_err().to_string();
3087        eprintln!("Error message: {}", err_msg);
3088        assert!(err_msg.contains("corrupted") || err_msg.contains("not a database"));
3089    }
3090
3091    #[test]
3092    fn test_validate_corrupted_trigrams() {
3093        use std::io::Write;
3094
3095        let temp = TempDir::new().unwrap();
3096        let cache = CacheManager::new(temp.path());
3097
3098        cache.init().unwrap();
3099
3100        // Create trigrams.bin with invalid magic bytes
3101        let trigrams_path = cache.path().join("trigrams.bin");
3102        let mut file = File::create(&trigrams_path).unwrap();
3103        file.write_all(b"BADM").unwrap(); // Wrong magic bytes (should be "RFTG")
3104
3105        // Validation should fail due to invalid magic bytes
3106        let result = cache.validate();
3107        assert!(result.is_err());
3108        let err = result.unwrap_err().to_string();
3109        assert!(err.contains("trigrams.bin") && err.contains("corrupted"));
3110    }
3111
3112    #[test]
3113    fn test_validate_corrupted_content() {
3114        use std::io::Write;
3115
3116        let temp = TempDir::new().unwrap();
3117        let cache = CacheManager::new(temp.path());
3118
3119        cache.init().unwrap();
3120
3121        // Create content.bin with invalid magic bytes
3122        let content_path = cache.path().join("content.bin");
3123        let mut file = File::create(&content_path).unwrap();
3124        file.write_all(b"BADM").unwrap(); // Wrong magic bytes (should be "RFCT")
3125
3126        // Validation should fail due to invalid magic bytes
3127        let result = cache.validate();
3128        assert!(result.is_err());
3129        let err = result.unwrap_err().to_string();
3130        assert!(err.contains("content.bin") && err.contains("corrupted"));
3131    }
3132
3133    #[test]
3134    fn test_validate_missing_schema_table() {
3135        let temp = TempDir::new().unwrap();
3136        let cache = CacheManager::new(temp.path());
3137
3138        cache.init().unwrap();
3139
3140        // Drop a required table to simulate schema corruption
3141        let db_path = cache.path().join(META_DB);
3142        let conn = open_meta_db(&db_path).unwrap();
3143        conn.execute("DROP TABLE files", []).unwrap();
3144
3145        // Validation should fail due to missing required table
3146        let result = cache.validate();
3147        assert!(result.is_err());
3148        let err = result.unwrap_err().to_string();
3149        assert!(err.contains("files") && err.contains("missing"));
3150    }
3151
3152    #[test]
3153    fn effective_config_uses_the_saved_languages_until_a_run_clears_them() {
3154        use crate::models::Language;
3155        let temp = TempDir::new().unwrap();
3156        let cache = CacheManager::new(temp.path());
3157        cache.init().unwrap();
3158        assert!(
3159            cache
3160                .effective_index_config(&[])
3161                .unwrap()
3162                .languages
3163                .is_empty()
3164        );
3165
3166        cache.set_languages_override(&[Language::Rust]).unwrap();
3167        assert_eq!(
3168            cache.effective_index_config(&[]).unwrap().languages,
3169            vec![Language::Rust]
3170        );
3171        // An explicit list wins over the saved one.
3172        assert_eq!(
3173            cache
3174                .effective_index_config(&[Language::Go])
3175                .unwrap()
3176                .languages,
3177            vec![Language::Go]
3178        );
3179
3180        cache.set_languages_override(&[]).unwrap();
3181        assert!(
3182            cache
3183                .effective_index_config(&[])
3184                .unwrap()
3185                .languages
3186                .is_empty()
3187        );
3188    }
3189}