wowlab_engine_ports/

resolver.rs

use std::sync::Arc;

use wowlab_types::data::{
    ChallengeModeHealthFlat, ContentTuningFlat, ContentTuningXDifficultyFlat,
    ContentTuningXExpectedFlat, CreatureDifficultyFlat, CreatureFlat, ExpansionTraitTreeFlat,
    ExpectedStatFlat, ExpectedStatModFlat, ItemDamageScalingFlat, ItemDataFlat, ItemScalingData,
    PermanentEnchantFlat, PowerTypeFlat, SpecDataFlat, SpellDataFlat, SpellEffect, TraitTreeFlat,
    TraitTreeWithSelections,
};

use crate::types::SpellId;

/// Tokenizes a display name for profile lookup.
#[must_use]
pub fn tokenize_name(name: &str) -> String {
    let mut out = String::with_capacity(name.len());

    for c in name.trim().chars() {
        if c.is_ascii_alphanumeric() {
            out.extend(c.to_lowercase());
        } else if (c.is_whitespace() || c == '-' || c == '_') && !out.ends_with('_') {
            out.push('_');
        }
    }

    out.trim_end_matches('_').to_string()
}

/// Lightweight search result for spell lookups.
#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
pub struct SpellSearchResult {
    #[serde(alias = "id")]
    pub spell_id: SpellId,
    pub name: String,
}

/// One effect slot on an enchantment. `effect_type == 3` means trigger spell.
#[derive(Clone, Copy, Debug, Default, serde::Deserialize, serde::Serialize)]
pub struct EnchantmentEffect {
    pub effect_type: i32,
    pub effect_arg: i32,
    #[serde(default)]
    pub points_min: Option<f64>,
    #[serde(default)]
    pub scaling_points: Option<f64>,
}

/// Number of independent effect slots stored per enchantment row.
pub(crate) const ENCHANTMENT_EFFECTS: usize = 3;

/// Resolved enchantment row from `game.enchantments`.
#[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize)]
pub struct EnchantmentRow {
    pub id: i32,
    pub name: String,
    pub duration_ms: u32,
    pub effects: [EnchantmentEffect; ENCHANTMENT_EFFECTS],
    pub scaling_class: i32,
    pub item_level_min: i32,
    pub item_level_max: i32,
    /// Caps the player level used for scaled stat values (`MaxLevel`); 0 = uncapped.
    pub max_level: i32,
}

/// Exact permanent-enchant lookup coordinates used by `SimC` profile decoding.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PermanentEnchantQuery {
    pub tokenized_name: String,
    pub rank: i32,
    pub item_class: i32,
    pub inventory_type: i32,
    pub item_subclass: i32,
}

fn permanent_enchant_mask_allows(mask: i32, value: i32) -> bool {
    value <= 0
        || mask <= 0
        || u32::try_from(value)
            .ok()
            .and_then(|shift| 1_i32.checked_shl(shift))
            .is_some_and(|bit| mask & bit != 0)
}

/// Selects an entry using `SimC`'s verbose-name alias and item-mask rules.
#[must_use]
pub fn select_permanent_enchant(
    entries: &[PermanentEnchantFlat],
    query: &PermanentEnchantQuery,
) -> Option<PermanentEnchantFlat> {
    let canonical_name = entries
        .iter()
        .find(|entry| {
            entry.tokenized_name.starts_with("enchant_")
                && entry
                    .tokenized_name
                    .split_once("__")
                    .is_some_and(|(_, alias)| alias == query.tokenized_name)
        })
        .map_or(query.tokenized_name.as_str(), |entry| {
            entry.tokenized_name.as_str()
        });

    entries
        .iter()
        .find(|entry| {
            entry.tokenized_name == canonical_name
                && entry.rank == query.rank
                && entry.item_class == query.item_class
                && permanent_enchant_mask_allows(entry.inventory_type_mask, query.inventory_type)
                && permanent_enchant_mask_allows(entry.subclass_mask, query.item_subclass)
        })
        .cloned()
}

