code_analyze_mcp/

analyze.rs

//! Main analysis engine for extracting code structure from files and directories.
//!
//! Implements the three analysis modes: Overview (directory structure), FileDetails (semantic extraction),
//! and SymbolFocus (call graph analysis). Handles parallel processing and cancellation.

use crate::formatter::{
    format_file_details, format_focused, format_focused_summary, format_structure,
};
use crate::graph::{CallChain, CallGraph, resolve_symbol};
use crate::lang::language_from_extension;
use crate::parser::{ElementExtractor, SemanticExtractor};
use crate::test_detection::is_test_file;
use crate::traversal::{WalkEntry, walk_directory};
use crate::types::{AnalysisMode, FileInfo, SemanticAnalysis, SymbolMatchMode};
use rayon::prelude::*;
use schemars::JsonSchema;
use serde::Serialize;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::time::Instant;
use thiserror::Error;
use tokio_util::sync::CancellationToken;
use tracing::instrument;

#[derive(Debug, Error)]
pub enum AnalyzeError {
    #[error("Traversal error: {0}")]
    Traversal(#[from] crate::traversal::TraversalError),
    #[error("Parser error: {0}")]
    Parser(#[from] crate::parser::ParserError),
    #[error("Graph error: {0}")]
    Graph(#[from] crate::graph::GraphError),
    #[error("Formatter error: {0}")]
    Formatter(#[from] crate::formatter::FormatterError),
    #[error("Analysis cancelled")]
    Cancelled,
}

/// Result of directory analysis containing both formatted output and file data.
#[derive(Debug, Serialize, JsonSchema)]
pub struct AnalysisOutput {
    #[schemars(description = "Formatted text representation of the analysis")]
    pub formatted: String,
    #[schemars(description = "List of files analyzed in the directory")]
    pub files: Vec<FileInfo>,
    /// Walk entries used internally for summary generation; not serialized.
    #[serde(skip)]
    #[schemars(skip)]
    pub entries: Vec<WalkEntry>,
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(
        description = "Opaque cursor token for the next page of results (absent when no more results)"
    )]
    pub next_cursor: Option<String>,
}

/// Result of file-level semantic analysis.
#[derive(Debug, Clone, Serialize, JsonSchema)]
pub struct FileAnalysisOutput {
    #[schemars(description = "Formatted text representation of the analysis")]
    pub formatted: String,
    #[schemars(description = "Semantic analysis data including functions, classes, and imports")]
    pub semantic: SemanticAnalysis,
    #[schemars(description = "Total line count of the analyzed file")]
    pub line_count: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(
        description = "Opaque cursor token for the next page of results (absent when no more results)"
    )]
    pub next_cursor: Option<String>,
}

/// Analyze a directory structure with progress tracking.
#[instrument(skip_all, fields(path = %root.display()))]
pub fn analyze_directory_with_progress(
    root: &Path,
    entries: Vec<WalkEntry>,
    progress: Arc<AtomicUsize>,
    ct: CancellationToken,
) -> Result<AnalysisOutput, AnalyzeError> {
    // Check if already cancelled
    if ct.is_cancelled() {
        return Err(AnalyzeError::Cancelled);
    }

    // Detect language from file extension
    let file_entries: Vec<&WalkEntry> = entries.iter().filter(|e| !e.is_dir).collect();

    let start = Instant::now();
    tracing::debug!(file_count = file_entries.len(), root = %root.display(), "analysis start");

    // Parallel analysis of files
    let analysis_results: Vec<FileInfo> = file_entries
        .par_iter()
        .filter_map(|entry| {
            // Check cancellation per file
            if ct.is_cancelled() {
                return None;
            }

            let path_str = entry.path.display().to_string();

            // Detect language from extension
            let ext = entry.path.extension().and_then(|e| e.to_str());

            // Try to read file content
            let source = match std::fs::read_to_string(&entry.path) {
                Ok(content) => content,
                Err(_) => {
                    // Binary file or unreadable - exclude from output
                    progress.fetch_add(1, Ordering::Relaxed);
                    return None;
                }
            };

            // Count lines
            let line_count = source.lines().count();

            // Detect language and extract counts
            let (language, function_count, class_count) = if let Some(ext_str) = ext {
                if let Some(lang) = language_from_extension(ext_str) {
                    let lang_str = lang.to_string();
                    match ElementExtractor::extract_with_depth(&source, &lang_str) {
                        Ok((func_count, class_count)) => (lang_str, func_count, class_count),
                        Err(_) => (lang_str, 0, 0),
                    }
                } else {
                    ("unknown".to_string(), 0, 0)
                }
            } else {
                ("unknown".to_string(), 0, 0)
            };

            progress.fetch_add(1, Ordering::Relaxed);

            let is_test = is_test_file(&entry.path);

            Some(FileInfo {
                path: path_str,
                line_count,
                function_count,
                class_count,
                language,
                is_test,
            })
        })
        .collect();

    // Check if cancelled after parallel processing
    if ct.is_cancelled() {
        return Err(AnalyzeError::Cancelled);
    }

    tracing::debug!(
        file_count = file_entries.len(),
        duration_ms = start.elapsed().as_millis() as u64,
        "analysis complete"
    );

    // Format output
    let formatted = format_structure(&entries, &analysis_results, None, Some(root));

    Ok(AnalysisOutput {
        formatted,
        files: analysis_results,
        entries,
        next_cursor: None,
    })
}

/// Analyze a directory structure and return formatted output and file data.
#[instrument(skip_all, fields(path = %root.display()))]
pub fn analyze_directory(
    root: &Path,
    max_depth: Option<u32>,
) -> Result<AnalysisOutput, AnalyzeError> {
    let entries = walk_directory(root, max_depth)?;
    let counter = Arc::new(AtomicUsize::new(0));
    let ct = CancellationToken::new();
    analyze_directory_with_progress(root, entries, counter, ct)
}

/// Determine analysis mode based on parameters and path.
pub fn determine_mode(path: &str, focus: Option<&str>) -> AnalysisMode {
    if focus.is_some() {
        return AnalysisMode::SymbolFocus;
    }

    let path_obj = Path::new(path);
    if path_obj.is_dir() {
        AnalysisMode::Overview
    } else {
        AnalysisMode::FileDetails
    }
}

/// Analyze a single file and return semantic analysis with formatted output.
#[instrument(skip_all, fields(path))]
pub fn analyze_file(
    path: &str,
    ast_recursion_limit: Option<usize>,
) -> Result<FileAnalysisOutput, AnalyzeError> {
    let start = Instant::now();
    let source = std::fs::read_to_string(path)
        .map_err(|e| AnalyzeError::Parser(crate::parser::ParserError::ParseError(e.to_string())))?;

    let line_count = source.lines().count();

    // Detect language from extension
    let ext = Path::new(path)
        .extension()
        .and_then(|e| e.to_str())
        .and_then(language_from_extension)
        .map(|l| l.to_string())
        .unwrap_or_else(|| "unknown".to_string());

    // Extract semantic information
    let mut semantic = SemanticExtractor::extract(&source, &ext, ast_recursion_limit)?;

    // Populate the file path on references now that the path is known
    for r in &mut semantic.references {
        r.location = path.to_string();
    }

    // Detect if this is a test file
    let is_test = is_test_file(Path::new(path));

    // Extract parent directory for relative path display
    let parent_dir = Path::new(path).parent();

    // Format output
    let formatted = format_file_details(path, &semantic, line_count, is_test, parent_dir);

    tracing::debug!(path = %path, language = %ext, functions = semantic.functions.len(), classes = semantic.classes.len(), imports = semantic.imports.len(), duration_ms = start.elapsed().as_millis() as u64, "file analysis complete");

    Ok(FileAnalysisOutput {
        formatted,
        semantic,
        line_count,
        next_cursor: None,
    })
}

/// Result of focused symbol analysis.
#[derive(Debug, Serialize, JsonSchema)]
pub struct FocusedAnalysisOutput {
    #[schemars(description = "Formatted text representation of the call graph analysis")]
    pub formatted: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    #[schemars(
        description = "Opaque cursor token for the next page of results (absent when no more results)"
    )]
    pub next_cursor: Option<String>,
    /// Production caller chains (partitioned from incoming chains, excluding test callers).
    /// Not serialized; used for pagination in lib.rs.
    #[serde(skip)]
    #[schemars(skip)]
    pub prod_chains: Vec<CallChain>,
    /// Test caller chains. Not serialized; used for pagination summary in lib.rs.
    #[serde(skip)]
    #[schemars(skip)]
    pub test_chains: Vec<CallChain>,
    /// Outgoing (callee) chains. Not serialized; used for pagination in lib.rs.
    #[serde(skip)]
    #[schemars(skip)]
    pub outgoing_chains: Vec<CallChain>,
    /// Number of definitions for the symbol. Not serialized; used for pagination headers.
    #[serde(skip)]
    #[schemars(skip)]
    pub def_count: usize,
}

