wowlab_engine_application/audit/

generic_folds.rs

// #t(file: rust_alloc_in_loop) the audit renders one owned diagnostic per finding, bounded by manifest size

//! Duplicate-fold check for content that re-declares a folded DBC damage modifier.
//!
//! Five static shapes are detected.
//!
//! Shape one is an aura declaring a damage-multiplier field over its own folded DBC effect.
//! Shape two is an `[effects]` entry naming a registered aura's folded damage effect.
//! Only shape two catches a hook folding the percentage into a spell coefficient.
//! Shape three is an aura tick hook over a DBC periodic trigger that already energizes.
//! Shape four is a `[spells.X] damage` row re-dealing a child of `X`'s own DBC trigger program.
//! Shape five is an aura re-declaring an auto-attack modifier already provided by its own DBC effects or a `TriggerSpellWithValue` driver.
//!
//! # Scope
//!
//! Every finding is a CANDIDATE and the absence of findings proves nothing.
//! The check is static over the manifest plus DBC, so several duplication shapes stay invisible.
//!
//! - Imperative `mask_aura_dbc_effect` builder calls legitimately hand an effect to content.
//! - A hook applying the same percentage to a disjoint pet or guardian axis reads as a duplicate.
//! - A hook may consume the aura before dealing damage, so the live modifier is already inactive.
//! - An `[effects]` binding may name a spell-modifier effect the generic path never folds.
//! - A duplication living only in hook Rust produces no manifest evidence at all.
//!
//! `SCOPE_NOTE` renders that contract beside the findings, so no reader reads clean as absent.

use wowlab_engine_domain::dbc::{
    AuraSubtypeKind, SpellEffectKind, SpellEffectSemanticExt, live_damage_modifier,
};
use wowlab_engine_ports::{DataResolver, DynDataResolver, SpellId};
use wowlab_manifest_schema::{Manifest, ManifestAuraDef, ManifestDamageDef, ScalarRef};
use wowlab_types::sim::FastSet;

use super::{AuditCtx, AuditSink};

/// What the duplicate-fold check does and does not see; emitted with every non-empty result.
const SCOPE_NOTE: &str = "[duplicate-fold] scope: static over manifest + DBC only. Findings are CANDIDATES (confirm on combined_mult), and a clean spec is NOT proof of absence — imperative mask_aura_dbc_effect calls, disjoint pet/guardian axes, spell-modifier effect bindings, and duplications living only in hook Rust are all invisible to it.";

/// Aura fields that declare a damage multiplier on the caster's own spells.
///
/// `pet_damage_mult` is deliberately absent: a whole-pet multiplier is a different axis.
fn declared_damage_fields(aura: &ManifestAuraDef) -> impl Iterator<Item = &'static str> {
    [
        aura.damage_mult.is_some().then_some("damage_mult"),
        aura.damage_mult_stacking
            .is_some()
            .then_some("damage_mult_stacking"),
        aura.damage_percent_spells
            .is_some()
            .then_some("damage_percent_spells"),
        aura.damage_percent_spells_linear
            .is_some()
            .then_some("damage_percent_spells_linear"),
        aura.crit_chance_spells
            .is_some()
            .then_some("crit_chance_spells"),
        aura.crit_damage_spells
            .is_some()
            .then_some("crit_damage_spells"),
    ]
    .into_iter()
    .flatten()
}

pub(super) async fn check_duplicate_generic_folds(ctx: &mut AuditCtx<'_>) {
    let registered: FastSet<u32> = ctx.manifest.auras.values().map(|aura| aura.id).collect();

    let before = ctx.sink.warning_count();

    check_aura_self_folds(ctx).await;
    check_auto_attack_aura_self_folds(ctx).await;
    check_effect_bindings(ctx, &registered).await;
    check_periodic_energize_hooks(ctx).await;
    check_trigger_program_damage_rows(ctx).await;

    if ctx.sink.warning_count() > before {
        ctx.sink.warning(SCOPE_NOTE.to_string());
    }
}

