deepmerge 0.1.0

//! Policy system for configuring merge behavior
//!
//! Policies define default behaviors for different types during merging.
//! They can be overridden at struct, field, or type level.


/// Scalar merge action for primitive types and structs.
///
/// This enum determines the fundamental merge strategy for scalar values
/// and can be used to configure whether structs should be recursively merged
/// or replaced entirely.
///
/// # Examples
///
/// ```rust
/// use deepmerge::prelude::*;
///
/// // ScalarAction enum demonstrates merge strategies
/// let replace_action = ScalarAction::Replace;
/// let keep_action = ScalarAction::Keep;
/// let merge_action = ScalarAction::Merge;
///
/// // Simple demonstration with basic merge
/// #[derive(DeepMerge, Debug, PartialEq)]
/// struct Config {
///     name: String,
///     value: i32,
/// }
///
/// let mut config1 = Config { name: "app".to_string(), value: 10 };
/// let config2 = Config { name: "service".to_string(), value: 20 };
///
/// // Default merge behavior - recursively merge fields
/// config1.merge_with_policy(config2, &DefaultPolicy);
/// assert_eq!(config1.name, "service"); // String uses Replace by default
/// assert_eq!(config1.value, 20); // i32 uses Replace by default
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ScalarAction {
    /// Replace left with right (default for scalars)
    Replace,
    /// Keep left, ignore right
    Keep,
    /// Recursively merge (default for structs with `DeepMerge`)
    Merge,
}

/// Sequence merge behavior for collections like `Vec<T>`, arrays, and slices.
///
/// This enum defines how two sequences should be combined during merging.
/// Different strategies are useful for different use cases like configuration
/// merging, data aggregation, or collection operations.
///
/// # Examples
///
/// ```rust
/// use deepmerge::prelude::*;
///
/// let mut tags1 = vec!["rust", "web"];
/// let tags2 = vec!["api", "server"];
///
/// // Append: add right elements to the end (default)
/// let policy = ComposedPolicy::new(DefaultPolicy)
///     .with_sequence_merge(SequenceMerge::Append);
/// let mut test = tags1.clone();
/// test.merge_with_policy(tags2.clone(), &policy);
/// assert_eq!(test, vec!["rust", "web", "api", "server"]);
///
/// // Prepend: add right elements to the beginning
/// let policy = ComposedPolicy::new(DefaultPolicy)
///     .with_sequence_merge(SequenceMerge::Prepend);
/// let mut test = tags1.clone();
/// test.merge_with_policy(tags2.clone(), &policy);
/// assert_eq!(test, vec!["api", "server", "rust", "web"]);
///
/// // Extend: same as Append but optimized for performance
/// let policy = ComposedPolicy::new(DefaultPolicy)
///     .with_sequence_merge(SequenceMerge::Extend);
/// let mut test = tags1.clone();
/// test.merge_with_policy(tags2.clone(), &policy);
/// assert_eq!(test, vec!["rust", "web", "api", "server"]);
/// ```
///
/// # Note
/// 
/// `Union` and `Intersect` operations may require additional trait bounds
/// or special handling depending on the element type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum SequenceMerge {
    /// Append right to left (default)
    Append,
    /// Prepend right to left
    Prepend,
    /// Extend left with right (like `HashMap::extend`)
    Extend,
    /// Union of left and right (dedupe)
    Union,
    /// Intersection of left and right
    Intersect,
}

/// Option merge behavior for `Option<T>` types.
///
/// This enum defines how two `Option` values should be combined,
/// providing different strategies for handling `Some` and `None` values.
///
/// # Examples
///
/// ```rust
/// use deepmerge::prelude::*;
///
/// // Take: use right if Some, otherwise keep left (default)
/// let policy = ComposedPolicy::new(DefaultPolicy)
///     .with_option_merge(OptionMerge::Take);
/// let mut left = Some(42);
/// left.merge_with_policy(Some(100), &policy);
/// assert_eq!(left, Some(100));
/// 
/// let mut left = Some(42);
/// left.merge_with_policy(None, &policy);
/// assert_eq!(left, Some(42));
///
/// // Preserve: always keep left, ignore right
/// let policy = ComposedPolicy::new(DefaultPolicy)
///     .with_option_merge(OptionMerge::Preserve);
/// let mut left = Some(42);
/// left.merge_with_policy(Some(100), &policy);
/// assert_eq!(left, Some(42));
///
/// // OrLeft: use left if Some, otherwise use right
/// let policy = ComposedPolicy::new(DefaultPolicy)
///     .with_option_merge(OptionMerge::OrLeft);
/// let mut left: Option<i32> = None;
/// left.merge_with_policy(Some(100), &policy);
/// assert_eq!(left, Some(100));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum OptionMerge {
    /// Take right if Some, else keep left (default)
    Take,
    /// Always keep left, ignore right
    Preserve,
    /// Take left if Some, else take right
    OrLeft,
}

