forge/bench/

report.rs

// #t(file: rust_alloc_in_loop) CLI binary, building chart data in loops is fine.
// #t(file: rust_hardcoded_url) commit URLs are constructed for the report.

use anyhow::{Context, Result};
use maud::{Markup, html};
use wowlab_fs::{atomic, directory, path::Path};

use super::{
    charts,
    types::{BenchHistory, BenchRun},
};
use crate::report::{Page, chart_box};

const GITHUB_REPO: &str = "https://github.com/legacy3/wowlab";
const BENCH_JS: &str = include_str!("report.js");

const TIMESTAMP_DATE_LEN: usize = 10;

struct RunCharts {
    throughput: String,
    dps: String,
    scatter: String,
    scaling_throughput: Option<String>,
    scaling_multiplier: Option<String>,
    scaling_efficiency: Option<String>,
    scaling_marginal: Option<String>,
}

fn run_label(run: &BenchRun, index: usize, total: usize) -> String {
    let age = total - index;
    let tag = if age == 1 {
        " (latest)".to_string()
    } else {
        format!(" (-{} runs)", age - 1)
    };
    let date_end = TIMESTAMP_DATE_LEN.min(run.timestamp.len());
    // BOUNDS: date_end is clamped to timestamp length.
    let date = &run.timestamp[..date_end];

    format!(
        "v{} {}@{} {}{}",
        run.engine_version, run.git_branch, run.git_hash, date, tag
    )
}

fn build_run_charts(run: &BenchRun) -> Result<RunCharts> {
    let single = BenchHistory {
        runs: vec![run.clone()],
    };

    let scaling =
        |f: fn(&[super::types::ScalingResult]) -> Result<String>| -> Result<Option<String>> {
            if run.scaling.is_empty() {
                Ok(None)
            } else {
                f(&run.scaling).map(Some)
            }
        };

    Ok(RunCharts {
        throughput: charts::throughput(&single)?,
        dps: charts::dps(&single)?,
        scatter: charts::throughput_vs_dps(&single)?,
        scaling_throughput: scaling(charts::scaling_throughput)?,
        scaling_multiplier: scaling(charts::scaling_multiplier)?,
        scaling_efficiency: scaling(charts::scaling_efficiency)?,
        scaling_marginal: scaling(charts::scaling_marginal_gain)?,
    })
}

fn render_meta(run: &BenchRun) -> Markup {
    let sys = &run.system;
    let cpu = if sys.cpu_model.is_empty() {
        "Unknown"
    } else {
        &sys.cpu_model
    };

    let items: Vec<(&str, String)> = vec![
        ("Engine", format!("v{}", run.engine_version)),
        ("Git", format!("{}@{}", run.git_branch, run.git_hash)),
        ("CPU", cpu.to_string()),
        ("Cores", format!("{}P + {}E", sys.p_cores, sys.e_cores)),
        ("Rustc", run.rustc_version.clone()),
        ("Backend", format!("{:?}", run.backend)),
        (
            "Features",
            if run.features.is_empty() {
                "none".to_string()
            } else {
                run.features.join(", ")
            },
        ),
    ];

    html! {
        div class="field is-grouped is-grouped-multiline mb-4" {
            @for (label, value) in &items {
                div class="control" {
                    div class="tags has-addons" {
                        span class="tag is-dark" { (label) }
                        span class="tag is-info is-light" { (value) }
                    }
                }
            }
        }
    }
}

fn render_table(run: &BenchRun, prev: Option<&BenchRun>) -> Markup {
    let mut sorted = run.results.clone();

    sorted.sort_by(|a, b| {
        b.median_iterations_per_sec
            .partial_cmp(&a.median_iterations_per_sec)
            .unwrap_or(std::cmp::Ordering::Equal)
    });

    html! {
        div class="table-container" {
            table class="table is-hoverable is-fullwidth is-narrow is-striped" {
                caption class="is-sr-only" { "Per-spec throughput results, latest run" }
                thead {
                    tr {
                        th scope="col" { "Spec" }
                        th scope="col" { "Encounter" }
                        th scope="col" class="has-text-right" { "Median iter/s" }
                        th scope="col" class="has-text-right" { "Mean iter/s" }
                        th scope="col" class="has-text-right" { "Std dev iter/s" }
                        th scope="col" class="has-text-right" { "vs Prev" }
                        th scope="col" class="has-text-right" { "Mean DPS" }
                        th scope="col" class="has-text-right" { "Events/iter" }
                        th scope="col" class="has-text-right" { "Rotations/iter" }
                        th scope="col" class="has-text-right" { "Damage/iter" }
                        th scope="col" class="has-text-right" { "Auras/iter" }
                        th scope="col" class="has-text-right" { "Allocations/iter" }
                        th scope="col" { "Fingerprint" }
                    }
                }
                tbody {
                    @for r in &sorted {
                        @let prev_ips = prev.and_then(|p| {
                            p.results.iter()
                                .find(|pr| pr.slug == r.slug)
                                .map(|pr| pr.median_iterations_per_sec)
                        });
                        @let (delta_text, delta_cls) = format_delta(r.median_iterations_per_sec, prev_ips);
                        @let normalized = normalized_counts(r);
                        tr {
                            td { (r.slug) }
                            td { (r.encounter_fixture) }
                            td class="has-text-right" { (format!("{:.1}", r.median_iterations_per_sec)) }
                            td class="has-text-right" { (format!("{:.1}", r.mean_iterations_per_sec)) }
                            td class="has-text-right" { (format!("{:.1}", r.population_stddev_iterations_per_sec)) }
                            td class=(format!("has-text-right {delta_cls}")) { (delta_text) }
                            td class="has-text-right" { (format!("{:.0}", r.mean_dps)) }
                            td class="has-text-right" { (format!("{:.2}", normalized.events)) }
                            td class="has-text-right" { (format!("{:.2}", normalized.rotations)) }
                            td class="has-text-right" { (format!("{:.2}", normalized.damage)) }
                            td class="has-text-right" { (format!("{:.2}", normalized.auras)) }
                            td class="has-text-right" { (format!("{:.2}", normalized.allocations)) }
                            td { code { (r.semantic_fingerprint) } }
                        }
                    }
                }
            }
        }
    }
}