/// Flags authored swing-speed and auto-attack damage fields already owned by the live-aura path.
///
/// A non-zero carrier is data-owned; a zero carrier requires a `TriggerSpellWithValue` driver.
async fn check_auto_attack_aura_self_folds(ctx: &mut AuditCtx<'_>) {
    let manifest = ctx.manifest;
    let resolver = ctx.resolver;
    let sink = &mut *ctx.sink;
    let auras = &manifest.auras;

    for (name, aura) in auras {
        let has_authored_field = has_authored_auto_attack_field(aura);

        if aura.id == 0 || !has_authored_field {
            continue;
        }

        let Ok(effects) = resolver.get_spell_effects(spell_id_of(aura.id)).await else {
            continue;
        };
        let talent_forwards_value = talent_forwards_value_to(manifest, resolver, aura.id).await;

        if let Some(field) = aura.attack_speed_per_stack.as_ref() {
            let forwarded = talent_forwards_value
                || scalar_ref_forwards_value_to(Some(field), resolver, aura.id).await;

            warn_auto_attack_field_folds(
                sink,
                &effects,
                AutoAttackFieldFold {
                    name,
                    aura_id: aura.id,
                    field: "attack_speed_per_stack",
                    subtypes: &[
                        AuraSubtypeKind::ModMeleeAutoAttackSpeedPercent,
                        AuraSubtypeKind::ModRangedAndMeleeAutoAttackSpeedPercent,
                    ],
                    forwarded,
                },
            );
        }

        if let Some(field) = aura.auto_attack_damage_per_stack.as_ref() {
            let forwarded = talent_forwards_value
                || scalar_ref_forwards_value_to(Some(field), resolver, aura.id).await;

            warn_auto_attack_field_folds(
                sink,
                &effects,
                AutoAttackFieldFold {
                    name,
                    aura_id: aura.id,
                    field: "auto_attack_damage_per_stack",
                    subtypes: &[AuraSubtypeKind::ModAutoAttackDamage],
                    forwarded,
                },
            );
        }
    }
}

fn has_authored_auto_attack_field(aura: &ManifestAuraDef) -> bool {
    aura.attack_speed_per_stack.is_some() || aura.auto_attack_damage_per_stack.is_some()
}

#[derive(Clone, Copy)]
struct AutoAttackFieldFold<'a> {
    name: &'a str,
    aura_id: u32,
    field: &'static str,
    subtypes: &'a [AuraSubtypeKind],
    forwarded: bool,
}

fn warn_auto_attack_field_folds(
    sink: &mut AuditSink,
    effects: &[wowlab_types::data::SpellEffect],
    fold: AutoAttackFieldFold<'_>,
) {
    for (position, effect) in effects.iter().enumerate() {
        if (effect.base_points.abs() > f64::EPSILON || fold.forwarded)
            && effect.aura_is_any(fold.subtypes)
        {
            warn_auto_attack_self_fold(
                sink,
                fold.name,
                fold.aura_id,
                fold.field,
                one_based_index(position),
                fold.forwarded && effect.base_points.abs() <= f64::EPSILON,
            );
        }
    }
}

fn warn_auto_attack_self_fold(
    sink: &mut AuditSink,
    name: &str,
    aura_id: u32,
    field: &str,
    effect_index: u8,
    forwarded: bool,
) {
    let ownership = if forwarded {
        "a TriggerSpellWithValue driver populates"
    } else {
        "DBC already provides"
    };

    sink.warning(format!(
        "[duplicate-fold] aura {name} ({aura_id}): {field} re-declares an auto-attack modifier {ownership} for the generic live-aura path at effect {effect_index}; delete the manifest row, or mask the DBC effect if content must own it",
    ));
}

