forge/

envelope.rs

// #t(file: rust_alloc_in_loop) CLI diagnostics favor readable aggregation over allocation minimization.

#![expect(
    clippy::cast_precision_loss,
    reason = "bounded telemetry counters and milliseconds are converted to CLI display values"
)]

//! Run a browser-style v2 intent envelope through the local engine with decision tracing.

use std::{collections::BTreeMap, io::Read};

use anyhow::{Context, Result};
use clap::Args;
#[cfg(test)]
use googletest::{Result as GtestResult, prelude::*};
use prost::Message;
use serde_json::Value;
use tabled::Tabled;
use wowlab_common::{
    output,
    sim::{
        intent::parse_sim_config,
        synthetic::{WASM_PREVIEW_JOB_LABEL, WASM_PREVIEW_ROTATION_ID},
    },
};
use wowlab_engine_adapter_data::{LocalCsvResolver, OverlayResolver};
use wowlab_engine_application::{IntentOverrides, SimRequest, simulate_intent_with_trace};
use wowlab_engine_ports::{
    ChunkAssignment, Decision, DynDataResolver, EvaluationStatus, NoopProgress, VecSink,
    content_catalog,
};
use wowlab_fs::{
    file,
    path::{Path, PathBuf},
};
use wowlab_types::{constants::MS_PER_SECOND, game::SpecId, proto::ChunkTelemetry, sim::FastMap};

use crate::{constants, trace, wowlab};

const DEFAULT_DECISION_LIMIT: usize = 25;
const DEFAULT_SEED: u64 = 42;

#[derive(Args, Debug)]
pub(crate) struct EnvelopeArgs {
    /// Path to a v2 intent TOML. Use `-` to read it from stdin.
    pub envelope: PathBuf,

    /// Rotation JSON to inject exactly like the browser preview.
    #[arg(long)]
    pub rotation: Option<PathBuf>,

    /// Deterministic seed (browser preview default: 42).
    #[arg(long, default_value_t = DEFAULT_SEED)]
    pub seed: u64,

    /// Maximum aggregated decision outcomes to display.
    #[arg(long, default_value_t = DEFAULT_DECISION_LIMIT)]
    pub decision_limit: usize,

    /// Enable low-level TRACE logging to a retained temporary file.
    #[arg(long)]
    pub trace: bool,
}

#[derive(Debug)]
struct LoadedRotation {
    source: String,
    value: Value,
}

#[derive(Debug, Default)]
struct ActionAggregate {
    casts: u64,
    crits: u64,
    damage: f64,
    hits: u64,
}

#[derive(Debug, Tabled)]
struct ActionRow {
    #[tabled(rename = "Spell")]
    spell: String,
    #[tabled(rename = "ID")]
    spell_id: u32,
    #[tabled(rename = "DPS")]
    dps: String,
    #[tabled(rename = "Damage")]
    damage: String,
    #[tabled(skip)]
    damage_value: f64,
    #[tabled(rename = "Casts")]
    casts: u64,
    #[tabled(rename = "Hits")]
    hits: u64,
    #[tabled(rename = "Crits")]
    crits: u64,
}

#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
struct DecisionKey {
    action_index: usize,
    list_id: String,
    reason: String,
    status: String,
}

#[derive(Clone, Debug)]
// #t(rust_similar_structs) decision outcomes carry rendered labels and counts beyond their grouping key
struct DecisionOutcome {
    action_index: usize,
    count: u64,
    label: String,
    list_id: String,
    reason: String,
    status: String,
}

#[derive(Debug, Tabled)]
struct DecisionRow {
    #[tabled(rename = "Action")]
    action: String,
    #[tabled(rename = "Outcome")]
    outcome: String,
    #[tabled(rename = "Count")]
    count: u64,
    #[tabled(rename = "Reason")]
    reason: String,
}