struct NormalizedCounts {
    events: f64,
    rotations: f64,
    damage: f64,
    auras: f64,
    allocations: f64,
}

fn normalized_counts(result: &super::types::SpecBenchResult) -> NormalizedCounts {
    let sample_count = u64::try_from(result.samples.len()).unwrap_or(u64::MAX);
    let denominator = f64::from(result.iterations) * count_as_f64(sample_count);

    if denominator <= f64::EPSILON {
        return NormalizedCounts {
            events: 0.0,
            rotations: 0.0,
            damage: 0.0,
            auras: 0.0,
            allocations: 0.0,
        };
    }

    NormalizedCounts {
        events: result
            .samples
            .iter()
            .map(|sample| count_as_f64(sample.counters.events))
            .sum::<f64>()
            / denominator,
        rotations: result
            .samples
            .iter()
            .map(|sample| count_as_f64(sample.counters.rotation_evaluations))
            .sum::<f64>()
            / denominator,
        damage: result
            .samples
            .iter()
            .map(|sample| count_as_f64(sample.counters.damage_events))
            .sum::<f64>()
            / denominator,
        auras: result
            .samples
            .iter()
            .map(|sample| count_as_f64(sample.counters.aura_events))
            .sum::<f64>()
            / denominator,
        allocations: result
            .samples
            .iter()
            .filter_map(|sample| sample.allocations)
            .map(|allocations| count_as_f64(allocations.count))
            .sum::<f64>()
            / denominator,
    }
}

#[expect(
    clippy::cast_precision_loss,
    reason = "integer benchmark counters are rendered as approximate floating-point rates"
)]
const fn count_as_f64(count: u64) -> f64 {
    count as f64
}

fn format_delta(current: f64, previous: Option<f64>) -> (String, &'static str) {
    match previous {
        Some(old) if old > 0.0 => {
            let pct = ((current - old) / old) * wowlab_types::constants::HUNDRED;
            let sign = if pct > 0.0 { "+" } else { "" };
            let cls = if pct.abs() < 1.0 {
                "neutral"
            } else if pct > 0.0 {
                "pos"
            } else {
                "neg"
            };

            (format!("{sign}{pct:.1}%"), cls)
        }
        _ => ("-".to_string(), "neutral"),
    }
}

fn run_chart_data(run_charts: &RunCharts, commit_url: &str) -> serde_json::Value {
    serde_json::json!({
        "commitUrl": commit_url,
        "throughput": serde_json::from_str::<serde_json::Value>(&run_charts.throughput).unwrap_or_default(),
        "dps": serde_json::from_str::<serde_json::Value>(&run_charts.dps).unwrap_or_default(),
        "scatter": serde_json::from_str::<serde_json::Value>(&run_charts.scatter).unwrap_or_default(),
        "scalingThroughput": run_charts.scaling_throughput.as_deref()
            .and_then(|s| serde_json::from_str::<serde_json::Value>(s).ok()),
        "scalingMultiplier": run_charts.scaling_multiplier.as_deref()
            .and_then(|s| serde_json::from_str::<serde_json::Value>(s).ok()),
        "scalingEfficiency": run_charts.scaling_efficiency.as_deref()
            .and_then(|s| serde_json::from_str::<serde_json::Value>(s).ok()),
        "scalingMarginal": run_charts.scaling_marginal.as_deref()
            .and_then(|s| serde_json::from_str::<serde_json::Value>(s).ok()),
    })
}

struct RunView {
    index: usize,
    label: String,
    meta: Markup,
    table: Markup,
    chart_data: serde_json::Value,
    has_scaling: bool,
}

