maproom 0.1.0

//! Query result caching for hybrid search optimization.
//!
//! This module provides LRU caching for search results to reduce database load
//! and improve response times for repeated queries.
//!
//! # Architecture
//!
//! The cache uses a dual-layer approach:
//! 1. **Query Results Cache**: Stores complete search results by query hash
//! 2. **Embedding Cache**: Already exists in embedding service (reuse)
//!
//! # Cache Key Strategy
//!
//! Query cache keys are composed of:
//! - Query string (normalized)
//! - Search mode (Code/Text/Auto)
//! - Repo ID
//! - Worktree ID (if specified)
//! - Limit
//!
//! This ensures cache hits only occur for identical queries.
//!
//! # Performance Impact
//!
//! Cache effectiveness varies by workload:
//! - Development IDE integration: ~60-80% hit rate
//! - Batch processing: ~20-40% hit rate
//! - Ad-hoc queries: ~10-20% hit rate
//!
//! Cache hits reduce latency:
//! - Without cache: 30-50ms (database query + processing)
//! - With cache hit: <1ms (memory lookup)
//! - Net improvement: ~30-49ms per cache hit
//!
//! # Example
//!
//! ```no_run
//! use maproom::search::cache::{SearchCache, CacheKey};
//! use maproom::search::FinalSearchResults;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!     let cache = SearchCache::new(1000);
//!
//!     let key = CacheKey::new("authenticate", 1, None, 10);
//!
//!     // Check cache first
//!     if let Some(results) = cache.get(&key) {
//!         println!("Cache hit! Results: {}", results.results.len());
//!         return Ok(());
//!     }
//!
//!     // Cache miss - execute query and cache result
//!     // let results = execute_search(...).await?;
//!     // cache.put(key, results);
//!
//!     Ok(())
//! }
//! ```

use crate::search::results::FinalSearchResults;
use lru::LruCache;
use std::hash::Hash;
use std::num::NonZeroUsize;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, RwLock};
use std::time::{SystemTime, UNIX_EPOCH};
use tracing::{debug, info};

/// Default cache size (number of entries).
///
/// 1000 entries provides good balance:
/// - ~50-100MB memory usage (assuming 50-100KB per result)
/// - Covers common query patterns in development workflows
/// - Reasonable eviction rate under high query diversity
const DEFAULT_CACHE_SIZE: usize = 1000;

/// Default TTL (time-to-live) for cache entries in seconds.
///
/// 3600 seconds (1 hour) provides good balance:
/// - Fresh enough for active development
/// - Long enough to benefit repeated queries
/// - Reasonable memory overhead for timestamps
const DEFAULT_TTL_SECONDS: u64 = 3600;

/// Cache entry with TTL support.
#[derive(Debug, Clone)]
struct CacheEntry {
    /// The cached search results
    results: FinalSearchResults,
    /// Timestamp when the entry was created (Unix timestamp)
    created_at: u64,
}

impl CacheEntry {
    fn new(results: FinalSearchResults) -> Self {
        let created_at = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();

        Self {
            results,
            created_at,
        }
    }

    fn is_expired(&self, ttl_seconds: u64) -> bool {
        if ttl_seconds == 0 {
            return false; // TTL of 0 means never expire
        }
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        now - self.created_at >= ttl_seconds
    }
}

/// Thread-safe LRU cache for search results with TTL support.
///
/// Uses Arc<RwLock<>> for concurrent access with read-write semantics:
/// - Multiple readers can access cache simultaneously
/// - Writers (put operations) require exclusive lock
/// - Atomic counters track hits/misses without locking
pub struct SearchCache {
    /// LRU cache storage
    cache: Arc<RwLock<LruCache<CacheKey, CacheEntry>>>,

    /// Time-to-live for cache entries (seconds, 0 = never expire)
    ttl_seconds: u64,

    /// Cache hit counter (atomic for lock-free updates)
    hits: Arc<AtomicU64>,

    /// Cache miss counter (atomic for lock-free updates)
    misses: Arc<AtomicU64>,

    /// Cache eviction counter (atomic for lock-free updates)
    evictions: Arc<AtomicU64>,

    /// Cache expiration counter (atomic for lock-free updates)
    expirations: Arc<AtomicU64>,
}

impl Default for SearchCache {
    /// Create a new SearchCache with default capacity and TTL.
    ///
    /// Uses DEFAULT_CACHE_SIZE (1000 entries) and DEFAULT_TTL_SECONDS (3600s).
    fn default() -> Self {
        Self::new(DEFAULT_CACHE_SIZE)
    }
}

