forge/profile/

mod.rs

// #t(file: rust_deep_exit) CLI binary module, process::exit for user-facing errors.

//! Profile subcommand: workspace profiling with samply.

mod analyze;
mod build;
mod categories;
mod monitor;
mod report;
mod samply;
mod targets;

use clap::Args;
#[cfg(test)]
use googletest::{Result as GtestResult, prelude::*};
use wowlab_common::{output, prompt};
use wowlab_fs::{path::Path, temporary};

use crate::run::{FightDurationSeconds, IterationCount, RunParameters, RunParametersError};

fn fatal(args: std::fmt::Arguments<'_>) -> ! {
    output::error(&format!("{args}"));
    std::process::exit(1);
}

use targets::{ProfileTarget, TargetKind};

#[derive(Args, Debug)]
pub(crate) struct ProfileArgs {
    /// Target crate to profile (skip interactive selection).
    #[arg(long, short)]
    pub target: Option<String>,

    /// Number of iterations (engine targets).
    #[arg(long, default_value = "5000")]
    pub iterations: u32,

    /// Fight duration in seconds (engine targets).
    #[arg(long, default_value = "300")]
    pub duration: u32,

    /// Spec to profile (engine targets).
    #[arg(long)]
    pub spec: Option<String>,

    /// Output JSON instead of text.
    #[arg(long)]
    pub json: bool,

    /// Top N functions to show.
    #[arg(long, default_value = "50")]
    pub top: usize,

    /// Suppress non-essential output.
    #[arg(long, short)]
    pub quiet: bool,

    /// Run criterion benchmarks instead of samply profiling.
    #[arg(long)]
    pub bench: bool,

    /// Custom command args (for non-engine targets).
    #[arg(last = true)]
    pub args: Vec<String>,
}