/// Number merge behavior for numeric types.
///
/// This enum defines different strategies for combining two numeric values,
/// supporting arithmetic operations and comparisons.
///
/// # Examples
///
/// ```rust
/// use deepmerge::prelude::*;
///
/// // Sum: add values together
/// #[derive(DeepMerge)]
/// #[merge(policy(number = sum))]
/// struct Config { score: i32 }
///
/// let mut config = Config { score: 10 };
/// config.merge_with_policy(Config { score: 25 }, &DefaultPolicy);
/// assert_eq!(config.score, 35);
///
/// // Max: keep the larger value  
/// #[derive(DeepMerge)]
/// #[merge(policy(number = max))]
/// struct MaxConfig { value: i32 }
///
/// let mut config = MaxConfig { value: 10 };
/// config.merge_with_policy(MaxConfig { value: 5 }, &DefaultPolicy);
/// assert_eq!(config.value, 10);
/// config.merge_with_policy(MaxConfig { value: 15 }, &DefaultPolicy);
/// assert_eq!(config.value, 15);
///
/// // Min: keep the smaller value
/// #[derive(DeepMerge)]
/// #[merge(policy(number = min))]
/// struct MinConfig { value: i32 }
///
/// let mut config = MinConfig { value: 10 };
/// config.merge_with_policy(MinConfig { value: 5 }, &DefaultPolicy);
/// assert_eq!(config.value, 5);
/// config.merge_with_policy(MinConfig { value: 15 }, &DefaultPolicy);
/// assert_eq!(config.value, 5);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum NumberMerge {
    /// Replace with right (default)
    Replace,
    /// Keep left, ignore right
    Keep,
    /// Take maximum of left and right
    Max,
    /// Take minimum of left and right
    Min,
    /// Sum left and right
    Sum,
}

/// Map merge behavior for `HashMap` and `BTreeMap` types.
///
/// This enum defines strategies for combining two maps, handling key conflicts
/// and nested value merging in different ways.
///
/// # Examples
///
/// ```rust
/// use std::collections::HashMap;
/// use deepmerge::prelude::*;
///
/// // Overlay: merge recursively, right wins on conflicts (default)
/// #[derive(DeepMerge)]
/// #[merge(policy(map = overlay))]
/// struct Config {
///     settings: HashMap<String, i32>,
/// }
///
/// let mut config = Config {
///     settings: [("a".to_string(), 1), ("b".to_string(), 2)].into(),
/// };
/// let update = Config {
///     settings: [("b".to_string(), 3), ("c".to_string(), 4)].into(),
/// };
/// config.merge_with_policy(update, &DefaultPolicy);
/// // Result: {"a": 1, "b": 3, "c": 4}
/// assert_eq!(config.settings.get("a"), Some(&1));
/// assert_eq!(config.settings.get("b"), Some(&3)); // right wins
/// assert_eq!(config.settings.get("c"), Some(&4));
///
/// // Left: keep only left entries
/// #[derive(DeepMerge)]
/// #[merge(policy(map = left))]
/// struct LeftConfig {
///     data: HashMap<String, i32>,
/// }
///
/// let mut config = LeftConfig {
///     data: [("a".to_string(), 1), ("b".to_string(), 2)].into(),
/// };
/// let update = LeftConfig {
///     data: [("b".to_string(), 3), ("c".to_string(), 4)].into(),
/// };
/// config.merge_with_policy(update, &DefaultPolicy);
/// // Result: {"a": 1, "b": 2} (unchanged)
/// assert_eq!(config.data.len(), 2);
/// assert_eq!(config.data.get("c"), None);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum MapMerge {
    /// Overlay right entries, merge values recursively (default)
    Overlay,
    /// Union of keys, prefer right on conflicts
    Union,
    /// Keep only left entries
    Left,
    /// Replace with right entries
    Right,
}