type BoxedCause = Box<dyn std::error::Error + Send + Sync + 'static>;

wowlab_engine_macros::define_error! {
/// Resolver failure with stable, situation-oriented construction and inspection APIs.
#[derive(Debug)]
pub struct ResolverError {
    #[source]
    kind: ResolverErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum ResolverErrorKind {
    #[error("spell {spell_id} not found")]
    SpellNotFound { spell_id: SpellId },

    #[error("spell effect not found: spell_id={spell_id}, effect_index={effect_index}")]
    SpellEffectNotFound { spell_id: SpellId, effect_index: u8 },

    #[error("item {item_id} not found")]
    ItemNotFound { item_id: i32 },

    #[error("trait tree for spec {spec_id} not found")]
    TraitTreeNotFound { spec_id: i32 },

    #[error("expansion trait tree {system:?} for expansion {expansion_id} not found")]
    ExpansionTraitTreeNotFound { expansion_id: i32, system: String },

    #[error("spec {spec_id} not found")]
    SpecNotFound { spec_id: i32 },

    #[error("rotation script {rotation_id} not found")]
    RotationScriptNotFound { rotation_id: String },

    #[error("expected stats not found for expansion {expansion_id}, lvl {lvl}")]
    ExpectedStatsNotFound { expansion_id: i32, lvl: i32 },

    #[error("creature {creature_id} not found")]
    CreatureNotFound { creature_id: i32 },

    #[error("content tuning {content_tuning_id} not found")]
    ContentTuningNotFound { content_tuning_id: i32 },

    #[error("expected stat mod {expected_stat_mod_id} not found")]
    ExpectedStatModNotFound { expected_stat_mod_id: i32 },

    #[error("challenge mode health not found for keystone level {keystone_level}")]
    ChallengeModeHealthNotFound { keystone_level: i32 },

    #[error("item_damage_scaling not found for weapon_type={weapon_type}, item_level={item_level}")]
    ItemDamageScalingNotFound {
        weapon_type: String,
        item_level: i32,
    },

    #[error("enchantment {enchantment_id} not found")]
    EnchantmentNotFound { enchantment_id: i32 },

    #[error("scaling data not configured for this resolver")]
    NoScalingData,

    #[error("resolver does not support {method}")]
    Unsupported { method: &'static str },

    #[error("trait decode error: {0}")]
    TraitDecode(#[source] wowlab_loadout::TraitError),

    #[error("filesystem error: {source}")]
    Filesystem {
        #[source]
        source: wowlab_fs::error::Error,
    },

    #[error("decode error in {op}")]
    Decode {
        op: &'static str,
        #[source]
        source: BoxedCause,
    },

    #[error("js bridge error in {method}: {message}")]
    JsBridge { method: String, message: String },

    #[error("backend error in {op}")]
    Backend {
        op: &'static str,
        #[source]
        source: BoxedCause,
    },

    #[error("environment variable error: {0}")]
    EnvVar(String),
}
}

impl ResolverError {
    #[must_use]
    pub fn spell_not_found(spell_id: SpellId) -> Self {
        Self {
            kind: ResolverErrorKind::SpellNotFound { spell_id },
        }
    }

    #[must_use]
    pub fn spell_effect_not_found(spell_id: SpellId, effect_index: u8) -> Self {
        Self {
            kind: ResolverErrorKind::SpellEffectNotFound {
                spell_id,
                effect_index,
            },
        }
    }

    #[must_use]
    pub fn item_not_found(item_id: i32) -> Self {
        Self {
            kind: ResolverErrorKind::ItemNotFound { item_id },
        }
    }

    #[must_use]
    pub fn trait_tree_not_found(spec_id: i32) -> Self {
        Self {
            kind: ResolverErrorKind::TraitTreeNotFound { spec_id },
        }
    }

    pub fn expansion_trait_tree_not_found(expansion_id: i32, system: impl Into<String>) -> Self {
        Self {
            kind: ResolverErrorKind::ExpansionTraitTreeNotFound {
                expansion_id,
                system: system.into(),
            },
        }
    }

    #[must_use]
    pub fn spec_not_found(spec_id: i32) -> Self {
        Self {
            kind: ResolverErrorKind::SpecNotFound { spec_id },
        }
    }

    pub fn rotation_script_not_found(rotation_id: impl Into<String>) -> Self {
        Self {
            kind: ResolverErrorKind::RotationScriptNotFound {
                rotation_id: rotation_id.into(),
            },
        }
    }

    #[must_use]
    pub fn expected_stats_not_found(expansion_id: i32, lvl: i32) -> Self {
        Self {
            kind: ResolverErrorKind::ExpectedStatsNotFound { expansion_id, lvl },
        }
    }

    #[must_use]
    pub fn creature_not_found(creature_id: i32) -> Self {
        Self {
            kind: ResolverErrorKind::CreatureNotFound { creature_id },
        }
    }

    #[must_use]
    pub fn content_tuning_not_found(content_tuning_id: i32) -> Self {
        Self {
            kind: ResolverErrorKind::ContentTuningNotFound { content_tuning_id },
        }
    }

    #[must_use]
    pub fn expected_stat_mod_not_found(expected_stat_mod_id: i32) -> Self {
        Self {
            kind: ResolverErrorKind::ExpectedStatModNotFound {
                expected_stat_mod_id,
            },
        }
    }

    #[must_use]
    pub fn challenge_mode_health_not_found(keystone_level: i32) -> Self {
        Self {
            kind: ResolverErrorKind::ChallengeModeHealthNotFound { keystone_level },
        }
    }

    pub fn item_damage_scaling_not_found(weapon_type: impl Into<String>, item_level: i32) -> Self {
        Self {
            kind: ResolverErrorKind::ItemDamageScalingNotFound {
                weapon_type: weapon_type.into(),
                item_level,
            },
        }
    }

    #[must_use]
    pub fn enchantment_not_found(enchantment_id: i32) -> Self {
        Self {
            kind: ResolverErrorKind::EnchantmentNotFound { enchantment_id },
        }
    }

    #[must_use]
    pub fn no_scaling_data() -> Self {
        Self {
            kind: ResolverErrorKind::NoScalingData,
        }
    }

    #[must_use]
    pub fn unsupported(method: &'static str) -> Self {
        Self {
            kind: ResolverErrorKind::Unsupported { method },
        }
    }

    #[must_use]
    pub fn filesystem(source: wowlab_fs::error::Error) -> Self {
        Self {
            kind: ResolverErrorKind::Filesystem { source },
        }
    }

    pub fn decode(
        op: &'static str,
        source: impl Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
    ) -> Self {
        Self {
            kind: ResolverErrorKind::Decode {
                op,
                source: source.into(),
            },
        }
    }

    pub fn js_bridge(method: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            kind: ResolverErrorKind::JsBridge {
                method: method.into(),
                message: message.into(),
            },
        }
    }

    pub fn backend(
        op: &'static str,
        source: impl Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
    ) -> Self {
        Self {
            kind: ResolverErrorKind::Backend {
                op,
                source: source.into(),
            },
        }
    }

    pub fn env_var(message: impl Into<String>) -> Self {
        Self {
            kind: ResolverErrorKind::EnvVar(message.into()),
        }
    }

    #[must_use]
    pub fn is_spell_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::SpellNotFound { .. })
    }

    #[must_use]
    pub fn is_item_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::ItemNotFound { .. })
    }

    #[must_use]
    pub fn is_trait_tree_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::TraitTreeNotFound { .. })
    }

    #[must_use]
    pub fn is_spec_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::SpecNotFound { .. })
    }

    #[must_use]
    pub fn is_rotation_script_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::RotationScriptNotFound { .. })
    }

    #[must_use]
    pub fn is_expected_stats_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::ExpectedStatsNotFound { .. })
    }

    #[must_use]
    pub fn is_creature_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::CreatureNotFound { .. })
    }

    #[must_use]
    pub fn is_content_tuning_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::ContentTuningNotFound { .. })
    }

    #[must_use]
    pub fn is_expected_stat_mod_not_found(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::ExpectedStatModNotFound { .. })
    }

    #[must_use]
    pub fn is_challenge_mode_health_not_found(&self) -> bool {
        matches!(
            self.kind,
            ResolverErrorKind::ChallengeModeHealthNotFound { .. }
        )
    }

    #[must_use]
    pub fn is_no_scaling_data(&self) -> bool {
        matches!(self.kind, ResolverErrorKind::NoScalingData)
    }

    #[must_use]
    pub fn spell_not_found_id(&self) -> Option<SpellId> {
        match self.kind {
            ResolverErrorKind::SpellNotFound { spell_id } => Some(spell_id),
            _ => None,
        }
    }

    #[must_use]
    pub fn spell_effect_not_found_coordinate(&self) -> Option<(SpellId, u8)> {
        match self.kind {
            ResolverErrorKind::SpellEffectNotFound {
                spell_id,
                effect_index,
            } => Some((spell_id, effect_index)),
            _ => None,
        }
    }
}