/// Analyze a symbol's call graph across a directory with progress tracking.
#[instrument(skip_all, fields(path = %root.display(), symbol = %focus))]
#[allow(clippy::too_many_arguments)]
pub fn analyze_focused_with_progress(
    root: &Path,
    focus: &str,
    match_mode: SymbolMatchMode,
    follow_depth: u32,
    max_depth: Option<u32>,
    ast_recursion_limit: Option<usize>,
    progress: Arc<AtomicUsize>,
    ct: CancellationToken,
    use_summary: bool,
) -> Result<FocusedAnalysisOutput, AnalyzeError> {
    #[allow(clippy::too_many_arguments)]
    // Check if already cancelled
    if ct.is_cancelled() {
        return Err(AnalyzeError::Cancelled);
    }

    // Check if path is a file (hint to use directory)
    if root.is_file() {
        let formatted =
            "Single-file focus not supported. Please provide a directory path for cross-file call graph analysis.\n"
                .to_string();
        return Ok(FocusedAnalysisOutput {
            formatted,
            next_cursor: None,
            prod_chains: vec![],
            test_chains: vec![],
            outgoing_chains: vec![],
            def_count: 0,
        });
    }

    // Walk the directory
    let entries = walk_directory(root, max_depth)?;

    // Collect semantic analysis for all files in parallel
    let file_entries: Vec<&WalkEntry> = entries.iter().filter(|e| !e.is_dir).collect();

    let analysis_results: Vec<(PathBuf, SemanticAnalysis)> = file_entries
        .par_iter()
        .filter_map(|entry| {
            // Check cancellation per file
            if ct.is_cancelled() {
                return None;
            }

            let ext = entry.path.extension().and_then(|e| e.to_str());

            // Try to read file content
            let source = match std::fs::read_to_string(&entry.path) {
                Ok(content) => content,
                Err(_) => {
                    progress.fetch_add(1, Ordering::Relaxed);
                    return None;
                }
            };

            // Detect language and extract semantic information
            let language = if let Some(ext_str) = ext {
                language_from_extension(ext_str)
                    .map(|l| l.to_string())
                    .unwrap_or_else(|| "unknown".to_string())
            } else {
                "unknown".to_string()
            };

            match SemanticExtractor::extract(&source, &language, ast_recursion_limit) {
                Ok(mut semantic) => {
                    // Populate file path on references
                    for r in &mut semantic.references {
                        r.location = entry.path.display().to_string();
                    }
                    progress.fetch_add(1, Ordering::Relaxed);
                    Some((entry.path.clone(), semantic))
                }
                Err(_) => {
                    progress.fetch_add(1, Ordering::Relaxed);
                    None
                }
            }
        })
        .collect();

    // Check if cancelled after parallel processing
    if ct.is_cancelled() {
        return Err(AnalyzeError::Cancelled);
    }

    // Build call graph
    let graph = CallGraph::build_from_results(analysis_results)?;

    // Resolve symbol name using the requested match mode.
    // Exact mode: check the graph directly without building a sorted set (O(1) lookups).
    // Fuzzy modes: collect a sorted, deduplicated set of all known symbols for deterministic results.
    let resolved_focus = if match_mode == SymbolMatchMode::Exact {
        let exists = graph.definitions.contains_key(focus)
            || graph.callers.contains_key(focus)
            || graph.callees.contains_key(focus);
        if exists {
            focus.to_string()
        } else {
            return Err(crate::graph::GraphError::SymbolNotFound {
                symbol: focus.to_string(),
                hint: "Try match_mode=insensitive for a case-insensitive search.".to_string(),
            }
            .into());
        }
    } else {
        let all_known: Vec<String> = graph
            .definitions
            .keys()
            .chain(graph.callers.keys())
            .chain(graph.callees.keys())
            .cloned()
            .collect::<std::collections::BTreeSet<_>>()
            .into_iter()
            .collect();
        resolve_symbol(all_known.iter(), focus, &match_mode)?
    };

    // Compute chain data for pagination (always, regardless of summary mode)
    let def_count = graph
        .definitions
        .get(&resolved_focus)
        .map_or(0, |d| d.len());
    let incoming_chains = graph.find_incoming_chains(&resolved_focus, follow_depth)?;
    let outgoing_chains = graph.find_outgoing_chains(&resolved_focus, follow_depth)?;

    let (prod_chains, test_chains): (Vec<_>, Vec<_>) =
        incoming_chains.into_iter().partition(|chain| {
            chain
                .chain
                .first()
                .is_none_or(|(name, path, _)| !is_test_file(path) && !name.starts_with("test_"))
        });

    // Format output
    let formatted = if use_summary {
        format_focused_summary(&graph, &resolved_focus, follow_depth, Some(root))?
    } else {
        format_focused(&graph, &resolved_focus, follow_depth, Some(root))?
    };

    Ok(FocusedAnalysisOutput {
        formatted,
        next_cursor: None,
        prod_chains,
        test_chains,
        outgoing_chains,
        def_count,
    })
}