/// Boolean merge behavior for `bool` types.
///
/// This enum defines logical operations for combining two boolean values,
/// supporting different prioritization strategies.
///
/// # Examples
///
/// ```rust
/// use deepmerge::prelude::*;
///
/// // TrueWins: logical OR behavior
/// #[derive(DeepMerge)]
/// #[merge(policy(bool = true_wins))]
/// struct Config { enabled: bool }
///
/// let mut config = Config { enabled: false };
/// config.merge_with_policy(Config { enabled: true }, &DefaultPolicy);
/// assert_eq!(config.enabled, true);
///
/// let mut config = Config { enabled: true };
/// config.merge_with_policy(Config { enabled: false }, &DefaultPolicy);
/// assert_eq!(config.enabled, true); // true wins
///
/// // FalseWins: logical NOR behavior  
/// #[derive(DeepMerge)]
/// #[merge(policy(bool = false_wins))]
/// struct FalseConfig { active: bool }
///
/// let mut config = FalseConfig { active: true };
/// config.merge_with_policy(FalseConfig { active: false }, &DefaultPolicy);
/// assert_eq!(config.active, false); // false wins
///
/// // Keep: ignore right value
/// #[derive(DeepMerge)]
/// #[merge(policy(bool = keep))]
/// struct KeepConfig { flag: bool }
///
/// let mut config = KeepConfig { flag: true };
/// config.merge_with_policy(KeepConfig { flag: false }, &DefaultPolicy);
/// assert_eq!(config.flag, true); // kept original
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum BoolMerge {
    /// Replace with right (default)
    Replace,
    /// Keep left, ignore right
    Keep,
    /// Set to true if either is true
    TrueWins,
    /// Set to false if either is false
    FalseWins,
}