pub(crate) fn run(args: &EnvelopeArgs) -> Result<()> {
    let sim_config = read_input(&args.envelope, "intent envelope")?;
    let intent = parse_sim_config(&sim_config).context("invalid v2 intent envelope")?;
    let spec = SpecId::parse_wow_spec_id(intent.spec)
        .map_err(|message| anyhow::anyhow!("invalid intent spec: {message}"))?;
    let rotation = load_rotation(args.rotation.as_deref(), spec)?;
    let trace_path = trace::init_trace_log(args.trace, &format!("envelope-{}", spec.slug()))?;

    output::header(&format!("Running engine envelope ({})", spec.slug()));
    output::kv("Envelope", &display_input(&args.envelope));
    output::kv("Rotation", &rotation.source);
    output::kv_fmt("Seed", args.seed);
    output::kv_fmt("Targets", intent.encounter.enemies.len());

    if let Some(path) = &trace_path {
        output::kv("Trace log", &path.display().to_string());
    }

    output::blank();

    let rotation_json =
        serde_json::to_string(&rotation.value).context("failed to serialize injected rotation")?;
    let data_dir =
        std::env::var("WOWLAB_DATA_DIR").unwrap_or_else(|_| constants::default_data_dir());
    let resolver = OverlayResolver::new(LocalCsvResolver::new(data_dir.as_str()))
        .with_rotation_script(WASM_PREVIEW_ROTATION_ID, rotation_json);
    let resolver_dyn = DynDataResolver::from_ref(&resolver);
    let chunk = ChunkAssignment::single_indexed(WASM_PREVIEW_JOB_LABEL, 0, 1);
    let overrides = IntentOverrides::with_rotation_id_override(WASM_PREVIEW_ROTATION_ID);
    let request = SimRequest {
        sim_config: &sim_config,
        chunk: &chunk,
        seed_base: args.seed,
        overrides,
    };
    let sink = VecSink::new();
    let runtime = tokio::runtime::Runtime::new().context("failed to create Tokio runtime")?;
    let catalog = content_catalog().context("engine content catalog is unavailable")?;
    let report = runtime
        .block_on(simulate_intent_with_trace(
            catalog,
            request,
            resolver_dyn,
            &NoopProgress,
            sink.clone(),
        ))
        .context("engine envelope simulation failed")?;
    let telemetry = ChunkTelemetry::decode(report.telemetry_bytes.as_slice())
        .context("failed to decode envelope telemetry")?;

    let mut name_map = wowlab::build_spell_name_map(spec)?;

    runtime.block_on(wowlab::enrich_spell_name_map(
        &mut name_map,
        telemetry.actions.iter().map(|action| action.spell_id),
        resolver_dyn,
    ));

    print_summary(&telemetry, sink.snapshot().len());
    print_actions(&telemetry, &name_map);

    let outcomes = summarize_decisions(&sink.snapshot(), &rotation.value);

    print_decisions(&outcomes, args.decision_limit);
    print_stall_warning(&telemetry, &outcomes);

    if let Some(path) = trace_path {
        output::blank();
        output::detail(&format!("Trace log written to: {}", path.display()));
        output::detail(&format!(
            "Cast rejections: rg 'REJECT_CANCAST' {}",
            path.display()
        ));
    }

    Ok(())
}

fn read_input(path: &Path, label: &str) -> Result<String> {
    if path.as_os_str() == "-" {
        let mut source = String::new();

        std::io::stdin()
            .read_to_string(&mut source)
            .with_context(|| format!("failed to read {label} from stdin"))?;

        return Ok(source);
    }

    file::read_text(path).with_context(|| format!("failed to read {label} {}", path.display()))
}

fn display_input(path: &Path) -> String {
    if path.as_os_str() == "-" {
        "stdin".to_string()
    } else {
        path.display().to_string()
    }
}

fn load_rotation(path: Option<&Path>, spec: SpecId) -> Result<LoadedRotation> {
    if let Some(path) = path {
        let source = read_input(path, "rotation JSON")?;
        let value = serde_json::from_str(&source)
            .with_context(|| format!("invalid rotation JSON {}", display_input(path)))?;

        return Ok(LoadedRotation {
            source: display_input(path),
            value,
        });
    }

    let rotation_id = format!("{}_assisted", spec.slug());
    let path = constants::engine_dir()
        .join("examples/rotations")
        .join(format!("{rotation_id}.json"));
    let source = file::read_text(&path)
        .with_context(|| format!("failed to read assisted rotation {}", path.display()))?;
    let value: Value = serde_json::from_str(&source)
        .with_context(|| format!("invalid assisted rotation JSON {}", path.display()))?;
    let value = wowlab_parsers::apply_rotation_overlay(spec.slug(), &value)
        .context("failed to apply assisted rotation overlay")?;

    Ok(LoadedRotation {
        source: format!("{} (assisted + overlay)", path.display()),
        value,
    })
}