#[derive(Debug, thiserror::Error)]
enum CaptureProfileError {
    #[error("failed to create profile workspace: {0}")]
    Workspace(#[from] wowlab_fs::error::Error),
    #[error("samply failed: {0}")]
    Samply(#[from] samply::RecordError),
    #[error("failed to parse profile: {0}")]
    Parse(#[from] anyhow::Error),
}

impl TryFrom<&ProfileArgs> for RunParameters {
    type Error = RunParametersError;

    fn try_from(args: &ProfileArgs) -> Result<Self, Self::Error> {
        let fight_duration = FightDurationSeconds::try_from(args.duration)?;
        let iterations = IterationCount::try_from(args.iterations)?;

        Ok(Self::new(iterations, fight_duration))
    }
}

pub(crate) fn run(profile_args: &ProfileArgs, crates_dir: &Path) {
    let all_targets = targets::discover(crates_dir);

    if all_targets.is_empty() {
        fatal(format_args!(
            "no profiling targets found in {}",
            crates_dir.display()
        ));
    }

    let target = if let Some(ref name) = profile_args.target {
        all_targets
            .iter()
            .find(|t| t.name == *name || t.bin_name == *name)
            .unwrap_or_else(|| {
                fatal(format_args!(
                    "target '{}' not found. available: {}",
                    name,
                    all_targets
                        .iter()
                        .map(|t| t.name.as_str())
                        .collect::<Vec<_>>()
                        .join(", ")
                ));
            })
            .clone()
    } else {
        interactive_select(&all_targets, crates_dir)
    };

    if !profile_args.quiet {
        output::kv("Target", &target.name);
        output::kv(
            "Kind",
            match target.kind {
                TargetKind::Binary => "binary",
                TargetKind::Bench => "benchmark",
            },
        );
        output::blank();
    }

    if profile_args.bench || target.kind == TargetKind::Bench {
        run_bench(&target, crates_dir, profile_args);
    } else {
        run_profile(&target, crates_dir, profile_args);
    }
}

fn interactive_select(targets: &[ProfileTarget], crates_dir: &Path) -> ProfileTarget {
    let labels: Vec<String> = targets.iter().map(ToString::to_string).collect();
    let idx = prompt::select("Target", &labels);
    // BOUNDS: idx returned by prompt::select which constrains to 0..targets.len()
    let mut target = targets[idx].clone();

    if target.name == "engine" {
        let specs = targets::discover_engine_specs(crates_dir);
        let spec_strs: Vec<&str> = specs.iter().map(String::as_str).collect();
        let spec_idx = prompt::select("Spec", &spec_strs);
        // BOUNDS: spec_idx returned by prompt::select which constrains to 0..specs.len()
        let spec = &specs[spec_idx];

        let iterations = prompt::text("Iterations", Some("5000"));
        let duration = prompt::text("Duration (seconds)", Some("300"));

        target.default_args = vec![
            "sim".to_string(),
            "--spec".to_string(),
            spec.clone(),
            "--iterations".to_string(),
            iterations,
            "--duration".to_string(),
            duration,
            "--threads".to_string(),
            "1".to_string(),
            "--format".to_string(),
            "json".to_string(),
        ];
    } else if target.kind == TargetKind::Binary && target.default_args.is_empty() {
        let custom = prompt::text("Command args (space-separated)", Some(""));

        if !custom.is_empty() {
            target.default_args = custom.split_whitespace().map(ToString::to_string).collect();
        }
    }

    target
}

fn run_bench(target: &ProfileTarget, crates_dir: &Path, args: &ProfileArgs) {
    if !args.quiet {
        output::header("Building benchmark...");
    }

    let bench_binary = build::build_bench(target, crates_dir, args.quiet);
    let Some(binary) = bench_binary else {
        fatal(format_args!(
            "failed to build benchmark '{}'",
            target.bin_name
        ));
    };

    if !args.quiet {
        output::success(&format!("Built: {}", binary.display()));
        output::header("Running benchmark...");
    }

    let result = monitor::run_monitored(&binary, &["--bench".to_string()], "error");

    if result.exit_code != 0 {
        fatal(format_args!("benchmark failed: {}", result.stderr));
    }

    report::print_bench_summary(&result.stdout);
}

fn run_profile(target: &ProfileTarget, crates_dir: &Path, args: &ProfileArgs) {
    if !samply::check_samply() {
        fatal(format_args!(
            "samply not found. install with: cargo install samply"
        ));
    }

    if !args.quiet {
        output::header("Building with bench-profile...");
    }

    let binary = build::build_target(target, crates_dir, args.quiet);
    let Some(binary) = binary else {
        fatal(format_args!("failed to build '{}'", target.bin_name));
    };

    if !args.quiet {
        output::success(&format!("Built: {}", binary.display()));
    }

    let (parameters, run_args) = if target.name == "engine" {
        let parameters =
            RunParameters::try_from(args).unwrap_or_else(|error| fatal(format_args!("{error}")));

        (
            Some(parameters),
            build_engine_run_args(target, args, parameters),
        )
    } else {
        (None, build_non_engine_run_args(target, args))
    };
    let host = monitor::collect_host_stats();

    if !args.quiet {
        output::header("Timing clean run (no profiler)...");
    }

    let clean = monitor::run_monitored(&binary, &run_args, "error");

    if clean.exit_code != 0 {
        fatal(format_args!("engine error: {}", clean.stderr));
    }

    let clean_secs = clean.duration.as_secs_f64();

    if !args.quiet {
        output::kv("Duration", &output::fmt_duration(clean_secs));
        output::kv(
            "Throughput",
            &format!(
                "{} sims/sec",
                output::fmt_number(
                    f64::from(parameters.map_or(args.iterations, RunParameters::iterations))
                        / clean_secs,
                )
            ),
        );
        output::blank();
    }

    if !args.quiet {
        output::header("Profiling with samply...");
    }

    let raw = capture_profile(&binary, &run_args, args.quiet)
        .unwrap_or_else(|error| fatal(format_args!("{error}")));

    let (symbols, _unresolved) = samply::resolve_symbols(&raw.strings, &binary, args.quiet);

    let spec = args
        .spec
        .clone()
        .or_else(|| extract_spec_from_args(&run_args))
        .unwrap_or_default();

    let analysis = analyze::analyze(
        &raw,
        &symbols,
        &spec,
        parameters.map_or(args.iterations, RunParameters::iterations),
        clean_secs,
        args.top,
    );

    if args.json {
        report::print_json(&analysis, &host, &clean.stats);
    } else {
        report::print_text(&analysis, &host, &clean.stats);
    }
}

fn capture_profile(
    binary: &Path,
    run_args: &[String],
    quiet: bool,
) -> Result<samply::RawProfile, CaptureProfileError> {
    let output = temporary::Directory::with_prefix("wowlab-forge-profile-")?;
    let path = output.path().join("profile.json.gz");

    samply::record(binary, run_args, &path)?;

    if !quiet {
        output::header("Analyzing profile...");
    }

    Ok(samply::parse(&path)?)
}

fn build_engine_run_args(
    target: &ProfileTarget,
    args: &ProfileArgs,
    parameters: RunParameters,
) -> Vec<String> {
    let spec = args.spec.clone().unwrap_or_else(|| {
        target
            .default_args
            .iter()
            .position(|argument| argument == "--spec")
            .and_then(|index| target.default_args.get(index + 1))
            .cloned()
            .expect("engine target must have a default --spec")
    });

    vec![
        "sim".to_string(),
        "--spec".to_string(),
        spec,
        "--iterations".to_string(),
        parameters.iterations().to_string(),
        "--duration".to_string(),
        parameters.fight_duration_secs().to_string(),
        "--threads".to_string(),
        "1".to_string(),
        "--format".to_string(),
        "json".to_string(),
    ]
}

fn build_non_engine_run_args(target: &ProfileTarget, args: &ProfileArgs) -> Vec<String> {
    if args.args.is_empty() {
        target.default_args.clone()
    } else {
        args.args.clone()
    }
}

const ARG_VALUE_PAIR: usize = 2;

fn extract_spec_from_args(run_args: &[String]) -> Option<String> {
    run_args
        .windows(ARG_VALUE_PAIR)
        // BOUNDS: windows(2) guarantees exactly 2 elements per slice
        .find(|w| w[0] == "--spec")
        .map(|w| w[1].clone())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[gtest]
    fn engine_command_uses_validated_parameters_in_stable_order() -> GtestResult<()> {
        let target = ProfileTarget {
            name: "engine".to_string(),
            package: "wowlab-engine".to_string(),
            bin_name: "engine".to_string(),
            kind: TargetKind::Binary,
            features: Vec::new(),
            default_args: vec![
                "sim".to_string(),
                "--spec".to_string(),
                "fire_mage".to_string(),
            ],
        };
        let args = ProfileArgs {
            target: Some("engine".to_string()),
            iterations: 17,
            duration: 45,
            spec: None,
            json: false,
            top: 50,
            quiet: false,
            bench: false,
            args: Vec::new(),
        };
        let parameters = RunParameters::try_from(&args).or_fail()?;

        verify_that!(
            build_engine_run_args(&target, &args, parameters),
            elements_are![
                "sim",
                "--spec",
                "fire_mage",
                "--iterations",
                "17",
                "--duration",
                "45",
                "--threads",
                "1",
                "--format",
                "json",
            ]
        )?;

        Ok(())
    }

    #[gtest]
    fn capture_profile_error_preserves_stage_context_and_source() -> GtestResult<()> {
        let error = CaptureProfileError::Parse(anyhow::anyhow!("invalid profile"));

        verify_that!(
            error.to_string(),
            eq("failed to parse profile: invalid profile")
        )?;
        verify_true!(std::error::Error::source(&error).is_some())?;

        Ok(())
    }
}