fn build_run_views(history: &BenchHistory) -> Result<Vec<RunView>> {
    let total = history.runs.len();
    let mut views = Vec::new();

    for (i, run) in history.runs.iter().enumerate() {
        let prev = i.checked_sub(1).and_then(|index| history.runs.get(index));
        let label = run_label(run, i, total);
        let meta = render_meta(run);
        let table = render_table(run, prev);
        let run_charts = build_run_charts(run)?;
        let commit_url = format!("{}/tree/{}", GITHUB_REPO, run.git_hash);
        let chart_data = run_chart_data(&run_charts, &commit_url);

        views.push(RunView {
            index: i,
            label,
            meta,
            table,
            chart_data,
            has_scaling: !run.scaling.is_empty(),
        });
    }

    Ok(views)
}

fn render_header_extras(run_views: &[RunView]) -> Markup {
    let latest = run_views.len().saturating_sub(1);

    html! {
        div class="field is-grouped mb-3" {
            div class="control" {
                div class="select is-small" {
                    select #run-select
                        aria-label="Select benchmark run"
                        onchange="benchSelectRun(this.value)" {
                        @for v in run_views.iter().rev() {
                            option value=(v.index) selected[v.index == latest] { (v.label) }
                        }
                    }
                }
            }
            div class="control" {
                a #commit-link
                    class="is-size-7 has-text-weak"
                    href=""
                    target="_blank"
                    rel="noopener noreferrer" { "" }
            }
        }
    }
}

fn render_overview(run_views: &[RunView]) -> Markup {
    let latest = run_views.len().saturating_sub(1);

    html! {
        @for v in run_views {
            div class="run-view" data-run=(v.index) hidden[v.index != latest] {
                (v.meta)
                div class="columns" {
                    div class="column is-half" {
                        (chart_box("Throughput", "chart", "throughput"))
                    }
                    div class="column is-half" {
                        (chart_box("DPS", "chart", "dps"))
                    }
                }
                (chart_box("Throughput vs DPS", "chart", "scatter"))
            }
        }
    }
}

fn render_scaling(run_views: &[RunView]) -> Markup {
    let latest = run_views.len().saturating_sub(1);

    html! {
        @for v in run_views {
            div class="run-view" data-run=(v.index) hidden[v.index != latest] {
                @if v.has_scaling {
                    (chart_box("Scaling: Throughput", "chart-tall", "scalingThroughput"))
                    div class="columns" {
                        div class="column is-half" {
                            (chart_box("Multiplier", "chart", "scalingMultiplier"))
                        }
                        div class="column is-half" {
                            (chart_box("Efficiency", "chart", "scalingEfficiency"))
                        }
                    }
                    (chart_box("Marginal Gain", "chart", "scalingMarginal"))
                } @else {
                    p class="has-text-grey" { "No scaling data for this run." }
                }
            }
        }
    }
}

fn render_history() -> Markup {
    html! {
        div class="box" {
            p class="chart-label" { "Throughput Over Time" }
            div #historyChart class="chart-tall" {}
        }
        div class="box" {
            p class="chart-label" { "DPS Over Time" }
            div #dpsHistoryChart class="chart-tall" {}
        }
    }
}

fn render_details(run_views: &[RunView]) -> Markup {
    let latest = run_views.len().saturating_sub(1);

    html! {
        @for v in run_views {
            div class="run-view" data-run=(v.index) hidden[v.index != latest] {
                div class="box" {
                    (v.table.clone())
                }
            }
        }
    }
}

pub(crate) fn generate(output_path: &Path, history: &BenchHistory) -> Result<()> {
    if let Some(parent) = output_path.parent() {
        directory::ensure(parent)
            .with_context(|| format!("failed to create directory {}", parent.display()))?;
    }

    let history_chart_json = charts::history_lines(history)?;
    let dps_history_chart_json = charts::dps_history_lines(history)?;
    let run_views = build_run_views(history)?;

    let mut page = Page::new(
        "Engine Benchmark Report",
        "Performance tracking across specs and commits",
    )
    .footer_command("cargo forge bench")
    .header_extras(render_header_extras(&run_views))
    .tab("overview", "Overview")
    .tab("scaling", "Scaling")
    .tab("history", "History")
    .tab("details", "Details")
    .section("overview", render_overview(&run_views))
    .section("scaling", render_scaling(&run_views))
    .section("history", render_history())
    .section("details", render_details(&run_views));

    for v in &run_views {
        page = page.data_script(format!("run-data-{}", v.index), v.chart_data.to_string());
    }

    page = page
        .data_script("history-data", history_chart_json)
        .data_script("dps-history-data", dps_history_chart_json)
        .extra_js(BENCH_JS);
    let rendered = page.render();

    atomic::replace(output_path, rendered)
        .with_context(|| format!("failed to write report to {}", output_path.display()))?;

    Ok(())
}