//! Multi-file module system implementation
//! 
//! Enables `use external_file;` imports for larger Ruchy programs while preserving 
//! 100% compatibility with existing inline modules.
//!
//! # Architecture
//! 
//! - **`ModuleLoader`**: Core component handling file discovery, parsing, and caching
//! - **`ParsedModule`**: Represents a loaded module with metadata and dependencies  
//! - **Search Path Resolution**: Multiple directory support with fallback patterns
//! - **Circular Dependency Detection**: Prevents infinite loading loops
//! - **Caching**: Avoids re-parsing unchanged files for performance
//!
//! # Usage
//!
//! ```rust
//! use ruchy::backend::module_loader::ModuleLoader;
//! 
//! let mut loader = ModuleLoader::new();
//! loader.add_search_path("./src");
//! loader.add_search_path("./modules");
//! 
//! let module = loader.load_module("math")?; // Loads math.ruchy
//! ```

use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::fs;
use std::time::SystemTime;
use anyhow::{Result, bail, Context};
use crate::frontend::parser::Parser;
use crate::frontend::ast::{Expr, ExprKind};

/// Core module loading and caching system
/// 
/// Handles file discovery, parsing, dependency resolution, and caching
/// for multi-file Ruchy programs.
pub struct ModuleLoader {
    /// Cache of parsed modules to avoid re-parsing unchanged files
    cache: HashMap<String, ParsedModule>,
    /// Directories to search for module files
    search_paths: Vec<PathBuf>,
    /// Stack of currently loading modules for circular dependency detection
    loading_stack: Vec<String>,
    /// Total number of files loaded (for metrics)
    files_loaded: usize,
    /// Total cache hits (for performance monitoring)
    cache_hits: usize,
}

impl ModuleLoader {
    /// Create a new `ModuleLoader` with default search paths
    /// 
    /// Default search paths:
    /// - `.` (current directory)
    /// - `./src` (source directory)
    /// - `./modules` (modules directory)
    #[must_use]
    pub fn new() -> Self {
        Self {
            cache: HashMap::new(),
            search_paths: vec![
                PathBuf::from("."),           // Current directory
                PathBuf::from("./src"),       // Source directory  
                PathBuf::from("./modules"),   // Modules directory
            ],
            loading_stack: Vec::new(),
            files_loaded: 0,
            cache_hits: 0,
        }
    }
    
    /// Add a directory to the module search path
    /// 
    /// Modules will be searched in the order paths were added.
    /// 
    /// # Arguments
    /// 
    /// * `path` - Directory to search for modules
    pub fn add_search_path<P: AsRef<Path>>(&mut self, path: P) {
        self.search_paths.push(path.as_ref().to_path_buf());
    }
    