async fn scalar_ref_forwards_value_to(
    scalar: Option<&ScalarRef>,
    resolver: &DynDataResolver<'_>,
    aura_id: u32,
) -> bool {
    let Some(ScalarRef::EffectRef {
        spell_id, effect, ..
    }) = scalar
    else {
        return false;
    };
    let Ok(effects) = resolver.get_spell_effects(spell_id_of(*spell_id)).await else {
        return false;
    };
    let driver_index = i32::from(*effect).saturating_sub(1);
    let Some(driver) = effects
        .iter()
        .find(|candidate| candidate.index == driver_index)
    else {
        return false;
    };

    driver.aura_is(AuraSubtypeKind::TriggerSpellWithValue)
        && u32::try_from(driver.trigger_spell).is_ok_and(|id| id == aura_id)
}

async fn talent_forwards_value_to(
    manifest: &Manifest,
    resolver: &DynDataResolver<'_>,
    aura_id: u32,
) -> bool {
    for &talent_id in manifest.talents.values() {
        let Ok(effects) = resolver.get_spell_effects(spell_id_of(talent_id)).await else {
            continue;
        };

        if effects.iter().any(|effect| {
            effect.aura_is(AuraSubtypeKind::TriggerSpellWithValue)
                && u32::try_from(effect.trigger_spell).is_ok_and(|id| id == aura_id)
        }) {
            return true;
        }
    }

    false
}

/// Flags a `[spells.X] damage` row that re-deals a child of `X`'s own DBC trigger program.
///
/// The generic trigger program already resolves that child's geometry and dispatches its damage.
// #t(fn: rust_async_loop_no_yield) an offline manifest audit over a bounded spell list, not a runtime task
async fn check_trigger_program_damage_rows(ctx: &mut AuditCtx<'_>) {
    let manifest = ctx.manifest;
    let resolver = ctx.resolver;
    let sink = &mut *ctx.sink;

    for (name, spell) in &manifest.spells {
        let Some(ManifestDamageDef::EffectRef {
            spell_id: payload, ..
        }) = spell.damage
        else {
            continue;
        };

        if spell.id == 0 || payload == spell.id {
            continue;
        }

        for (index, triggered) in trigger_program_children(resolver, spell.id).await {
            if triggered != payload {
                continue;
            }

            sink.warning(format!(
                "[duplicate-fold] spell {name} ({}): damage names {payload}, which effect {index} already triggers; the generic trigger program dispatches it too, so the payload lands twice",
                spell.id,
            ));
        }
    }
}

/// `(1-based effect index, triggered spell id)` for every trigger-program effect.
async fn trigger_program_children(resolver: &DynDataResolver<'_>, spell_id: u32) -> Vec<(u8, u32)> {
    let Ok(effects) = resolver.get_spell_effects(spell_id_of(spell_id)).await else {
        return Vec::new();
    };

    effects
        .iter()
        .enumerate()
        .filter(|(_, effect)| {
            effect.effect_is_any(&[
                SpellEffectKind::TriggerMissile,
                SpellEffectKind::TriggerSpell,
                SpellEffectKind::TriggerSpellWithValue,
                SpellEffectKind::TriggerSpell2,
            ])
        })
        .filter_map(|(position, effect)| {
            u32::try_from(effect.trigger_spell)
                .ok()
                .filter(|triggered| *triggered != 0)
                .map(|triggered| (one_based_index(position), triggered))
        })
        .collect()
}

/// Flags an aura tick hook whose resource grant the generic periodic-trigger path already makes.
///
/// A `Periodic Trigger Spell (23)` whose child energizes already runs generically.
///   A `tick_hook` on the same aura therefore grants that resource a second time.
async fn check_periodic_energize_hooks(ctx: &mut AuditCtx<'_>) {
    let manifest = ctx.manifest;
    let resolver = ctx.resolver;
    let sink = &mut *ctx.sink;

    for (name, aura) in &manifest.auras {
        if aura.id == 0 || aura.tick_hook.is_none() {
            continue;
        }

        for (index, triggered) in periodic_trigger_children(resolver, aura.id).await {
            if !spell_energizes(resolver, triggered).await {
                continue;
            }

            sink.warning(format!(
                "[duplicate-fold] aura {name} ({}): tick_hook duplicates the resource the generic periodic-trigger path already grants through effect {index} -> spell {triggered}; delete one half",
                aura.id,
            ));
        }
    }
}

