ferric_ai/commands/stats/

mod.rs

use crate::cli::Cli;
use crate::error::Result;
use crate::handler::CommandHandler;
use crate::helpers::{parse_single_svg, resolve_path_to_files};
use crate::parser::Tree;
use std::path::PathBuf;

// Module declarations
pub mod calculations {
    pub mod basic;
    pub mod concentration;
    pub mod tiers;
    pub mod statistics;
    pub mod percentiles;
    pub mod health;
    pub mod distribution;
    pub mod validation;
}

pub mod core {
    pub mod data_structures;
}

pub mod display {
    pub mod formatting;
}

pub mod subcommands {
    pub mod summary;
    pub mod hotspots;
    pub mod diagnosis;
    pub mod distribution;
    pub mod comprehensive;
}

use subcommands::{
    summary::SummaryHandler,
    hotspots::HotspotsHandler,
    diagnosis::DiagnosisHandler,
    distribution::DistributionHandler,
    comprehensive::ComprehensiveHandler,
};

/// Stats subcommands
#[derive(Debug, Clone, clap::Subcommand)]
pub enum StatsCommands {
    /// Show basic flamegraph inventory
    Summary {
        #[arg(long, help = "Show comparison analysis instead of individual stats")]
        comparison: bool,
        #[arg(long, help = "Output results in JSON format")]
        json: bool,
    },
    /// Identify CPU hotspots and concentration patterns
    Hotspots {
        #[arg(long, help = "Show comparison analysis instead of individual stats")]
        comparison: bool,
        #[arg(long, help = "Output results in JSON format")]
        json: bool,
    },
    /// Assess performance health and get optimization recommendations
    Diagnosis {
        #[arg(long, help = "Show comparison analysis instead of individual stats")]
        comparison: bool,
        #[arg(long, help = "Output results in JSON format")]
        json: bool,
    },
    /// Analyze statistical distribution patterns
    Distribution {
        #[arg(long, help = "Show comparison analysis instead of individual stats")]
        comparison: bool,
        #[arg(long, help = "Output results in JSON format")]
        json: bool,
    },
    /// Complete analysis (all metrics)
    Comprehensive {
        #[arg(long, help = "Show comparison analysis instead of individual stats")]
        comparison: bool,
        #[arg(long, help = "Output results in JSON format")]
        json: bool,
    },
}

/// Handler for the stats command with subcommands
pub struct StatsHandler;

impl CommandHandler for StatsHandler {
    fn execute(&self, cli: &Cli) -> Result<()> {
        // Extract subcommand from CLI
        let stats_command = if let crate::cli::Commands::Stats(ref subcommand) = &cli.command {
            subcommand
        } else {
            return Err(crate::error::FerricError::CommandError(
                "Stats command expected but not found".to_string()
            ));
        };

        // Parse trees with restriction to single files only
        let (primary_tree, comparison_tree, primary_path, comparison_path) = self.parse_trees_with_paths(cli)?;

        let primary_filename = primary_path.file_name().unwrap_or_default().to_string_lossy();
        let comparison_filename = comparison_path.as_ref()
            .and_then(|p| p.file_name())
            .map(|n| n.to_string_lossy())
            .unwrap_or_default();

        // Route to appropriate subcommand handler
        match stats_command {
            StatsCommands::Summary { comparison: _, json } => {
                let handler = SummaryHandler;
                if let Some(comp_tree) = comparison_tree {
                    handler.execute_comparison(&primary_tree, &comp_tree, &primary_filename, &comparison_filename, *json)
                } else {
                    handler.execute_single(&primary_tree, &primary_filename, *json)
                }
            },
            StatsCommands::Hotspots { comparison: _, json } => {
                let handler = HotspotsHandler;
                if let Some(comp_tree) = comparison_tree {
                    handler.execute_comparison(&primary_tree, &comp_tree, &primary_filename, &comparison_filename, *json)
                } else {
                    handler.execute_single(&primary_tree, &primary_filename, *json)
                }
            },
            StatsCommands::Diagnosis { comparison: _, json } => {
                let handler = DiagnosisHandler;
                if let Some(comp_tree) = comparison_tree {
                    handler.execute_comparison(&primary_tree, &comp_tree, &primary_filename, &comparison_filename, *json)
                } else {
                    handler.execute_single(&primary_tree, &primary_filename, *json)
                }
            },
            StatsCommands::Distribution { comparison: _, json } => {
                let handler = DistributionHandler;
                if let Some(comp_tree) = comparison_tree {
                    handler.execute_comparison(&primary_tree, &comp_tree, &primary_filename, &comparison_filename, *json)
                } else {
                    handler.execute_single(&primary_tree, &primary_filename, *json)
                }
            },
            StatsCommands::Comprehensive { comparison: _, json } => {
                let handler = ComprehensiveHandler;
                if let Some(comp_tree) = comparison_tree {
                    handler.execute_comparison(&primary_tree, &comp_tree, &primary_filename, &comparison_filename, *json)
                } else {
                    handler.execute_single(&primary_tree, &primary_filename, *json)
                }
            },
        }
    }