/// String merge behavior for `String` and `&str` types.
///
/// This enum defines different strategies for combining two string values,
/// including concatenation with optional separators.
///
/// # Examples
///
/// ```rust
/// use deepmerge::prelude::*;
///
/// // Concat: simple concatenation
/// #[derive(DeepMerge)]
/// #[merge(policy(string = concat))]
/// struct Config { text: String }
///
/// let mut config = Config { text: "Hello".to_string() };
/// config.merge_with_policy(Config { text: " World".to_string() }, &DefaultPolicy);
/// assert_eq!(config.text, "Hello World");
///
/// // ConcatWithSep: concatenation with separator
/// #[derive(DeepMerge)]
/// #[merge(policy(string = StringMerge::ConcatWithSep(", ")))]
/// struct ListConfig { items: String }
///
/// let mut config = ListConfig { items: "apple".to_string() };
/// config.merge_with_policy(ListConfig { items: "banana".to_string() }, &DefaultPolicy);
/// assert_eq!(config.items, "apple, banana");
///
/// // Keep: ignore right value
/// #[derive(DeepMerge)]
/// #[merge(policy(string = keep))]
/// struct KeepConfig { name: String }
///
/// let mut config = KeepConfig { name: "original".to_string() };
/// config.merge_with_policy(KeepConfig { name: "new".to_string() }, &DefaultPolicy);
/// assert_eq!(config.name, "original");
///
/// // Field-level override with path separator
/// #[derive(DeepMerge)]
/// struct PathConfig {
///     #[merge(string = StringMerge::ConcatWithSep(" -> "))]
///     path: String,
/// }
///
/// let mut config = PathConfig { path: "home".to_string() };
/// config.merge_with_policy(PathConfig { path: "user".to_string() }, &DefaultPolicy);
/// assert_eq!(config.path, "home -> user");
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum StringMerge {
    /// Replace left with right (default)
    Replace,
    /// Keep left, ignore right
    Keep,
    /// Concatenate right to left
    Concat,
    /// Concatenate with a separator
    ConcatWithSep(&'static str),
}

/// When to apply merge operations (guards/conditions).
///
/// This enum provides conditional logic for determining whether a merge
/// operation should be performed, enabling fine-grained control over when
/// values are actually merged.
///
/// # Examples
///
/// ```rust
/// use deepmerge::prelude::*;
///
/// // NonEmpty: only merge when right value is non-empty
/// #[derive(DeepMerge)]
/// #[merge(policy(condition = non_empty))]
/// struct Config { text: String }
/// 
/// let mut config = Config { text: "original".to_string() };
/// config.merge_with_policy(Config { text: "".to_string() }, &DefaultPolicy);
/// assert_eq!(config.text, "original"); // empty string ignored
/// 
/// config.merge_with_policy(Config { text: "new".to_string() }, &DefaultPolicy);
/// assert_eq!(config.text, "new"); // non-empty string merged
///
/// // NonDefault: only merge when right is not default value
/// #[derive(DeepMerge)]
/// #[merge(policy(condition = non_default))]
/// struct DefaultConfig { value: i32 }
/// 
/// let mut config = DefaultConfig { value: 42 };
/// config.merge_with_policy(DefaultConfig { value: 0 }, &DefaultPolicy); // 0 is default for i32
/// assert_eq!(config.value, 42); // default ignored
/// 
/// config.merge_with_policy(DefaultConfig { value: 99 }, &DefaultPolicy);
/// assert_eq!(config.value, 99); // non-default merged
///
/// // Some: only merge when Option is Some
/// #[derive(DeepMerge)]
/// #[merge(policy(condition = some))]
/// struct OptConfig { data: Option<i32> }
/// 
/// let mut config = OptConfig { data: Some(42) };
/// config.merge_with_policy(OptConfig { data: None }, &DefaultPolicy);
/// assert_eq!(config.data, Some(42)); // None ignored
/// 
/// config.merge_with_policy(OptConfig { data: Some(99) }, &DefaultPolicy);
/// assert_eq!(config.data, Some(99)); // Some merged
///
/// // Changed: only merge when values differ
/// #[derive(DeepMerge)]
/// #[merge(policy(condition = changed))]
/// struct ChangeConfig { count: i32 }
/// 
/// let mut config = ChangeConfig { count: 42 };
/// config.merge_with_policy(ChangeConfig { count: 42 }, &DefaultPolicy);
/// assert_eq!(config.count, 42); // same value ignored
/// 
/// config.merge_with_policy(ChangeConfig { count: 99 }, &DefaultPolicy);
/// assert_eq!(config.count, 99); // different value merged
/// ```
#[derive(Debug)]
pub enum Condition {
    /// Always apply (default)
    Always,
    /// Only when right is non-empty (for collections/strings)
    NonEmpty,
    /// Only when right is not the default value
    NonDefault,
    /// Only when right is Some (for Options)
    Some,
    /// Only when right differs from left
    Changed,
    /// Only when right differs from left according to a custom key extractor function
    /// This stores a function that can extract comparable keys from values
    /// The function signature should be fn(&T) -> K where K: `PartialEq`
    ChangedBy(fn()),
}

impl Clone for Condition {
    fn clone(&self) -> Self {
        match self {
            Condition::Always => Condition::Always,
            Condition::NonEmpty => Condition::NonEmpty,
            Condition::NonDefault => Condition::NonDefault,
            Condition::Some => Condition::Some,
            Condition::Changed => Condition::Changed,
            Condition::ChangedBy(f) => Condition::ChangedBy(*f),
        }
    }
}

impl PartialEq for Condition {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Condition::Always, Condition::Always)
            | (Condition::NonEmpty, Condition::NonEmpty)
            | (Condition::NonDefault, Condition::NonDefault)
            | (Condition::Some, Condition::Some)
            | (Condition::Changed, Condition::Changed) => true,
            (Condition::ChangedBy(f1), Condition::ChangedBy(f2)) => core::ptr::eq(std::ptr::from_ref::<fn()>(f1), std::ptr::from_ref::<fn()>(f2)),
            _ => false,
        }
    }
}

impl Eq for Condition {}

/// Policy trait defining default merge behaviors
pub trait Policy: Clone {
    /// Default action for scalars
    fn scalar_action(&self) -> ScalarAction {
        ScalarAction::Replace
    }

    /// Default action for structs that implement `DeepMerge`
    fn struct_action(&self) -> ScalarAction {
        ScalarAction::Merge
    }

    /// Default strategy for Options
    fn option_merge(&self) -> OptionMerge {
        OptionMerge::Take
    }

    /// Default strategy for sequences (Vec, arrays, etc.)
    fn sequence_merge(&self) -> SequenceMerge {
        SequenceMerge::Append
    }

    /// Whether to deduplicate sequences by default
    fn sequence_dedupe(&self) -> bool {
        false
    }

    /// Default strategy for maps (`HashMap`, `BTreeMap`, etc.)
    fn map_merge(&self) -> MapMerge {
        MapMerge::Overlay
    }

    /// Default strategy for numbers
    fn number_merge(&self) -> NumberMerge {
        NumberMerge::Replace
    }