impl From<wowlab_loadout::TraitError> for ResolverError {
    fn from(source: wowlab_loadout::TraitError) -> Self {
        Self {
            kind: ResolverErrorKind::TraitDecode(source),
        }
    }
}

impl From<wowlab_fs::error::Error> for ResolverError {
    fn from(source: wowlab_fs::error::Error) -> Self {
        Self::filesystem(source)
    }
}

macro_rules! unsupported_default {
    ($method:ident; $($argument:expr),* $(,)?) => {{
        let _ = ($($argument),*);

        Err(ResolverError::unsupported(stringify!($method)))
    }};
}

/// Supertrait bound: `Sync` off-wasm (keeps `&self` `Send`), unconstrained on single-threaded wasm.
#[cfg(not(target_arch = "wasm32"))]
pub trait ResolverSyncBound: Sync {}
#[cfg(not(target_arch = "wasm32"))]
impl<T> ResolverSyncBound for T where T: Sync + ?Sized {}
/// Supertrait bound: unconstrained on wasm (single-threaded resolvers).
#[cfg(target_arch = "wasm32")]
pub trait ResolverSyncBound {}
#[cfg(target_arch = "wasm32")]
impl<T> ResolverSyncBound for T where T: ?Sized {}

/// Unified data resolver trait (`DynDataResolver` restores dyn polymorphism); method futures are `Send` but not `Sync`.
// wasm32 intentionally exposes !Send futures, hence the allowed async_fn_in_trait.
// docref:start data-resolution-trait-macros
#[cfg_attr(target_arch = "wasm32", allow(async_fn_in_trait))]
#[cfg_attr(not(target_arch = "wasm32"), trait_variant::make(Send))]
// #t(rust_expect_over_allow) proc-macro expansion makes this lint configuration-dependent
#[allow(
    unreachable_pub,
    reason = "the dynosaur macro exports DataResolver through the generated facade"
)]
#[dynosaur::dynosaur(pub DynDataResolver = dyn(box) DataResolver, bridge(dyn))]
pub trait DataResolver: ResolverSyncBound {
    // docref:end data-resolution-trait-macros
    async fn get_spell(&self, spell_id: SpellId) -> Result<SpellDataFlat, ResolverError>;