impl SearchCache {
    /// Create a new SearchCache with specified capacity and TTL.
    ///
    /// # Arguments
    ///
    /// * `capacity` - Maximum number of entries to store
    /// * `ttl_seconds` - Time-to-live in seconds (0 = never expire)
    ///
    /// # Example
    ///
    /// ```
    /// use maproom::search::cache::SearchCache;
    ///
    /// let cache = SearchCache::with_ttl(1000, 3600); // 1000 entries, 1 hour TTL
    /// ```
    pub fn with_ttl(capacity: usize, ttl_seconds: u64) -> Self {
        info!(
            "Creating search result cache (capacity: {}, ttl: {}s)",
            capacity, ttl_seconds
        );

        Self {
            cache: Arc::new(RwLock::new(LruCache::new(
                NonZeroUsize::new(capacity).expect("Cache capacity must be > 0"),
            ))),
            ttl_seconds,
            hits: Arc::new(AtomicU64::new(0)),
            misses: Arc::new(AtomicU64::new(0)),
            evictions: Arc::new(AtomicU64::new(0)),
            expirations: Arc::new(AtomicU64::new(0)),
        }
    }

    /// Create a new SearchCache with specified capacity and default TTL.
    ///
    /// # Arguments
    ///
    /// * `capacity` - Maximum number of entries to store
    ///
    /// # Example
    ///
    /// ```
    /// use maproom::search::cache::SearchCache;
    ///
    /// let cache = SearchCache::new(1000);
    /// ```
    pub fn new(capacity: usize) -> Self {
        Self::with_ttl(capacity, DEFAULT_TTL_SECONDS)
    }

    /// Get a cached result by key.
    ///
    /// Returns None if key is not in cache or if entry is expired (cache miss).
    /// Updates LRU ordering on cache hit.
    ///
    /// # Arguments
    ///
    /// * `key` - Cache key identifying the query
    ///
    /// # Example
    ///
    /// ```no_run
    /// use maproom::search::cache::{SearchCache, CacheKey};
    ///
    /// let cache = SearchCache::new(1000);
    /// let key = CacheKey::new("auth", 1, None, 10);
    ///
    /// if let Some(results) = cache.get(&key) {
    ///     println!("Found {} results in cache", results.results.len());
    /// }
    /// ```
    pub fn get(&self, key: &CacheKey) -> Option<FinalSearchResults> {
        let mut cache = self.cache.write().unwrap();

        match cache.get(key) {
            Some(entry) => {
                // Check if entry is expired
                if entry.is_expired(self.ttl_seconds) {
                    cache.pop(key);
                    self.expirations.fetch_add(1, Ordering::Relaxed);
                    self.misses.fetch_add(1, Ordering::Relaxed);
                    debug!("Cache EXPIRED: {:?}", key);
                    None
                } else {
                    self.hits.fetch_add(1, Ordering::Relaxed);
                    debug!("Cache HIT: {:?}", key);
                    Some(entry.results.clone())
                }
            }
            None => {
                self.misses.fetch_add(1, Ordering::Relaxed);
                debug!("Cache MISS: {:?}", key);
                None
            }
        }
    }

    /// Put a result into the cache.
    ///
    /// If cache is full, evicts least recently used entry.
    ///
    /// # Arguments
    ///
    /// * `key` - Cache key identifying the query
    /// * `results` - Search results to cache
    ///
    /// # Example
    ///
    /// ```ignore
    /// use maproom::search::cache::{SearchCache, CacheKey};
    /// use maproom::search::FinalSearchResults;
    ///
    /// let cache = SearchCache::new(1000);
    /// let key = CacheKey::new("auth", 1, None, 10);
    /// // let results = ...; // Create actual results
    ///
    /// // cache.put(key, results);
    /// ```
    pub fn put(&self, key: CacheKey, results: FinalSearchResults) {
        let mut cache = self.cache.write().unwrap();

        // Check if we're about to evict
        if cache.len() >= cache.cap().get() && !cache.contains(&key) {
            self.evictions.fetch_add(1, Ordering::Relaxed);
            debug!("Cache EVICTION (capacity: {})", cache.cap());
        }

        let entry = CacheEntry::new(results);
        cache.put(key, entry);
        debug!("Cache PUT: entry added");
    }