    /// Load a module from the file system
    /// 
    /// Supports these patterns:
    /// - `module_name.ruchy` - Direct file
    /// - `module_name/mod.ruchy` - Directory module  
    /// - `module_name.rchy` - Short extension
    /// 
    /// # Arguments
    /// 
    /// * `module_name` - Name of the module to load
    /// 
    /// # Returns
    /// 
    /// Clone of the parsed module with AST and metadata
    /// 
    /// # Errors
    /// 
    /// Returns an error if:
    /// - Module file not found in any search path
    /// - Circular dependency detected
    /// - File parsing fails
    /// - I/O errors reading the file
    pub fn load_module(&mut self, module_name: &str) -> Result<ParsedModule> {
        // Check circular dependencies first
        if self.loading_stack.contains(&module_name.to_string()) {
            let stack = self.loading_stack.join(" -> ");
            let cycle_path = format!("{stack} -> {module_name}");
            bail!("Circular dependency detected: {}", cycle_path);
        }
        
        // Check cache for already loaded modules
        if let Some(cached) = self.cache.get(module_name) {
            if self.is_cache_valid(cached)? {
                self.cache_hits += 1;
                return Ok(cached.clone());
            }
        }
        
        // Find the module file in search paths
        let file_path = self.resolve_module_path(module_name)
            .with_context(|| format!("Failed to find module '{module_name}'"))?;
        
        // Read and parse the module file  
        let content = fs::read_to_string(&file_path)
            .with_context(|| {
                let path = file_path.display();
                format!("Failed to read module file: {path}")
            })?;
        
        // Track loading for circular dependency detection
        self.loading_stack.push(module_name.to_string());
        
        // Parse the module content
        let mut parser = Parser::new(&content);
        let ast = parser.parse()
            .with_context(|| format!("Failed to parse module '{module_name}'"))?;
        
        // Extract dependencies from the parsed AST
        let dependencies = self.extract_dependencies(&ast)?;
        
        // Create parsed module metadata
        let parsed_module = ParsedModule {
            ast,
            file_path: file_path.clone(),
            dependencies: dependencies.clone(),
            last_modified: fs::metadata(&file_path)?.modified()?,
        };
        
        // Load dependencies recursively - check for circular dependencies first
        for dep in &dependencies {
            if self.loading_stack.contains(&dep.to_string()) {
                let stack = self.loading_stack.join(" -> ");
                let cycle_path = format!("{stack} -> {module_name} -> {dep}");
                bail!("Circular dependency detected: {}", cycle_path);
            }
            self.load_module(dep)
                .with_context(|| format!("Failed to load dependency '{dep}' for module '{module_name}'"))?;
        }
        
        // Remove from loading stack and cache the result
        self.loading_stack.pop();
        
        // Cache invalid entry removal and insertion
        self.cache.remove(module_name);
        self.cache.insert(module_name.to_string(), parsed_module.clone());
        self.files_loaded += 1;
        
        Ok(parsed_module)
    }
    
    /// Resolve module name to file system path
    /// 
    /// Tries these patterns in each search path:
    /// 1. `{module_name}.ruchy`
    /// 2. `{module_name}/mod.ruchy`  
    /// 3. `{module_name}.rchy`
    fn resolve_module_path(&self, module_name: &str) -> Result<PathBuf> {
        let possible_names = [
            format!("{module_name}.ruchy"),
            format!("{module_name}/mod.ruchy"),
            format!("{module_name}.rchy"),
        ];
        
        for search_path in &self.search_paths {
            for name in &possible_names {
                let candidate = search_path.join(name);
                if candidate.exists() && candidate.is_file() {
                    return Ok(candidate);
                }
            }
        }
        
        bail!(
            "Module '{}' not found. Searched in: {}\nLooked for: {}",
            module_name,
            self.search_paths.iter()
                .map(|p| p.display().to_string())
                .collect::<Vec<_>>()
                .join(", "),
            possible_names.join(", ")
        );
    }
    
    /// Check if a cached module is still valid (file not modified since parsing)
    fn is_cache_valid(&self, module: &ParsedModule) -> Result<bool> {
        let current_modified = fs::metadata(&module.file_path)?.modified()?;
        Ok(current_modified <= module.last_modified)
    }
    
    /// Extract module dependencies from AST
    /// 
    /// Traverses the AST looking for Import nodes that reference other files
    /// (not inline modules or standard library imports).
    fn extract_dependencies(&self, ast: &Expr) -> Result<Vec<String>> {
        let mut dependencies = Vec::new();
        self.collect_dependencies(ast, &mut dependencies);
        Ok(dependencies)
    }
    
    /// Recursive helper to collect dependencies from AST nodes
    fn collect_dependencies(&self, expr: &Expr, dependencies: &mut Vec<String>) {
        match &expr.kind {
            ExprKind::Import { path, .. } => {
                // Only treat simple names (no ::) as potential file imports
                if !path.contains("::") && !path.starts_with("std::") && !path.starts_with("http") {
                    dependencies.push(path.clone());
                }
            }
            ExprKind::Block(exprs) => {
                for expr in exprs {
                    self.collect_dependencies(expr, dependencies);
                }
            }
            ExprKind::Module { body, .. } => {
                self.collect_dependencies(body, dependencies);
            }
            ExprKind::Function { body, .. } => {
                self.collect_dependencies(body, dependencies);
            }
            // Add other expression types that can contain imports
            _ => {
                // For now, basic dependency extraction
                // Future: Add comprehensive AST traversal for all expression types if needed
            }
        }
    }
    