    fn get_spells(
        &self,
        spell_ids: &[SpellId],
    ) -> impl Future<Output = Result<Vec<SpellDataFlat>, ResolverError>> {
        async move {
            let mut result = Vec::with_capacity(spell_ids.len());

            for &id in spell_ids {
                result.push(self.get_spell(id).await?);
            }

            Ok(result)
        }
    }
    /// `effect_index` is 1-based (author-facing).
    async fn get_spell_effect(
        &self,
        spell_id: SpellId,
        effect_index: u8,
    ) -> Result<SpellEffect, ResolverError>;
    async fn get_spell_effects(&self, spell_id: SpellId)
    -> Result<Vec<SpellEffect>, ResolverError>;
    async fn get_item(&self, item_id: i32) -> Result<ItemDataFlat, ResolverError>;
    async fn get_scaling_data(&self) -> Result<Arc<ItemScalingData>, ResolverError>;

    async fn get_power_types(&self) -> Result<Vec<PowerTypeFlat>, ResolverError>;

    async fn get_spec(&self, spec_id: i32) -> Result<SpecDataFlat, ResolverError>;
    async fn get_trait_tree(&self, spec_id: i32) -> Result<TraitTreeFlat, ResolverError>;
    /// Fetch a class-agnostic expansion progression tree, such as Midnight's Omnium Folio.
    fn get_expansion_trait_tree(
        &self,
        expansion_id: i32,
        system: &str,
    ) -> impl Future<Output = Result<ExpansionTraitTreeFlat, ResolverError>> {
        async move { unsupported_default!(get_expansion_trait_tree; expansion_id, system) }
    }
    async fn get_rotation_script(&self, rotation_id: &str) -> Result<String, ResolverError>;