    /// Get cache statistics.
    ///
    /// Returns snapshot of current cache performance metrics.
    ///
    /// # Example
    ///
    /// ```
    /// use maproom::search::cache::SearchCache;
    ///
    /// let cache = SearchCache::new(1000);
    /// let stats = cache.stats();
    ///
    /// println!("Hit rate: {:.1}%", stats.hit_rate() * 100.0);
    /// println!("Entries: {}/{}", stats.size, stats.capacity);
    /// ```
    pub fn stats(&self) -> CacheStats {
        let cache = self.cache.read().unwrap();

        CacheStats {
            capacity: cache.cap().get(),
            size: cache.len(),
            hits: self.hits.load(Ordering::Relaxed),
            misses: self.misses.load(Ordering::Relaxed),
            evictions: self.evictions.load(Ordering::Relaxed),
            expirations: self.expirations.load(Ordering::Relaxed),
            ttl_seconds: self.ttl_seconds,
        }
    }

    /// Clear all entries from the cache.
    ///
    /// Resets cache to empty state but preserves statistics.
    pub fn clear(&self) {
        let mut cache = self.cache.write().unwrap();
        cache.clear();
        info!("Cache cleared");
    }

    /// Reset all statistics counters to zero.
    ///
    /// Does not clear cached entries.
    pub fn reset_stats(&self) {
        self.hits.store(0, Ordering::Relaxed);
        self.misses.store(0, Ordering::Relaxed);
        self.evictions.store(0, Ordering::Relaxed);
        self.expirations.store(0, Ordering::Relaxed);
        info!("Cache statistics reset");
    }

    /// Remove expired entries from the cache.
    ///
    /// Returns the number of entries removed.
    pub fn cleanup_expired(&self) -> usize {
        let mut cache = self.cache.write().unwrap();
        let mut expired_keys = Vec::new();

        // Collect expired keys
        for (key, entry) in cache.iter() {
            if entry.is_expired(self.ttl_seconds) {
                expired_keys.push(key.clone());
            }
        }

        // Remove expired entries
        let count = expired_keys.len();
        for key in expired_keys {
            cache.pop(&key);
        }

        if count > 0 {
            self.expirations.fetch_add(count as u64, Ordering::Relaxed);
            debug!("Cache cleanup: removed {} expired entries", count);
        }

        count
    }

    /// Invalidate cache entries by repository ID.
    ///
    /// Used when files are updated in a repository.
    pub fn invalidate_by_repo(&self, repo_id: i64) -> usize {
        let mut cache = self.cache.write().unwrap();
        let mut keys_to_remove = Vec::new();

        // Collect keys matching the repo_id
        for (key, _) in cache.iter() {
            if key.repo_id == repo_id {
                keys_to_remove.push(key.clone());
            }
        }

        // Remove matching entries
        let count = keys_to_remove.len();
        for key in keys_to_remove {
            cache.pop(&key);
        }

        if count > 0 {
            info!(
                "Cache invalidation: removed {} entries for repo {}",
                count, repo_id
            );
        }

        count
    }

    /// Invalidate cache entries by worktree ID.
    ///
    /// Used when files are updated in a specific worktree.
    pub fn invalidate_by_worktree(&self, worktree_id: i64) -> usize {
        let mut cache = self.cache.write().unwrap();
        let mut keys_to_remove = Vec::new();

        // Collect keys matching the worktree_id
        for (key, _) in cache.iter() {
            if key.worktree_id == Some(worktree_id) {
                keys_to_remove.push(key.clone());
            }
        }

        // Remove matching entries
        let count = keys_to_remove.len();
        for key in keys_to_remove {
            cache.pop(&key);
        }

        if count > 0 {
            info!(
                "Cache invalidation: removed {} entries for worktree {}",
                count, worktree_id
            );
        }

        count
    }
}

impl Clone for SearchCache {
    fn clone(&self) -> Self {
        Self {
            cache: Arc::clone(&self.cache),
            ttl_seconds: self.ttl_seconds,
            hits: Arc::clone(&self.hits),
            misses: Arc::clone(&self.misses),
            evictions: Arc::clone(&self.evictions),
            expirations: Arc::clone(&self.expirations),
        }
    }
}

/// Cache key for identifying unique queries.
///
/// Includes all parameters that affect search results:
/// - Query string (normalized to lowercase, trimmed)
/// - Repo ID
/// - Worktree ID (optional)
/// - Result limit
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct CacheKey {
    /// Normalized query string (lowercase, trimmed)
    pub query: String,
    /// Repository ID
    pub repo_id: i64,
    /// Optional worktree ID
    pub worktree_id: Option<i64>,
    /// Result limit (k)
    pub limit: usize,
}

