//! 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

    pub(crate) 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", "42")?;

        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.search_paths.clear(); // Remove default paths

        loader.add_search_path(temp_dir.path());

        create_test_module(&temp_dir, "test", "42")?;

        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.search_paths.clear(); // Remove default paths

        loader.add_search_path(temp_dir.path());

        create_test_module(&temp_dir, "test", "42")?;

        // 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(())

    }

}