mirage-analyzer 1.6.0

use anyhow::Result;
use magellan::{
    CodeGraph, CondensationResult, CycleReport, DeadSymbol, PathEnumerationResult, SymbolInfo,
};

use super::json_types::{CondensationJson, PathEnumerationJson, SliceWrapper};

/// Bridge to Magellan's inter-procedural graph algorithms
///
/// Wraps [`CodeGraph`] to provide access to call graph algorithms including:
/// - Reachability analysis (forward/reverse)
/// - Dead code detection
/// - Cycle detection (mutual recursion)
/// - Program slicing
/// - Path enumeration
///
/// # Example
///
/// ```no_run
/// use mirage_analyzer::analysis::MagellanBridge;
///
/// // Open existing Magellan database
/// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
///
/// // Find all functions reachable from main
/// let reachable = bridge.reachable_symbols("main")?;
/// println!("Found {} reachable functions", reachable.len());
///
/// // Find dead code unreachable from entry points
/// let dead = bridge.graph().dead_symbols("main")?;
/// println!("Found {} dead symbols", dead.len());
/// # Ok::<(), anyhow::Error>(())
/// ```
pub struct MagellanBridge {
    graph: CodeGraph,
}

impl MagellanBridge {
    /// Open a Magellan database for inter-procedural analysis
    ///
    /// # Arguments
    ///
    /// * `db_path` - Path to the Magellan database file (typically `codemcp/mirage.db`)
    ///
    /// # Returns
    ///
    /// A [`MagellanBridge`] instance ready for analysis
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn open(db_path: &str) -> Result<Self> {
        let graph = CodeGraph::open(db_path)?;
        Ok(Self { graph })
    }

    /// Get a reference to the underlying Magellan [`CodeGraph`]
    ///
    /// Provides direct access to all Magellan algorithms for advanced use cases.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// // Access full CodeGraph API
    /// let cycles = bridge.graph().detect_cycles()?;
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn graph(&self) -> &CodeGraph {
        &self.graph
    }

    /// Find all symbols reachable from a given symbol (forward reachability)
    ///
    /// Computes the transitive closure of the call graph starting from the
    /// specified symbol. This is useful for:
    /// - Impact analysis (what does changing this symbol affect?)
    /// - Test coverage (what code does this test exercise?)
    /// - Dependency tracing
    ///
    /// # Arguments
    ///
    /// * `symbol_id` - Stable symbol ID (32-char BLAKE3 hash) or FQN
    ///
    /// # Returns
    ///
    /// Vector of [`SymbolInfo`] for reachable symbols, sorted deterministically
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// // Find all functions called from main (directly or indirectly)
    /// let reachable = bridge.reachable_symbols("main")?;
    /// for symbol in reachable {
    ///     println!("  - {}", symbol.fqn.as_deref().unwrap_or("?"));
    /// }
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn reachable_symbols(&self, symbol_id: &str) -> Result<Vec<SymbolInfo>> {
        self.graph.reachable_symbols(symbol_id, None)
    }

    /// Find all symbols that can reach a given symbol (reverse reachability)
    ///
    /// Computes the reverse transitive closure of the call graph. Returns all
    /// symbols from which the specified symbol can be reached (i.e., all callers).
    /// This is useful for:
    /// - Bug isolation (what code affects this symbol?)
    /// - Refactoring safety (what needs to be updated?)
    /// - Root cause analysis
    ///
    /// # Arguments
    ///
    /// * `symbol_id` - Stable symbol ID (32-char BLAKE3 hash) or FQN
    ///
    /// # Returns
    ///
    /// Vector of [`SymbolInfo`] for symbols that can reach the target
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// // Find all functions that call 'helper_function'
    /// let callers = bridge.reverse_reachable_symbols("helper_function")?;
    /// println!("{} functions call this", callers.len());
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn reverse_reachable_symbols(&self, symbol_id: &str) -> Result<Vec<SymbolInfo>> {
        self.graph.reverse_reachable_symbols(symbol_id, None)
    }

    pub fn k_hop_callees(
        &self,
        symbol_name: &str,
        depth: usize,
    ) -> Result<Vec<magellan::graph::navigator::DepthSymbol>> {
        let nav = self.graph.navigator();
        let resolved = nav.resolve(symbol_name)?;
        if resolved.is_empty() {
            anyhow::bail!("symbol '{}' not found", symbol_name);
        }
        nav.k_hop_callees(resolved[0].id, depth as u32)
    }