    /// Required for resolver parity: a backend with no override table returns `Ok(vec![])`.
    async fn get_spell_overrides(
        &self,
        spec_id: i32,
    ) -> Result<Vec<(SpellId, SpellId)>, ResolverError>;

    /// Every spell id assigned to the spec in `SpecializationSpells`; a backend with no table returns `Ok(vec![])`.
    async fn get_specialization_spells(&self, spec_id: i32) -> Result<Vec<SpellId>, ResolverError>;

    /// Every racial ability the race grants the class; a backend with no table returns `Ok(vec![])`.
    ///
    /// `race_id` is `ChrRaces.ID` and `class_id` is `ChrClasses.ID`.
    async fn get_racial_spells(
        &self,
        race_id: i32,
        class_id: i32,
    ) -> Result<Vec<SpellId>, ResolverError>;

    /// Required for resolver parity: return `ExpectedStatsNotFound` when a backend cannot source it.
    async fn get_expected_stats(
        &self,
        expansion_id: i32,
        lvl: i32,
    ) -> Result<ExpectedStatFlat, ResolverError>;

    /// Required for resolver parity: return `ItemDamageScalingNotFound` when a backend cannot source it.
    async fn get_item_damage_scaling(
        &self,
        item_level: i32,
        weapon_type: &str,
    ) -> Result<ItemDamageScalingFlat, ResolverError>;

    /// Defaults to `Unsupported`; a backend with no search index fails loud rather than returning empty.
    fn search_spells(
        &self,
        query: &str,
        limit: u32,
    ) -> impl Future<Output = Result<Vec<SpellSearchResult>, ResolverError>> {
        async move { unsupported_default!(search_spells; query, limit) }
    }

    /// Finds consumable items whose tokenized names contain `name_token`.
    fn find_consumable_items(
        &self,
        name_token: &str,
        subclass: i32,
    ) -> impl Future<Output = Result<Vec<ItemDataFlat>, ResolverError>> {
        async move { unsupported_default!(find_consumable_items; name_token, subclass) }
    }

    /// Required for resolver parity: return `EnchantmentNotFound` when a backend cannot source it.
    async fn get_enchantment(&self, enchantment_id: i32) -> Result<EnchantmentRow, ResolverError>;

    /// Resolves a named permanent enchant through the profession-derived `SimC` index.
    fn find_permanent_enchant(
        &self,
        query: &PermanentEnchantQuery,
    ) -> impl Future<Output = Result<Option<PermanentEnchantFlat>, ResolverError>> {
        async move { unsupported_default!(find_permanent_enchant; query) }
    }

    /// Creature identity row (`Creature` table) by NPC ID; defaults to `Unsupported` until a backend implements enemy resolution.
    fn get_creature(
        &self,
        creature_id: i32,
    ) -> impl Future<Output = Result<CreatureFlat, ResolverError>> {
        async move { unsupported_default!(get_creature; creature_id) }
    }