impl CacheKey {
    /// Create a new cache key.
    ///
    /// Query string is normalized (trimmed, lowercased) for better cache hit rate.
    ///
    /// # Example
    ///
    /// ```
    /// use maproom::search::cache::CacheKey;
    ///
    /// let key1 = CacheKey::new("authenticate", 1, None, 10);
    /// let key2 = CacheKey::new("  AUTHENTICATE  ", 1, None, 10);
    ///
    /// assert_eq!(key1, key2); // Normalized to same key
    /// ```
    pub fn new(query: &str, repo_id: i64, worktree_id: Option<i64>, limit: usize) -> Self {
        Self {
            query: query.trim().to_lowercase(),
            repo_id,
            worktree_id,
            limit,
        }
    }

    /// Create a cache key from search options.
    ///
    /// Convenience method for creating keys from SearchOptions.
    pub fn from_options(query: &str, options: &crate::search::SearchOptions) -> Self {
        Self::new(query, options.repo_id, options.worktree_id, options.limit)
    }
}

/// Cache performance statistics.
#[derive(Debug, Clone)]
pub struct CacheStats {
    /// Maximum cache capacity
    pub capacity: usize,
    /// Current number of entries
    pub size: usize,
    /// Total cache hits
    pub hits: u64,
    /// Total cache misses
    pub misses: u64,
    /// Total evictions
    pub evictions: u64,
    /// Total expirations
    pub expirations: u64,
    /// TTL in seconds
    pub ttl_seconds: u64,
}

impl CacheStats {
    /// Calculate cache hit rate.
    ///
    /// Returns value from 0.0 to 1.0.
    /// Returns 0.0 if no queries have been made.
    pub fn hit_rate(&self) -> f64 {
        let total = self.hits + self.misses;
        if total == 0 {
            return 0.0;
        }
        self.hits as f64 / total as f64
    }

    /// Calculate cache utilization as a percentage.
    ///
    /// Returns value from 0.0 to 100.0.
    pub fn utilization_percent(&self) -> f64 {
        if self.capacity == 0 {
            return 0.0;
        }
        (self.size as f64 / self.capacity as f64) * 100.0
    }

    /// Total number of queries (hits + misses).
    pub fn total_queries(&self) -> u64 {
        self.hits + self.misses
    }