    pub fn k_hop_callers(
        &self,
        symbol_name: &str,
        depth: usize,
    ) -> Result<Vec<magellan::graph::navigator::DepthSymbol>> {
        let nav = self.graph.navigator();
        let resolved = nav.resolve(symbol_name)?;
        if resolved.is_empty() {
            anyhow::bail!("symbol '{}' not found", symbol_name);
        }
        nav.k_hop_callers(resolved[0].id, depth as u32)
    }

    /// Find dead code unreachable from an entry point symbol
    ///
    /// Identifies all symbols in the call graph that cannot be reached from
    /// the specified entry point (e.g., `main`, `test_main`).
    ///
    /// # Limitations
    ///
    /// - Only considers the call graph
    /// - Symbols called via reflection, function pointers, or dynamic dispatch
    ///   may be incorrectly flagged
    /// - Test functions and platform-specific code may appear as dead code
    ///
    /// # Arguments
    ///
    /// * `entry_symbol_id` - Stable symbol ID of the entry point (e.g., main function)
    ///
    /// # Returns
    ///
    /// Vector of [`DeadSymbol`] for unreachable symbols
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    /// use mirage_analyzer::cli::DeadSymbolJson;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// // Find all functions unreachable from main
    /// let dead = bridge.dead_symbols("main")?;
    /// for dead_symbol in &dead {
    ///     println!("Dead: {} ({})",
    ///         dead_symbol.symbol.fqn.as_deref().unwrap_or("?"),
    ///         dead_symbol.reason);
    /// }
    ///
    /// // Convert to JSON-serializable format
    /// let json_symbols: Vec<DeadSymbolJson> = dead.iter().map(|d| d.into()).collect();
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn dead_symbols(&self, entry_symbol_id: &str) -> Result<Vec<DeadSymbol>> {
        self.graph.dead_symbols(entry_symbol_id)
    }

    /// Detect cycles in the call graph using SCC decomposition
    ///
    /// Finds all strongly connected components (SCCs) with more than one member,
    /// which indicate cycles or mutual recursion in the call graph.
    ///
    /// # Returns
    ///
    /// [`CycleReport`] containing all detected cycles
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// let report = bridge.detect_cycles()?;
    /// println!("Found {} cycles", report.total_count);
    /// for cycle in &report.cycles {
    ///     println!("Cycle with {} members:", cycle.members.len());
    ///     for member in &cycle.members {
    ///         println!("  - {}", member.fqn.as_deref().unwrap_or("?"));
    ///     }
    /// }
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn detect_cycles(&self) -> Result<CycleReport> {
        self.graph.detect_cycles()
    }

    /// Compute a backward program slice (what affects this symbol)
    ///
    /// Returns all symbols that can affect the target symbol through the call graph.
    /// This is useful for bug isolation.
    ///
    /// # Note
    ///
    /// Current implementation uses call-graph reachability as a fallback.
    /// Full CFG-based program slicing will be available in future versions.
    ///
    /// # Arguments
    ///
    /// * `symbol_id` - Stable symbol ID or FQN to slice from
    ///
    /// # Returns
    ///
    /// [`SliceResult`] containing the slice and statistics
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// // Find what affects 'helper_function'
    /// let slice_result = bridge.backward_slice("helper_function")?;
    /// println!("{} symbols affect this function", slice_result.symbol_count);
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn backward_slice(&self, symbol_id: &str) -> Result<SliceWrapper> {
        let result = self.graph.backward_slice(symbol_id)?;
        Ok((&result).into())
    }

    /// Compute a forward program slice (what this symbol affects)
    ///
    /// Returns all symbols that the target symbol can affect through the call graph.
    /// This is useful for refactoring safety.
    ///
    /// # Note
    ///
    /// Current implementation uses call-graph reachability as a fallback.
    /// Full CFG-based program slicing will be available in future versions.
    ///
    /// # Arguments
    ///
    /// * `symbol_id` - Stable symbol ID or FQN to slice from
    ///
    /// # Returns
    ///
    /// [`SliceWrapper`] containing the slice and statistics
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// // Find what 'main_function' affects
    /// let slice_result = bridge.forward_slice("main_function")?;
    /// println!("{} symbols are affected by this function", slice_result.symbol_count);
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn forward_slice(&self, symbol_id: &str) -> Result<SliceWrapper> {
        let result = self.graph.forward_slice(symbol_id)?;
        Ok((&result).into())
    }