    // Override default parse_trees to restrict to single files only
    fn parse_trees(&self, cli: &Cli) -> Result<(Vec<Tree>, Vec<Tree>)> {
        let (primary_tree, comparison_tree) = self.parse_trees_single_file(cli)?;

        let primary_vec = vec![primary_tree];
        let comparison_vec = if let Some(tree) = comparison_tree {
            vec![tree]
        } else {
            Vec::new()
        };

        Ok((primary_vec, comparison_vec))
    }
}

impl StatsHandler {
    /// Parse trees with restriction to single files only, returning paths as well
    fn parse_trees_with_paths(&self, cli: &Cli) -> Result<(Tree, Option<Tree>, PathBuf, Option<PathBuf>)> {
        // Check primary input - resolve glob and ensure single file
        let primary_files = resolve_path_to_files(&cli.flamegraph)?;
        if primary_files.len() != 1 {
            return Err(crate::error::FerricError::CommandError(
                format!("Stats command requires exactly one flamegraph file, but found {} files. Please specify a single .svg file or a glob pattern that matches exactly one file.", primary_files.len())
            ));
        }

        let primary_path = primary_files.into_iter().next().unwrap();
        let primary_tree = parse_single_svg(&primary_path)?;

        // Handle comparison input if provided
        let (comparison_tree, comparison_path) = if let Some(ref compare_path) = cli.compare {
            let comparison_files = resolve_path_to_files(compare_path)?;
            if comparison_files.len() != 1 {
                return Err(crate::error::FerricError::CommandError(
                    format!("Stats comparison requires exactly one comparison file, but found {} files. Please specify a single .svg file.", comparison_files.len())
                ));
            }

            let comp_path = comparison_files.into_iter().next().unwrap();
            let comp_tree = parse_single_svg(&comp_path)?;
            (Some(comp_tree), Some(comp_path))
        } else {
            (None, None)
        };

        Ok((primary_tree, comparison_tree, primary_path, comparison_path))
    }

    /// Parse trees with restriction to single files only (legacy method for parse_trees override)
    fn parse_trees_single_file(&self, cli: &Cli) -> Result<(Tree, Option<Tree>)> {
        let (primary_tree, comparison_tree, _, _) = self.parse_trees_with_paths(cli)?;
        Ok((primary_tree, comparison_tree))
    }
}

// Long about text for the stats command
pub const STATS_LONG_ABOUT: &str = "Analyze flamegraph statistics and performance characteristics to provide context for threshold configuration. Generates CPU percentage distributions, function counts, recursion depth analysis, and suggested thresholds for hotspot detection. Designed to help LLMs and users configure appropriate analysis parameters based on the specific performance profile of the application. Output includes both human-readable summaries and structured JSON data for automated threshold setting.

Available subcommands:
  summary       Basic flamegraph inventory and function counts
  hotspots      CPU concentration analysis and performance tiers
  diagnosis     Health assessment and optimization recommendations
  distribution  Statistical distribution patterns and variability analysis
  comprehensive Complete analysis combining all metrics

Use --comparison flag with --compare to show comparison analysis between two flamegraphs.";