fn print_summary(telemetry: &ChunkTelemetry, decision_count: usize) {
    let total_casts: u64 = telemetry.actions.iter().map(|action| action.casts).sum();

    output::subheader("Run Summary");
    output::kv("Mean DPS", &format!("{:.1}", telemetry.mean_dps()));
    output::kv_fmt(
        "Fight time",
        format!(
            "{:.3}s",
            telemetry.total_fight_time_ms as f64 / MS_PER_SECOND
        ),
    );
    output::kv_fmt("Recorded casts", total_casts);
    output::kv_fmt("Decision frames", decision_count);
    output::blank();
}

fn print_actions(telemetry: &ChunkTelemetry, names: &FastMap<u32, String>) {
    let duration_s = telemetry.total_fight_time_ms as f64 / MS_PER_SECOND;
    let mut aggregates: BTreeMap<u32, ActionAggregate> = BTreeMap::new();

    for action in &telemetry.actions {
        let aggregate = aggregates.entry(action.spell_id).or_default();

        aggregate.casts += action.casts;
        aggregate.crits += action.crits;
        aggregate.damage += action.total_damage();
        aggregate.hits += action.direct_hits;
    }

    let mut rows: Vec<ActionRow> = aggregates
        .into_iter()
        .map(|(spell_id, aggregate)| ActionRow {
            spell: names
                .get(&spell_id)
                .cloned()
                .unwrap_or_else(|| format!("unknown#{spell_id}")),
            spell_id,
            dps: if duration_s > 0.0 {
                format!("{:.1}", aggregate.damage / duration_s)
            } else {
                "0.0".to_string()
            },
            damage: format!("{:.1}", aggregate.damage),
            damage_value: aggregate.damage,
            casts: aggregate.casts,
            hits: aggregate.hits,
            crits: aggregate.crits,
        })
        .collect();

    rows.sort_by(|left, right| right.damage_value.total_cmp(&left.damage_value));

    output::subheader("Action Breakdown");
    output::table(rows);
    output::blank();
}

fn summarize_decisions(decisions: &[Decision], rotation: &Value) -> Vec<DecisionOutcome> {
    let mut counts = BTreeMap::new();

    collect_decisions(decisions, &mut counts);
    let mut outcomes: Vec<DecisionOutcome> = counts
        .into_iter()
        .map(|(key, count)| DecisionOutcome {
            label: action_label(rotation, &key.list_id, key.action_index),
            action_index: key.action_index,
            count,
            list_id: key.list_id,
            reason: key.reason,
            status: key.status,
        })
        .collect();

    outcomes.sort_by(|left, right| {
        right
            .count
            .cmp(&left.count)
            .then_with(|| left.list_id.cmp(&right.list_id))
            .then_with(|| left.action_index.cmp(&right.action_index))
    });

    outcomes
}

// #t(fn: rust_clone_in_loop) aggregation keys own trace strings after borrowed decisions are released.
fn collect_decisions(decisions: &[Decision], counts: &mut BTreeMap<DecisionKey, u64>) {
    let mut pending: Vec<&Decision> = decisions.iter().collect();

    while let Some(decision) = pending.pop() {
        for evaluation in &decision.evaluations {
            let key = DecisionKey {
                action_index: evaluation.action_index,
                list_id: evaluation.list_id.clone(),
                reason: evaluation.rejection_reason.clone().unwrap_or_default(),
                status: status_label(evaluation.status).to_string(),
            };

            *counts.entry(key).or_default() += 1;
        }

        pending.extend(&decision.nested);
    }
}

const fn status_label(status: EvaluationStatus) -> &'static str {
    match status {
        EvaluationStatus::Disabled => "disabled",
        EvaluationStatus::Executed => "executed",
        EvaluationStatus::Fired => "fired",
        EvaluationStatus::NotReached => "not reached",
        EvaluationStatus::Rejected => "rejected",
        _ => "unknown",
    }
}

fn action_label(rotation: &Value, list_id: &str, action_index: usize) -> String {
    let action = if list_id == "actions" {
        rotation
            .get("actions")
            .and_then(Value::as_array)
            .and_then(|actions| actions.get(action_index))
    } else {
        rotation
            .get("lists")
            .and_then(|lists| lists.get(list_id))
            .and_then(Value::as_array)
            .and_then(|actions| actions.get(action_index))
    };
    let Some(action) = action else {
        return format!("{list_id}[{action_index}]");
    };
    let kind = action
        .get("type")
        .and_then(Value::as_str)
        .unwrap_or("action");
    let detail = ["spell", "list", "name", "slot"]
        .into_iter()
        .find_map(|key| action.get(key).and_then(value_label));

    match detail {
        Some(detail) => format!("{list_id}[{action_index}] {kind} {detail}"),
        None => format!("{list_id}[{action_index}] {kind}"),
    }
}