    /// Enumerate execution paths from a starting symbol
    ///
    /// Finds all execution paths from `start_symbol_id` to `end_symbol_id` (if provided)
    /// or all paths starting from `start_symbol_id` (if end_symbol_id is None).
    ///
    /// Path enumeration uses bounded DFS to prevent infinite traversal in cyclic graphs.
    ///
    /// # Arguments
    ///
    /// * `start_symbol_id` - Starting symbol ID or FQN
    /// * `end_symbol_id` - Optional ending symbol ID or FQN
    /// * `max_depth` - Maximum path depth (default: 100)
    /// * `max_paths` - Maximum number of paths to return (default: 1000)
    ///
    /// # Returns
    ///
    /// [`PathEnumerationResult`] with all discovered paths and statistics
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// // Find all paths from main to any leaf function
    /// let result = bridge.enumerate_paths("main", None, 50, 100)?;
    ///
    /// println!("Found {} paths", result.total_enumerated);
    /// println!("Average length: {:.2}", result.statistics.avg_length);
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn enumerate_paths(
        &self,
        start_symbol_id: &str,
        end_symbol_id: Option<&str>,
        max_depth: usize,
        max_paths: usize,
    ) -> Result<PathEnumerationResult> {
        self.graph
            .enumerate_paths(start_symbol_id, end_symbol_id, max_depth, max_paths)
    }

    /// Enumerate paths and return JSON-serializable result
    ///
    /// Convenience method that wraps [`PathEnumerationResult`] in a
    /// JSON-serializable format for CLI output.
    ///
    /// # Arguments
    ///
    /// * `start_symbol_id` - Starting symbol ID or FQN
    /// * `end_symbol_id` - Optional ending symbol ID or FQN
    /// * `max_depth` - Maximum path depth (default: 100)
    /// * `max_paths` - Maximum number of paths to return (default: 1000)
    ///
    /// # Returns
    ///
    /// JSON-serializable path enumeration result
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    /// let result = bridge.enumerate_paths_json("main", None, 50, 100)?;
    /// println!("Found {} paths", result.total_enumerated);
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn enumerate_paths_json(
        &self,
        start_symbol_id: &str,
        end_symbol_id: Option<&str>,
        max_depth: usize,
        max_paths: usize,
    ) -> Result<PathEnumerationJson> {
        let result =
            self.graph
                .enumerate_paths(start_symbol_id, end_symbol_id, max_depth, max_paths)?;
        Ok((&result).into())
    }

    /// Condense the call graph by collapsing SCCs into supernodes
    ///
    /// Creates a condensation DAG by collapsing each strongly connected component
    /// into a single "supernode". The resulting graph is always acyclic.
    ///
    /// # Use Cases
    ///
    /// - **Topological Sorting**: Condensation graph is a DAG
    /// - **Mutual Recursion Detection**: Large supernodes indicate tight coupling
    /// - **Impact Analysis**: Changing one symbol affects its entire SCC
    /// - **Inter-procedural Dominance**: Functions in root supernodes dominate downstream functions
    ///
    /// # Returns
    ///
    /// [`CondensationResult`] with the condensed DAG and symbol-to-supernode mapping
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    ///
    /// let condensed = bridge.condense_call_graph()?;
    ///
    /// println!("Condensed to {} supernodes", condensed.graph.supernodes.len());
    /// println!("Condensed graph has {} edges", condensed.graph.edges.len());
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn condense_call_graph(&self) -> Result<CondensationResult> {
        self.graph.condense_call_graph()
    }

    /// Condense call graph and return JSON-serializable result
    ///
    /// Convenience method that wraps [`CondensationResult`] in a
    /// JSON-serializable format for CLI output.
    ///
    /// # Returns
    ///
    /// [`CondensationJson`] with condensed DAG summary and supernode details
    ///
    /// # Example
    ///
    /// ```no_run
    /// use mirage_analyzer::analysis::MagellanBridge;
    ///
    /// let bridge = MagellanBridge::open("codemcp/mirage.db")?;
    /// let condensed = bridge.condense_call_graph_json()?;
    /// println!("Condensed to {} supernodes", condensed.supernode_count);
    /// println!("Largest SCC has {} functions", condensed.largest_scc_size);
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn condense_call_graph_json(&self) -> Result<CondensationJson> {
        let result = self.graph.condense_call_graph()?;
        Ok((&result).into())
    }
}