    /// Get module loading statistics for performance monitoring
    #[must_use]
    pub fn stats(&self) -> ModuleLoaderStats {
        ModuleLoaderStats {
            cached_modules: self.cache.len(),
            files_loaded: self.files_loaded,
            cache_hits: self.cache_hits,
            search_paths: self.search_paths.len(),
        }
    }
    
    /// Clear the module cache
    /// 
    /// Forces all modules to be reloaded from disk on next access.
    /// Useful for development when module files are frequently changing.
    pub fn clear_cache(&mut self) {
        self.cache.clear();
        self.files_loaded = 0;
        self.cache_hits = 0;
    }
    
    /// Check if a module is currently being loaded (for debugging)
    #[must_use]
    pub fn is_loading(&self, module_name: &str) -> bool {
        self.loading_stack.contains(&module_name.to_string())
    }
}

impl Default for ModuleLoader {
    fn default() -> Self {
        Self::new()
    }
}

/// Represents a parsed module with metadata and dependencies
#[derive(Debug, Clone)]
pub struct ParsedModule {
    /// Parsed AST of the module
    pub ast: Expr,
    /// File system path where the module was loaded from
    pub file_path: PathBuf,
    /// List of other modules this module depends on
    pub dependencies: Vec<String>,
    /// Last modification time of the source file
    pub last_modified: SystemTime,
}

impl ParsedModule {
    /// Get the module name from the file path
    #[must_use]
    pub fn name(&self) -> Option<String> {
        self.file_path
            .file_stem()
            .and_then(|stem| stem.to_str())
            .map(std::string::ToString::to_string)
    }
    
    /// Check if this module has any dependencies
    #[must_use]
    pub fn has_dependencies(&self) -> bool {
        !self.dependencies.is_empty()
    }
}

/// Statistics about module loader performance
#[derive(Debug, Clone, Copy)]
pub struct ModuleLoaderStats {
    /// Number of modules currently cached in memory
    pub cached_modules: usize,
    /// Total number of files loaded from disk
    pub files_loaded: usize,
    /// Number of cache hits (avoided file I/O)  
    pub cache_hits: usize,
    /// Number of search paths configured
    pub search_paths: usize,
}