    /// Default strategy for booleans
    fn bool_merge(&self) -> BoolMerge {
        BoolMerge::Replace
    }

    /// Default strategy for strings
    fn string_merge(&self) -> StringMerge {
        StringMerge::Replace
    }

    /// Default when condition
    fn when_condition(&self) -> Condition {
        Condition::Always
    }
}

/// Default policy with sensible defaults
#[derive(Debug, Clone, Copy, Default)]
pub struct DefaultPolicy;

impl Policy for DefaultPolicy {
    // Uses all the default implementations
}

/// Policy that always replaces (no merging)
#[derive(Debug, Clone, Copy, Default)]
pub struct StrictReplacePolicy;

impl Policy for StrictReplacePolicy {
    fn struct_action(&self) -> ScalarAction {
        ScalarAction::Replace
    }
    
    fn map_merge(&self) -> MapMerge {
        MapMerge::Right
    }
}

/// Policy that preserves left values
#[derive(Debug, Clone, Copy, Default)]
pub struct PreservePolicy;

impl Policy for PreservePolicy {
    fn scalar_action(&self) -> ScalarAction {
        ScalarAction::Keep
    }
    
    fn struct_action(&self) -> ScalarAction {
        ScalarAction::Keep
    }
    
    fn option_merge(&self) -> OptionMerge {
        OptionMerge::Preserve
    }
    
    fn sequence_merge(&self) -> SequenceMerge {
        SequenceMerge::Extend // Keep left, ignore right
    }
    
    fn map_merge(&self) -> MapMerge {
        MapMerge::Left
    }
    
    fn number_merge(&self) -> NumberMerge {
        NumberMerge::Keep // Preserve left values
    }
    
    fn bool_merge(&self) -> BoolMerge {
        BoolMerge::Keep
    }
    
    fn string_merge(&self) -> StringMerge {
        StringMerge::Keep
    }
    
    fn when_condition(&self) -> Condition {
        Condition::Always // But we'll ignore the merge anyway due to other settings
    }
}

/// Policy that deduplicates collections
#[derive(Debug, Clone, Copy, Default)]
pub struct DedupeCollectionsPolicy;

impl Policy for DedupeCollectionsPolicy {
    fn sequence_merge(&self) -> SequenceMerge {
        SequenceMerge::Union
    }
    
    fn sequence_dedupe(&self) -> bool {
        true
    }
}

/// Composed policy that overrides specific behaviors from a base policy
/// Used by the derive macro to implement field-level policy overrides
#[derive(Debug, Clone)]
pub struct ComposedPolicy<P: Policy> {
    /// The base policy to use when no override is specified
    pub base: P,
    /// Override for scalar merge behavior 
    pub scalar_action: Option<ScalarAction>,
    /// Override for struct merge behavior
    pub struct_action: Option<ScalarAction>,
    /// Override for Option<T> merge behavior
    pub option_merge: Option<OptionMerge>,
    /// Override for sequence (Vec, arrays) merge behavior
    pub sequence_merge: Option<SequenceMerge>,
    /// Whether to deduplicate sequences after merging
    pub sequence_dedupe: Option<bool>,
    /// Override for HashMap/BTreeMap merge behavior
    pub map_merge: Option<MapMerge>,
    /// Override for numeric type merge behavior
    pub number_merge: Option<NumberMerge>,
    /// Override for boolean merge behavior
    pub bool_merge: Option<BoolMerge>,
    /// Override for string merge behavior
    pub string_merge: Option<StringMerge>,
    /// Condition for when to apply the merge
    pub when_condition: Option<Condition>,
}

impl<P: Policy> ComposedPolicy<P> {
    /// Create a new composed policy with the given base policy and no overrides
    pub fn new(base: P) -> Self {
        Self {
            base,
            scalar_action: None,
            struct_action: None,
            option_merge: None,
            sequence_merge: None,
            sequence_dedupe: None,
            map_merge: None,
            number_merge: None,
            bool_merge: None,
            string_merge: None,
            when_condition: None,
        }
    }
    
    /// Set the scalar action for this policy
    #[must_use]
    pub fn with_scalar_action(mut self, action: ScalarAction) -> Self {
        self.scalar_action = Some(action);
        self
    }
    
    /// Set the struct action for this policy
    #[must_use]
    pub fn with_struct_action(mut self, action: ScalarAction) -> Self {
        self.struct_action = Some(action);
        self
    }
    
