wowlab_engine_domain/rotation/

trace.rs

// #t(file: rust_inline_test_module_size) private trace-rendering tests cover the complete condition vocabulary beside the renderer

//! Human-readable labels for rotation condition trees (debug tracing).

use wowlab_types::sim::{Condition, Rotation};

use super::{
    buffer::{DenseBuffer, DescriptorTable},
    context::ContextSchema,
    lower::eval_condition_as,
    resolver::SpecResolver,
};

/// Structural label for `cond` (no live values).
pub fn condition_label(cond: &Condition) -> String {
    match cond {
        Condition::Read { field } => {
            if let Some(key) = &field.key {
                format!("{}.{}({})", field.domain, field.name, key)
            } else {
                format!("{}.{}", field.domain, field.name)
            }
        }
        Condition::Bool { value } => format!("{value}"),
        Condition::Int { value } => format!("{value}"),
        Condition::Float { value } => format!("{value}"),
        Condition::Var { name } => format!("var:{name}"),

        Condition::And { operands } => {
            let labels: Vec<String> = operands.iter().map(condition_label).collect();

            labels.join(" && ")
        }
        Condition::Or { operands } => {
            let labels: Vec<String> = operands.iter().map(condition_label).collect();

            labels.join(" || ")
        }
        Condition::Not { operand } => format!("!{}", condition_label(operand)),

        Condition::Compare { op, left, right } => {
            format!(
                "{} {} {}",
                condition_label(left),
                op.symbol(),
                condition_label(right)
            )
        }

        Condition::Arith { op, left, right } => {
            format!(
                "{} {} {}",
                condition_label(left),
                op.symbol(),
                condition_label(right)
            )
        }

        Condition::UnaryMath { op, operand } => {
            format!("{}({})", op.symbol(), condition_label(operand))
        }

        Condition::MinMax { op, left, right } => {
            format!(
                "{}({},{})",
                op.symbol(),
                condition_label(left),
                condition_label(right)
            )
        }

        Condition::IfThenElse {
            condition,
            then,
            otherwise,
        } => format!(
            "if({},{},{})",
            condition_label(condition),
            condition_label(then),
            condition_label(otherwise)
        ),
        _ => format!("<unsupported condition variant: {cond:?}>"),
    }
}

/// Borrowed evaluation context for [`condition_label_with_values`].
#[derive(Debug)]
// #t(rust_similar_structs) public trace evaluation adds mutable runtime state to private recorder metadata
pub struct TraceContext<'a> {
    pub rotation: &'a Rotation,
    pub schema: &'a ContextSchema,
    pub resolver: &'a SpecResolver,
    pub table: &'a DescriptorTable,
    pub buffer: &'a mut DenseBuffer,
    pub now_secs: f64,
}

/// Label for a false condition, inlining realized buffer values.
pub fn condition_label_with_values(condition: &Condition, ctx: &mut TraceContext<'_>) -> String {
    walk_for_label(condition, ctx)
}

// #t(fn: rust_recursive_fn) only recurses into the first failing `And` operand; depth is bounded by the condition nesting authored in the rotation, not by call volume.
fn walk_for_label(condition: &Condition, ctx: &mut TraceContext<'_>) -> String {
    match condition {
        Condition::And { operands } => {
            for op in operands {
                if !eval_bool(op, ctx) {
                    return walk_for_label(op, ctx);
                }
            }

            condition_label(condition)
        }
        Condition::Compare { left, right, .. } => {
            let left_value = eval_float(left, ctx);
            let right_value = eval_float(right, ctx);

            format!(
                "{} (was: {} vs {})",
                condition_label(condition),
                format_value(left_value),
                format_value(right_value),
            )
        }
        _ => condition_label(condition),
    }
}

fn eval_bool(condition: &Condition, ctx: &mut TraceContext<'_>) -> bool {
    eval_condition_as(condition, ctx, |value, backend| value.into_bool(backend))
}

fn eval_float(condition: &Condition, ctx: &mut TraceContext<'_>) -> f64 {
    eval_condition_as(condition, ctx, |value, backend| value.into_float(backend))
}