    /// Check if cache is performing well (hit rate > 50%).
    pub fn is_effective(&self) -> bool {
        self.hit_rate() > 0.5
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::search::results::{QueryProcessingDetails, SearchMetadata, SearchTiming};
    use crate::search::types::SearchMode;
    use std::collections::HashMap;

    fn create_test_metadata() -> SearchMetadata {
        let query_processing = QueryProcessingDetails::new(
            "test".to_string(),
            SearchMode::Auto,
            1,
            0,
            "test".to_string(),
            false,
        );
        let result_counts = HashMap::new();
        let timing = SearchTiming::new(1.0, 1.0, 1.0, 1.0);
        SearchMetadata::new(query_processing, result_counts, timing, 0, 0)
    }

    #[test]
    fn test_cache_key_normalization() {
        let key1 = CacheKey::new("authenticate", 1, None, 10);
        let key2 = CacheKey::new("  AUTHENTICATE  ", 1, None, 10);
        let key3 = CacheKey::new("Authenticate", 1, None, 10);

        assert_eq!(key1, key2);
        assert_eq!(key1, key3);
        assert_eq!(key2, key3);
    }

    #[test]
    fn test_cache_key_different_params() {
        let key1 = CacheKey::new("auth", 1, None, 10);
        let key2 = CacheKey::new("auth", 2, None, 10); // Different repo
        let key3 = CacheKey::new("auth", 1, Some(1), 10); // Different worktree
        let key4 = CacheKey::new("auth", 1, None, 20); // Different limit

        assert_ne!(key1, key2);
        assert_ne!(key1, key3);
        assert_ne!(key1, key4);
    }

    #[test]
    fn test_cache_basic_operations() {
        let cache = SearchCache::new(2);
        let key1 = CacheKey::new("test", 1, None, 10);
        let results = FinalSearchResults::new("test".to_string(), vec![], create_test_metadata());

        // Initially empty
        assert!(cache.get(&key1).is_none());

        // Put and get
        cache.put(key1.clone(), results.clone());
        assert!(cache.get(&key1).is_some());

        // Stats
        let stats = cache.stats();
        assert_eq!(stats.hits, 1);
        assert_eq!(stats.misses, 1);
    }

    #[test]
    fn test_cache_lru_eviction() {
        let cache = SearchCache::new(2);

        let key1 = CacheKey::new("query1", 1, None, 10);
        let key2 = CacheKey::new("query2", 1, None, 10);
        let key3 = CacheKey::new("query3", 1, None, 10);
        let results = FinalSearchResults::new("test".to_string(), vec![], create_test_metadata());

        // Fill cache
        cache.put(key1.clone(), results.clone());
        cache.put(key2.clone(), results.clone());

        // Both should be in cache
        assert!(cache.get(&key1).is_some());
        assert!(cache.get(&key2).is_some());

        // Add third entry - should evict key1 (LRU)
        cache.put(key3.clone(), results.clone());

        // key1 should be evicted, key2 and key3 should remain
        assert!(cache.get(&key1).is_none());
        assert!(cache.get(&key2).is_some());
        assert!(cache.get(&key3).is_some());

        let stats = cache.stats();
        assert_eq!(stats.evictions, 1);
    }

    #[test]
    fn test_cache_stats_calculations() {
        let stats = CacheStats {
            capacity: 100,
            size: 80,
            hits: 70,
            misses: 30,
            evictions: 10,
            expirations: 5,
            ttl_seconds: 3600,
        };

        assert_eq!(stats.hit_rate(), 0.7);
        assert_eq!(stats.utilization_percent(), 80.0);
        assert_eq!(stats.total_queries(), 100);
        assert!(stats.is_effective());
    }

    #[test]
    fn test_cache_ttl_expiration() {
        // Cache with 0 second TTL (never expire)
        let cache = SearchCache::with_ttl(100, 0);
        let key = CacheKey::new("test", 1, None, 10);
        let results = FinalSearchResults::new("test".to_string(), vec![], create_test_metadata());

        cache.put(key.clone(), results);

        // Entry should never expire with TTL=0
        assert!(cache.get(&key).is_some());
        let stats = cache.stats();
        assert_eq!(stats.expirations, 0);
    }

    #[test]
    fn test_cache_invalidation_by_repo() {
        let cache = SearchCache::new(100);

        let key1 = CacheKey::new("test1", 1, None, 10);
        let key2 = CacheKey::new("test2", 2, None, 10);
        let key3 = CacheKey::new("test3", 1, None, 10);
        let results = FinalSearchResults::new("test".to_string(), vec![], create_test_metadata());

        cache.put(key1.clone(), results.clone());
        cache.put(key2.clone(), results.clone());
        cache.put(key3.clone(), results.clone());

        // Invalidate repo 1
        let count = cache.invalidate_by_repo(1);
        assert_eq!(count, 2); // key1 and key3

        // Only key2 should remain
        assert!(cache.get(&key1).is_none());
        assert!(cache.get(&key2).is_some());
        assert!(cache.get(&key3).is_none());
    }

    #[test]
    fn test_cache_invalidation_by_worktree() {
        let cache = SearchCache::new(100);

        let key1 = CacheKey::new("test1", 1, Some(1), 10);
        let key2 = CacheKey::new("test2", 1, Some(2), 10);
        let key3 = CacheKey::new("test3", 1, None, 10);
        let results = FinalSearchResults::new("test".to_string(), vec![], create_test_metadata());

        cache.put(key1.clone(), results.clone());
        cache.put(key2.clone(), results.clone());
        cache.put(key3.clone(), results.clone());

        // Invalidate worktree 1
        let count = cache.invalidate_by_worktree(1);
        assert_eq!(count, 1); // only key1

        // key2 and key3 should remain
        assert!(cache.get(&key1).is_none());
        assert!(cache.get(&key2).is_some());
        assert!(cache.get(&key3).is_some());
    }

    #[test]
    fn test_cache_clone() {
        let cache1 = SearchCache::new(100);
        let cache2 = cache1.clone();

        let key = CacheKey::new("test", 1, None, 10);
        let results = FinalSearchResults::new("test".to_string(), vec![], create_test_metadata());

        // Put in cache1
        cache1.put(key.clone(), results);

        // Should be visible in cache2 (same underlying cache)
        assert!(cache2.get(&key).is_some());

        // Stats should be shared
        let stats1 = cache1.stats();
        let stats2 = cache2.stats();
        assert_eq!(stats1.hits, stats2.hits);
    }
}