/// `(1-based effect index, triggered spell id)` for every `Periodic Trigger Spell` effect.
async fn periodic_trigger_children(
    resolver: &DynDataResolver<'_>,
    spell_id: u32,
) -> Vec<(u8, u32)> {
    let Ok(effects) = resolver.get_spell_effects(spell_id_of(spell_id)).await else {
        return Vec::new();
    };

    effects
        .iter()
        .enumerate()
        .filter(|(_, effect)| effect.aura_is(AuraSubtypeKind::PeriodicTriggerSpell))
        .filter_map(|(position, effect)| {
            u32::try_from(effect.trigger_spell)
                .ok()
                .filter(|triggered| *triggered != 0)
                .map(|triggered| (one_based_index(position), triggered))
        })
        .collect()
}

async fn spell_energizes(resolver: &DynDataResolver<'_>, spell_id: u32) -> bool {
    let Ok(effects) = resolver.get_spell_effects(spell_id_of(spell_id)).await else {
        return false;
    };

    effects.iter().any(|effect| {
        effect.effect_is_any(&[
            SpellEffectKind::Energize,
            SpellEffectKind::EnergizePowerPercent,
        ])
    })
}

// #t(fn: rust_async_loop_no_yield) an offline manifest audit over a bounded aura list, not a runtime task
async fn check_aura_self_folds(ctx: &mut AuditCtx<'_>) {
    let manifest = ctx.manifest;
    let resolver = ctx.resolver;
    let sink = &mut *ctx.sink;

    for (name, aura) in &manifest.auras {
        let mut fields = declared_damage_fields(aura).peekable();

        if aura.id == 0 || fields.peek().is_none() {
            continue;
        }

        for index in folded_damage_effects(resolver, aura.id).await {
            for field in declared_damage_fields(aura) {
                sink.warning(format!(
                    "[duplicate-fold] aura {name} ({}): {field} re-declares a damage modifier the generic live-aura path already folds from effect {index}; delete the manifest row, or mask the DBC effect if content must own it",
                    aura.id,
                ));
            }
        }
    }
}

async fn check_effect_bindings(ctx: &mut AuditCtx<'_>, registered: &FastSet<u32>) {
    let manifest = ctx.manifest;
    let resolver = ctx.resolver;
    let sink = &mut *ctx.sink;

    for (name, binding) in &manifest.effects {
        if !registered.contains(&binding.spell_id) {
            continue;
        }

        if !folded_damage_effects(resolver, binding.spell_id)
            .await
            .contains(&binding.effect)
        {
            continue;
        }

        sink.warning(format!(
            "[duplicate-fold] effect binding {name} ({}, e{}) names a registered aura effect the generic live-aura path already folds as a damage modifier; a hook reading it applies the percentage a second time",
            binding.spell_id, binding.effect,
        ));
    }
}

/// 1-based indexes of the spell's effects the generic live-aura path folds as damage modifiers.
async fn folded_damage_effects(resolver: &DynDataResolver<'_>, spell_id: u32) -> Vec<u8> {
    let Ok(effects) = resolver.get_spell_effects(spell_id_of(spell_id)).await else {
        return Vec::new();
    };

    effects
        .iter()
        .enumerate()
        .filter(|(_, effect)| live_damage_modifier(effect.aura, effect.misc_value_0).is_some())
        .map(|(position, _)| one_based_index(position))
        .collect()
}

fn spell_id_of(spell_id: u32) -> SpellId {
    SpellId::new(wowlab_types::numeric::u32_to_i32_saturating(spell_id))
}

fn one_based_index(position: usize) -> u8 {
    u8::try_from(position.saturating_add(1)).unwrap_or(u8::MAX)
}