/// Analyze a symbol's call graph with use_summary parameter (internal).
#[instrument(skip_all, fields(path = %root.display(), symbol = %focus))]
#[allow(clippy::too_many_arguments)]
/// Analyze a symbol's call graph across a directory.
#[instrument(skip_all, fields(path = %root.display(), symbol = %focus))]
pub fn analyze_focused(
    root: &Path,
    focus: &str,
    follow_depth: u32,
    max_depth: Option<u32>,
    ast_recursion_limit: Option<usize>,
) -> Result<FocusedAnalysisOutput, AnalyzeError> {
    let counter = Arc::new(AtomicUsize::new(0));
    let ct = CancellationToken::new();
    analyze_focused_with_progress(
        root,
        focus,
        SymbolMatchMode::Exact,
        follow_depth,
        max_depth,
        ast_recursion_limit,
        counter,
        ct,
        false,
    )
}

/// Analyze a single file and return a minimal fixed schema (name, line count, language,
/// functions, imports) for lightweight code understanding.
#[instrument(skip_all, fields(path))]
pub fn analyze_module_file(path: &str) -> Result<crate::types::ModuleInfo, AnalyzeError> {
    let source = std::fs::read_to_string(path)
        .map_err(|e| AnalyzeError::Parser(crate::parser::ParserError::ParseError(e.to_string())))?;

    let file_path = Path::new(path);
    let name = file_path
        .file_name()
        .and_then(|s| s.to_str())
        .unwrap_or("unknown")
        .to_string();

    let line_count = source.lines().count();

    let language = file_path
        .extension()
        .and_then(|e| e.to_str())
        .and_then(language_from_extension)
        .ok_or_else(|| {
            AnalyzeError::Parser(crate::parser::ParserError::ParseError(
                "unsupported or missing file extension".to_string(),
            ))
        })?;

    let semantic = SemanticExtractor::extract(&source, language, None)?;

    let functions = semantic
        .functions
        .into_iter()
        .map(|f| crate::types::ModuleFunctionInfo {
            name: f.name,
            line: f.line,
        })
        .collect();

    let imports = semantic
        .imports
        .into_iter()
        .map(|i| crate::types::ModuleImportInfo {
            module: i.module,
            items: i.items,
        })
        .collect();

    Ok(crate::types::ModuleInfo {
        name,
        line_count,
        language: language.to_string(),
        functions,
        imports,
    })
}