fn value_label(value: &Value) -> Option<String> {
    match value {
        Value::String(value) => Some(value.clone()),
        Value::Number(value) => Some(value.to_string()),
        _ => None,
    }
}

fn print_decisions(outcomes: &[DecisionOutcome], limit: usize) {
    output::subheader("Decision Outcomes");
    let rows = outcomes.iter().take(limit).map(|outcome| DecisionRow {
        action: outcome.label.clone(),
        outcome: outcome.status.clone(),
        count: outcome.count,
        reason: outcome.reason.clone(),
    });

    output::table(rows);

    if outcomes.len() > limit {
        output::detail(&format!(
            "Showing {limit} of {} outcomes; increase --decision-limit to see more.",
            outcomes.len()
        ));
    }

    output::blank();
}

fn print_stall_warning(telemetry: &ChunkTelemetry, outcomes: &[DecisionOutcome]) {
    let total_casts: u64 = telemetry.actions.iter().map(|action| action.casts).sum();

    if total_casts > 0 {
        return;
    }

    let Some(fired) = outcomes.iter().find(|outcome| outcome.status == "fired") else {
        output::warning("Rotation produced no casts and no action reached the fired state.");

        return;
    };

    output::warning(&format!(
        "Rotation stall: no casts were recorded while {} was selected {} times.",
        fired.label, fired.count
    ));
}

#[cfg(test)]
mod tests {
    use serde_json::json;
    use wowlab_engine_ports::ActionEvaluation;
    use wowlab_fs::temporary::Directory;

    use super::*;

    #[gtest]
    fn action_label_resolves_root_and_named_list_actions() -> GtestResult<()> {
        let rotation = json!({
            "actions": [{ "list": "main", "type": "call" }],
            "lists": {
                "main": [{ "spell": "roll_the_bones", "type": "cast" }]
            }
        });

        verify_that!(
            action_label(&rotation, "actions", 0),
            eq("actions[0] call main")
        )?;
        verify_that!(
            action_label(&rotation, "main", 0),
            eq("main[0] cast roll_the_bones")
        )?;

        Ok(())
    }

    #[gtest]
    fn summarize_decisions_counts_repeated_stalled_selection() -> GtestResult<()> {
        let rotation = json!({
            "lists": {
                "main": [{ "spell": "roll_the_bones", "type": "cast" }]
            }
        });
        let decision = Decision {
            time_ms: 0,
            list_id: "main".to_string(),
            fired_action_index: Some(0),
            evaluations: vec![ActionEvaluation {
                list_id: "main".to_string(),
                action_index: 0,
                status: EvaluationStatus::Fired,
                rejection_reason: None,
            }],
            nested: Vec::new(),
        };

        let outcomes = summarize_decisions(&[decision.clone(), decision], &rotation);

        verify_that!(
            outcomes.as_slice(),
            elements_are![matches_pattern!(DecisionOutcome {
                count: eq(&2),
                label: eq("main[0] cast roll_the_bones"),
                status: eq("fired"),
                ..
            })]
        )?;

        Ok(())
    }

    #[gtest]
    fn explicit_rotation_uses_shared_file_input_and_preserves_source_diagnostics() -> GtestResult<()>
    {
        let temporary = Directory::new().or_fail()?;
        let path = temporary.path().join("rotation.json");

        file::write_text(&path, r#"{"actions":[]}"#).or_fail()?;

        let rotation = load_rotation(Some(&path), SpecId::Outlaw).or_fail()?;
        let expected_source = path.display().to_string();

        verify_that!(rotation.source, eq(&expected_source))?;
        verify_that!(rotation.value, eq(&json!({ "actions": [] })))?;

        let missing = temporary.path().join("missing.toml");
        let error = read_input(&missing, "intent envelope").unwrap_err();

        verify_that!(
            error.to_string(),
            contains_substring(format!(
                "failed to read intent envelope {}",
                missing.display()
            ))
        )
    }
}