fn format_value(value: f64) -> String {
    if value.is_nan() {
        return "NaN".to_string();
    }

    let rounded = value.round();

    if (value - rounded).abs() < f64::EPSILON {
        format!(
            "{}",
            wowlab_types::numeric::f64_to_i64_saturating_trunc(rounded)
        )
    } else {
        format!("{value:.3}")
    }
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;
    use rstest::rstest;
    use wowlab_types::sim::{ArithOp, CompareOp, FieldRead, MinMaxOp, UnaryMathOp};

    use super::*;

    fn read(domain: &str, name: &str, key: Option<&str>) -> Condition {
        Condition::Read {
            field: FieldRead {
                domain: domain.into(),
                name: name.into(),
                key: key.map(Into::into),
                on: None,
            },
        }
    }

    fn boxed(cond: Condition) -> Box<Condition> {
        Box::new(cond)
    }

    #[gtest]
    fn condition_label_read_without_key() -> Result<()> {
        verify_that!(
            condition_label(&read("domain", "name", None)),
            eq("domain.name")
        )?;

        Ok(())
    }

    #[gtest]
    fn condition_label_read_with_key() -> Result<()> {
        verify_that!(
            condition_label(&read("domain", "name", Some("kc"))),
            eq("domain.name(kc)")
        )?;

        Ok(())
    }

    #[gtest]
    fn condition_label_bool() -> Result<()> {
        verify_that!(
            condition_label(&Condition::Bool { value: true }),
            eq("true")
        )?;

        Ok(())
    }

    #[gtest]
    fn condition_label_int() -> Result<()> {
        verify_that!(condition_label(&Condition::Int { value: 5 }), eq("5"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_float() -> Result<()> {
        verify_that!(condition_label(&Condition::Float { value: 2.5 }), eq("2.5"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_var() -> Result<()> {
        verify_that!(
            condition_label(&Condition::Var { name: "x".into() }),
            eq("var:x")
        )?;

        Ok(())
    }

    #[gtest]
    fn condition_label_and() -> Result<()> {
        let cond = Condition::And {
            operands: vec![
                Condition::Var { name: "a".into() },
                Condition::Var { name: "b".into() },
            ],
        };

        verify_that!(condition_label(&cond), eq("var:a && var:b"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_or() -> Result<()> {
        let cond = Condition::Or {
            operands: vec![
                Condition::Var { name: "a".into() },
                Condition::Var { name: "b".into() },
            ],
        };

        verify_that!(condition_label(&cond), eq("var:a || var:b"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_not() -> Result<()> {
        let cond = Condition::Not {
            operand: boxed(Condition::Var { name: "a".into() }),
        };

        verify_that!(condition_label(&cond), eq("!var:a"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_compare() -> Result<()> {
        let cond = Condition::Compare {
            op: CompareOp::Gt,
            left: boxed(Condition::Var { name: "l".into() }),
            right: boxed(Condition::Var { name: "r".into() }),
        };

        verify_that!(condition_label(&cond), eq("var:l > var:r"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_arith() -> Result<()> {
        let cond = Condition::Arith {
            op: ArithOp::Add,
            left: boxed(Condition::Var { name: "l".into() }),
            right: boxed(Condition::Var { name: "r".into() }),
        };

        verify_that!(condition_label(&cond), eq("var:l + var:r"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_unary_math() -> Result<()> {
        let cond = Condition::UnaryMath {
            op: UnaryMathOp::Floor,
            operand: boxed(Condition::Var { name: "x".into() }),
        };

        verify_that!(condition_label(&cond), eq("floor(var:x)"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_min_max() -> Result<()> {
        let cond = Condition::MinMax {
            op: MinMaxOp::Max,
            left: boxed(Condition::Var { name: "l".into() }),
            right: boxed(Condition::Var { name: "r".into() }),
        };

        verify_that!(condition_label(&cond), eq("max(var:l,var:r)"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_if_then_else() -> Result<()> {
        let cond = Condition::IfThenElse {
            condition: boxed(Condition::Var { name: "c".into() }),
            then: boxed(Condition::Var { name: "t".into() }),
            otherwise: boxed(Condition::Var { name: "e".into() }),
        };

        verify_that!(condition_label(&cond), eq("if(var:c,var:t,var:e)"))?;

        Ok(())
    }

    #[gtest]
    fn condition_label_nested_composite_snapshot() {
        let cond = Condition::And {
            operands: vec![
                Condition::Compare {
                    op: CompareOp::Gt,
                    left: boxed(read("cooldown", "charges", Some("kc"))),
                    right: boxed(Condition::Int { value: 1 }),
                },
                Condition::Not {
                    operand: boxed(Condition::Var {
                        name: "pooling".into(),
                    }),
                },
            ],
        };

        insta::assert_snapshot!(condition_label(&cond));
    }

    #[gtest]
    #[rstest]
    #[case::nan(f64::NAN, "NaN")]
    #[case::positive_integer(3.0, "3")]
    #[case::negative_integer(-2.0, "-2")]
    #[case::decimal(2.5, "2.500")]
    #[case::epsilon_boundary(0.0001, "0.000")]
    fn format_value_arms(#[case] value: f64, #[case] expected: &str) -> Result<()> {
        verify_that!(format_value(value), eq(expected))?;

        Ok(())
    }
}