    /// Set the option merge strategy
    #[must_use]
    pub fn with_option_merge(mut self, merge: OptionMerge) -> Self {
        self.option_merge = Some(merge);
        self
    }
    
    /// Set the sequence merge strategy
    #[must_use]
    pub fn with_sequence_merge(mut self, merge: SequenceMerge) -> Self {
        self.sequence_merge = Some(merge);
        self
    }
    
    /// Set whether to deduplicate sequences
    #[must_use]
    pub fn with_sequence_dedupe(mut self, dedupe: bool) -> Self {
        self.sequence_dedupe = Some(dedupe);
        self
    }
    
    /// Set the map merge strategy
    #[must_use]
    pub fn with_map_merge(mut self, merge: MapMerge) -> Self {
        self.map_merge = Some(merge);
        self
    }
    
    /// Set the number merge strategy
    #[must_use]
    pub fn with_number_merge(mut self, merge: NumberMerge) -> Self {
        self.number_merge = Some(merge);
        self
    }
    
    /// Set the boolean merge strategy
    #[must_use]
    pub fn with_bool_merge(mut self, merge: BoolMerge) -> Self {
        self.bool_merge = Some(merge);
        self
    }
    
    /// Set the string merge strategy
    #[must_use]
    pub fn with_string_merge(mut self, merge: StringMerge) -> Self {
        self.string_merge = Some(merge);
        self
    }
    
    /// Set the when condition
    #[must_use]
    pub fn with_when_condition(mut self, condition: Condition) -> Self {
        self.when_condition = Some(condition);
        self
    }
}

impl<P: Policy> Policy for ComposedPolicy<P> {
    fn scalar_action(&self) -> ScalarAction {
        self.scalar_action.unwrap_or_else(|| self.base.scalar_action())
    }
    
    fn struct_action(&self) -> ScalarAction {
        self.struct_action.unwrap_or_else(|| self.base.struct_action())
    }
    
    fn option_merge(&self) -> OptionMerge {
        self.option_merge.unwrap_or_else(|| self.base.option_merge())
    }
    
    fn sequence_merge(&self) -> SequenceMerge {
        self.sequence_merge.unwrap_or_else(|| self.base.sequence_merge())
    }
    
    fn sequence_dedupe(&self) -> bool {
        self.sequence_dedupe.unwrap_or_else(|| self.base.sequence_dedupe())
    }
    
    fn map_merge(&self) -> MapMerge {
        self.map_merge.unwrap_or_else(|| self.base.map_merge())
    }
    
    fn number_merge(&self) -> NumberMerge {
        self.number_merge.unwrap_or_else(|| self.base.number_merge())
    }
    
    fn bool_merge(&self) -> BoolMerge {
        self.bool_merge.unwrap_or_else(|| self.base.bool_merge())
    }
    
    fn string_merge(&self) -> StringMerge {
        self.string_merge.clone().unwrap_or_else(|| self.base.string_merge())
    }
    
    fn when_condition(&self) -> Condition {
        self.when_condition.clone().unwrap_or_else(|| self.base.when_condition())
    }
}

/// Result of a merge operation indicating what changed
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MergeOutcome {
    /// Nothing was changed during the merge
    Unchanged,
    /// Something was changed during the merge
    Changed,
}

impl MergeOutcome {
    /// Check if the merge changed anything
    #[must_use]
    pub fn is_changed(&self) -> bool {
        matches!(self, MergeOutcome::Changed)
    }
    
    /// Check if the merge left everything unchanged
    #[must_use]
    pub fn is_unchanged(&self) -> bool {
        matches!(self, MergeOutcome::Unchanged)
    }
}

/// Merge trait with policy parameter
pub trait DeepMerge<P: Policy = DefaultPolicy>: Sized {
    /// Merge another instance into this one using the specified policy
    fn merge_with_policy(&mut self, other: Self, policy: &P);
    
    /// Merge another instance by reference using the specified policy
    /// This avoids moving the source when possible
    fn merge_ref(&mut self, src: &Self, policy: &P)
    where
        Self: Clone,
    {
        self.merge_with_policy(src.clone(), policy);
    }
    
    /// Merge and report whether anything changed
    fn merge_with_policy_reporting(&mut self, other: Self, policy: &P) -> MergeOutcome {
        // Default implementation just merges and reports changed
        // Individual types can override for more precise change detection
        self.merge_with_policy(other, policy);
        MergeOutcome::Changed
    }
    