    /// Every `CreatureDifficulty` variant for a creature; defaults to `Unsupported` until a backend implements enemy resolution.
    fn get_creature_difficulties(
        &self,
        creature_id: i32,
    ) -> impl Future<Output = Result<Vec<CreatureDifficultyFlat>, ResolverError>> {
        async move { unsupported_default!(get_creature_difficulties; creature_id) }
    }

    /// `ContentTuning` row by ID; defaults to `Unsupported` until a backend implements enemy resolution.
    fn get_content_tuning(
        &self,
        content_tuning_id: i32,
    ) -> impl Future<Output = Result<ContentTuningFlat, ResolverError>> {
        async move { unsupported_default!(get_content_tuning; content_tuning_id) }
    }

    /// Every `ContentTuningXDifficulty` mapping for a content tuning; defaults to `Unsupported` until a backend implements enemy resolution.
    fn get_content_tuning_x_difficulty(
        &self,
        content_tuning_id: i32,
    ) -> impl Future<Output = Result<Vec<ContentTuningXDifficultyFlat>, ResolverError>> {
        async move { unsupported_default!(get_content_tuning_x_difficulty; content_tuning_id) }
    }

    /// Every `ContentTuningXExpected` mapping; row selection stays in the application layer.
    fn get_content_tuning_x_expected(
        &self,
        content_tuning_id: i32,
    ) -> impl Future<Output = Result<Vec<ContentTuningXExpectedFlat>, ResolverError>> {
        async move { unsupported_default!(get_content_tuning_x_expected; content_tuning_id) }
    }

    /// `ExpectedStatMod` multiplier row by ID.
    fn get_expected_stat_mod(
        &self,
        expected_stat_mod_id: i32,
    ) -> impl Future<Output = Result<ExpectedStatModFlat, ResolverError>> {
        async move { unsupported_default!(get_expected_stat_mod; expected_stat_mod_id) }
    }

    /// `ChallengeModeHealth` `GameTable` scalar by keystone level.
    fn get_challenge_mode_health(
        &self,
        keystone_level: i32,
    ) -> impl Future<Output = Result<ChallengeModeHealthFlat, ResolverError>> {
        async move { unsupported_default!(get_challenge_mode_health; keystone_level) }
    }

    /// Decode a loadout string against this spec's tree into a raw selected tree; talent-tree interpretation is the caller's job.
    fn decode_traits(
        &self,
        spec_id: i32,
        trait_string: &str,
    ) -> impl Future<Output = Result<TraitTreeWithSelections, ResolverError>> {
        async move {
            let tree = self.get_trait_tree(spec_id).await?;
            let decoded = wowlab_loadout::decode_trait_loadout(trait_string)?;

            Ok(wowlab_loadout::apply_decoded_traits(tree, &decoded))
        }
    }
}

#[cfg(test)]
mod tests {
    use std::error::Error as _;

    use googletest::prelude::*;
    use rstest::rstest;

    use super::*;