impl ModuleLoaderStats {
    /// Calculate cache hit ratio as a percentage
    #[must_use]
    pub fn cache_hit_ratio(&self) -> f64 {
        if self.files_loaded + self.cache_hits == 0 {
            0.0
        } else {
            f64::from(self.cache_hits as u32) / f64::from((self.files_loaded + self.cache_hits) as u32) * 100.0
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;
    use std::fs;

    fn create_test_module(temp_dir: &TempDir, name: &str, content: &str) -> Result<()> {
        let file_path = temp_dir.path().join(format!("{name}.ruchy"));
        fs::write(file_path, content)?;
        Ok(())
    }

    #[test]
    fn test_module_loader_creation() {
        let loader = ModuleLoader::new();
        assert_eq!(loader.cache.len(), 0);
        assert_eq!(loader.search_paths.len(), 3);
        assert!(loader.search_paths.contains(&PathBuf::from(".")));
        assert!(loader.search_paths.contains(&PathBuf::from("./src")));
        assert!(loader.search_paths.contains(&PathBuf::from("./modules")));
    }

    #[test]
    fn test_add_search_path() {
        let mut loader = ModuleLoader::new();
        loader.add_search_path("/custom/path");
        
        assert_eq!(loader.search_paths.len(), 4);
        assert!(loader.search_paths.contains(&PathBuf::from("/custom/path")));
    }

    #[test]
    fn test_resolve_module_path_success() -> Result<()> {
        let temp_dir = TempDir::new()?;
        let mut loader = ModuleLoader::new();
        loader.add_search_path(temp_dir.path());
        
        // Create a test module file
        create_test_module(&temp_dir, "math", "pub fun add(a, b) { a + b }")?;
        
        let resolved = loader.resolve_module_path("math")?;
        assert_eq!(resolved, temp_dir.path().join("math.ruchy"));
        assert!(resolved.exists());
        
        Ok(())
    }

    #[test]
    fn test_resolve_module_path_not_found() {
        let loader = ModuleLoader::new();
        let result = loader.resolve_module_path("nonexistent");
        
        assert!(result.is_err());
        let error_msg = result.unwrap_err().to_string();
        assert!(error_msg.contains("Module 'nonexistent' not found"));
    }

    #[test]
    fn test_circular_dependency_detection() -> Result<()> {
        let temp_dir = TempDir::new()?;
        let mut loader = ModuleLoader::new();
        loader.add_search_path(temp_dir.path());
        
        // Create circular dependencies: a imports b, b imports a
        create_test_module(&temp_dir, "a", "use b;")?;
        create_test_module(&temp_dir, "b", "use a;")?;
        
        let result = loader.load_module("a");
        assert!(result.is_err());
        
        let error = result.unwrap_err();
        let error_msg = format!("{error:?}"); // Use Debug formatting to get full error chain
        
        // Check if the full error chain contains circular dependency
        let found_circular_dep = error_msg.contains("Circular dependency detected") 
                               || error_msg.contains("circular dependency");
        
        assert!(found_circular_dep, "Expected circular dependency error, got: {error_msg}");
        
        Ok(())
    }

    #[test]
    fn test_stats_tracking() -> Result<()> {
        let temp_dir = TempDir::new()?;
        let mut loader = ModuleLoader::new();
        loader.add_search_path(temp_dir.path());
        
        create_test_module(&temp_dir, "test", "pub fun test() {}")?;
        
        let initial_stats = loader.stats();
        assert_eq!(initial_stats.files_loaded, 0);
        assert_eq!(initial_stats.cache_hits, 0);
        assert_eq!(initial_stats.cached_modules, 0);
        
        // Load module first time
        loader.load_module("test")?;
        let after_load = loader.stats();
        assert_eq!(after_load.files_loaded, 1);
        assert_eq!(after_load.cached_modules, 1);
        
        // Load same module again (should hit cache)
        loader.load_module("test")?;
        let after_cache = loader.stats();
        assert_eq!(after_cache.files_loaded, 1); // Same as before
        assert_eq!(after_cache.cache_hits, 1);   // Incremented
        
        Ok(())
    }

    #[test]
    fn test_cache_hit_ratio_calculation() {
        let stats = ModuleLoaderStats {
            cached_modules: 5,
            files_loaded: 10,
            cache_hits: 20,
            search_paths: 3,
        };
        
        let ratio = stats.cache_hit_ratio();
        assert!((ratio - 66.67).abs() < 0.01); // 20/(10+20) * 100 = 66.67%
    }

    #[test]
    fn test_clear_cache() -> Result<()> {
        let temp_dir = TempDir::new()?;
        let mut loader = ModuleLoader::new();
        loader.add_search_path(temp_dir.path());
        
        create_test_module(&temp_dir, "test", "pub fun test() {}")?;
        
        // Load module to populate cache
        loader.load_module("test")?;
        assert_eq!(loader.cache.len(), 1);
        
        // Clear cache
        loader.clear_cache();
        assert_eq!(loader.cache.len(), 0);
        assert_eq!(loader.files_loaded, 0);
        assert_eq!(loader.cache_hits, 0);
        
        Ok(())
    }

    #[test]
    fn test_parsed_module_name() -> Result<()> {
        let temp_dir = TempDir::new()?;
        let path = temp_dir.path().join("math.ruchy");
        
        let module = ParsedModule {
            ast: Expr::new(crate::frontend::ast::ExprKind::Literal(crate::frontend::ast::Literal::Unit), 
                          crate::frontend::ast::Span { start: 0, end: 0 }),
            file_path: path,
            dependencies: Vec::new(),
            last_modified: SystemTime::now(),
        };
        
        assert_eq!(module.name(), Some("math".to_string()));
        assert!(!module.has_dependencies());
        
        Ok(())
    }
}