    /// Merge by reference and report whether anything changed
    fn merge_ref_reporting(&mut self, src: &Self, policy: &P) -> MergeOutcome
    where
        Self: Clone,
    {
        self.merge_with_policy_reporting(src.clone(), policy)
    }
    
    /// Non-mutating merge using the specified policy
    #[must_use]
    fn merged_with_policy(mut self, other: Self, policy: &P) -> Self {
        self.merge_with_policy(other, policy);
        self
    }
}

/// Merge trait for merging from other types, including references
/// This allows merging from U into Self without requiring Clone on U
pub trait DeepMergeFrom<U, P: Policy = DefaultPolicy> {
    /// Merge from another type/reference using the specified policy
    fn merge_from_with_policy(&mut self, other: U, policy: &P);
    
    /// Merge from another type/reference and report whether anything changed
    fn merge_from_with_policy_reporting(&mut self, other: U, policy: &P) -> MergeOutcome {
        // Default implementation just merges and reports changed
        // Individual types can override for more precise change detection
        self.merge_from_with_policy(other, policy);
        MergeOutcome::Changed
    }
}

/// Extension trait for convenience methods when using `DefaultPolicy`
/// 
/// This trait provides shorthand methods for common merge operations
/// without requiring explicit policy arguments.
pub trait DeepMergeDefault: DeepMerge<DefaultPolicy> {
    /// Merge using the default policy
    fn merge(&mut self, other: Self) {
        self.merge_with_policy(other, &DefaultPolicy);
    }
    
    /// Merge by reference using the default policy
    fn merge_ref(&mut self, src: &Self)
    where
        Self: Clone,
    {
        DeepMerge::merge_ref(self, src, &DefaultPolicy);
    }
    
    /// Merge and report changes using the default policy
    fn merge_reporting(&mut self, other: Self) -> MergeOutcome {
        self.merge_with_policy_reporting(other, &DefaultPolicy)
    }
    
    /// Merge by reference and report changes using the default policy
    fn merge_ref_reporting(&mut self, src: &Self) -> MergeOutcome
    where
        Self: Clone,
    {
        DeepMerge::merge_ref_reporting(self, src, &DefaultPolicy)
    }
    
    /// Non-mutating merge using the default policy
    #[must_use]
    fn merged(self, other: Self) -> Self {
        self.merged_with_policy(other, &DefaultPolicy)
    }
}

// Blanket impl for all types that implement DeepMerge<DefaultPolicy>
impl<T: DeepMerge<DefaultPolicy>> DeepMergeDefault for T {}

/// Extension trait for `DeepMergeFrom` convenience methods when using `DefaultPolicy`
pub trait DeepMergeFromDefault<U>: DeepMergeFrom<U, DefaultPolicy> {
    /// Merge from another type/reference using the default policy
    fn merge_from(&mut self, other: U) {
        self.merge_from_with_policy(other, &DefaultPolicy);
    }
    
    /// Merge from another type/reference and report changes using the default policy
    fn merge_from_reporting(&mut self, other: U) -> MergeOutcome {
        self.merge_from_with_policy_reporting(other, &DefaultPolicy)
    }
}

// Blanket impl for all types that implement DeepMergeFrom<U, DefaultPolicy>
impl<T: DeepMergeFrom<U, DefaultPolicy>, U> DeepMergeFromDefault<U> for T {}

// Bridge implementation: DeepMerge -> DeepMergeFrom for owned types
impl<T: DeepMerge<P>, P: Policy> DeepMergeFrom<T, P> for T {
    fn merge_from_with_policy(&mut self, other: T, policy: &P) {
        self.merge_with_policy(other, policy);
    }
    
    fn merge_from_with_policy_reporting(&mut self, other: T, policy: &P) -> MergeOutcome {
        self.merge_with_policy_reporting(other, policy)
    }
}

// Bridge implementation: DeepMerge -> DeepMergeFrom for references (requires Clone)
impl<T: DeepMerge<P> + Clone, P: Policy> DeepMergeFrom<&T, P> for T {
    fn merge_from_with_policy(&mut self, other: &T, policy: &P) {
        self.merge_ref(other, policy);
    }
    
    fn merge_from_with_policy_reporting(&mut self, other: &T, policy: &P) -> MergeOutcome {
        self.merge_ref_reporting(other, policy)
    }
}