    #[cfg(not(target_arch = "wasm32"))]
    fn assert_send_sync<T>()
    where
        T: Send + Sync + ?Sized,
    {
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[gtest]
    fn native_dynamic_resolver_preserves_send_sync_contract() {
        assert_send_sync::<DynDataResolver<'static>>();
    }

    #[gtest]
    #[rstest]
    #[case::trim_and_lower("  Arcane Blast  ", "arcane_blast")]
    #[case::collapse_separators("arcane-- blast___rank 2", "arcane_blast_rank_2")]
    #[case::discard_punctuation("Nature's Swiftness!", "natures_swiftness")]
    #[case::empty(" --- ", "")]
    fn tokenize_name_normalizes_profile_lookup_keys(
        #[case] input: &str,
        #[case] expected: &str,
    ) -> Result<()> {
        verify_that!(tokenize_name(input), eq(expected))
    }

    #[gtest]
    fn permanent_enchant_lookup_applies_alias_rank_and_masks_exactly() -> Result<()> {
        let entries = vec![
            PermanentEnchantFlat {
                enchant_id: 7_966,
                rank: 1,
                item_class: 4,
                inventory_type_mask: 1 << 11,
                subclass_mask: 0x1f,
                tokenized_name: "enchant_ring__eyes_of_the_eagle".to_string(),
            },
            PermanentEnchantFlat {
                enchant_id: 7_967,
                rank: 2,
                item_class: 4,
                inventory_type_mask: 1 << 11,
                subclass_mask: 0x1f,
                tokenized_name: "enchant_ring__eyes_of_the_eagle".to_string(),
            },
        ];
        let query = PermanentEnchantQuery {
            tokenized_name: "eyes_of_the_eagle".to_string(),
            rank: 2,
            item_class: 4,
            inventory_type: 11,
            item_subclass: 0,
        };

        verify_that!(
            select_permanent_enchant(&entries, &query),
            some(matches_pattern!(PermanentEnchantFlat {
                enchant_id: eq(&7_967),
                ..
            }))
        )?;

        let wrong_rank = PermanentEnchantQuery {
            rank: 3,
            ..query.clone()
        };

        verify_that!(select_permanent_enchant(&entries, &wrong_rank), none())?;

        let wrong_inventory = PermanentEnchantQuery {
            inventory_type: 7,
            ..query.clone()
        };

        verify_that!(select_permanent_enchant(&entries, &wrong_inventory), none())?;

        let bit_31_entries = vec![PermanentEnchantFlat {
            inventory_type_mask: i32::MIN,
            ..entries[1].clone()
        }];

        let bit_31_inventory = PermanentEnchantQuery {
            inventory_type: 31,
            ..query
        };

        verify_that!(
            select_permanent_enchant(&bit_31_entries, &bit_31_inventory),
            some(matches_pattern!(PermanentEnchantFlat {
                enchant_id: eq(&7_967),
                ..
            }))
        )
    }

    #[gtest]
    fn backend_error_preserves_context_and_source() -> Result<()> {
        let error = ResolverError::backend(
            "fetch spell",
            std::io::Error::other("upstream request failed"),
        );

        verify_that!(error.to_string(), eq("backend error in fetch spell"))?;

        verify_that!(
            error
                .source()
                .and_then(std::error::Error::source)
                .map(ToString::to_string)
                .as_deref(),
            some(eq("upstream request failed"))
        )
    }

    #[gtest]
    fn trait_decode_error_preserves_typed_source() -> Result<()> {
        let error = wowlab_loadout::decode_trait_loadout("")
            .err()
            .or_fail()?
            .into();
        let error: ResolverError = error;

        verify_that!(
            error.to_string(),
            eq("trait decode error: Trait string too short")
        )?;
        let source = error
            .source()
            .and_then(std::error::Error::source)
            .and_then(|source| source.downcast_ref::<wowlab_loadout::TraitError>())
            .or_fail()?;

        verify_true!(source.is_too_short())
    }

    #[gtest]
    #[rstest]
    #[case::first_arm(0, Some(10.0))]
    #[case::mid_arm(3, Some(40.0))]
    #[case::last_valid_arm(6, Some(70.0))]
    #[case::above_range(7, None)]
    #[case::negative(-1, None)]
    fn item_damage_scaling_quality_arms(
        #[case] quality: i32,
        #[case] expected: Option<f64>,
    ) -> Result<()> {
        let row = ItemDamageScalingFlat {
            quality_0: 10.0,
            quality_1: 20.0,
            quality_2: 30.0,
            quality_3: 40.0,
            quality_4: 50.0,
            quality_5: 60.0,
            quality_6: 70.0,
            ..ItemDamageScalingFlat::default()
        };

        if let Some(v) = expected {
            verify_that!(row.quality(quality), some(near(v, 1e-9)))
        } else {
            verify_that!(row.quality(quality), none())
        }
    }
}