posthog_rs/

feature_flags.rs

use chrono::{DateTime, NaiveDate, Utc};
use regex::Regex;
use serde::{Deserialize, Serialize};
use sha1::{Digest, Sha1};
use std::collections::HashMap;
use std::fmt;
use std::sync::{Mutex, OnceLock};

/// Global cache for compiled regexes to avoid recompilation on every flag evaluation
static REGEX_CACHE: OnceLock<Mutex<HashMap<String, Option<Regex>>>> = OnceLock::new();

/// Salt used for rollout percentage hashing. Intentionally empty to match PostHog's
/// consistent hashing algorithm across all SDKs. This ensures the same user gets
/// the same rollout decision regardless of which SDK evaluates the flag.
const ROLLOUT_HASH_SALT: &str = "";

/// Salt used for multivariate variant selection. Uses "variant" to ensure consistent
/// variant assignment across all PostHog SDKs for the same user/flag combination.
const VARIANT_HASH_SALT: &str = "variant";

fn get_cached_regex(pattern: &str) -> Option<Regex> {
    let cache = REGEX_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
    let mut cache_guard = match cache.lock() {
        Ok(guard) => guard,
        Err(_) => {
            tracing::warn!(
                pattern,
                "Regex cache mutex poisoned, treating as cache miss"
            );
            return None;
        }
    };

    if let Some(cached) = cache_guard.get(pattern) {
        return cached.clone();
    }

    let compiled = Regex::new(pattern).ok();
    cache_guard.insert(pattern.to_string(), compiled.clone());
    compiled
}

/// The value of a feature flag evaluation.
///
/// Feature flags can return either a boolean (enabled/disabled) or a string
/// (for multivariate flags where users are assigned to different variants).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(untagged)]
pub enum FlagValue {
    /// Flag is either enabled (true) or disabled (false)
    Boolean(bool),
    /// Flag returns a specific variant key (e.g., "control", "test", "variant-a")
    String(String),
}

/// Error returned when a feature flag cannot be evaluated locally.
///
/// This typically occurs when:
/// - Required person/group properties are missing
/// - A cohort referenced by the flag is not in the local cache
/// - A dependent flag is not available locally
/// - An unknown operator is encountered
#[derive(Debug)]
pub struct InconclusiveMatchError {
    /// Human-readable description of why evaluation was inconclusive
    pub message: String,
}

impl InconclusiveMatchError {
    /// Create an inconclusive-match error with a human-readable message.
    pub fn new(message: &str) -> Self {
        Self {
            message: message.to_string(),
        }
    }
}

impl fmt::Display for InconclusiveMatchError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl std::error::Error for InconclusiveMatchError {}

impl Default for FlagValue {
    fn default() -> Self {
        FlagValue::Boolean(false)
    }
}

/// A feature flag definition from PostHog.
///
/// Contains all the information needed to evaluate whether a flag should be
/// enabled for a given user, including targeting rules and rollout percentages.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FeatureFlag {
    /// Unique identifier for the flag (e.g., "new-checkout-flow")
    pub key: String,
    /// Whether the flag is currently active. Inactive flags always return false.
    pub active: bool,
    /// Targeting rules and rollout configuration
    #[serde(default)]
    pub filters: FeatureFlagFilters,
}

/// Targeting rules and configuration for a feature flag.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct FeatureFlagFilters {
    /// List of condition groups (evaluated with OR logic between groups)
    #[serde(default)]
    pub groups: Vec<FeatureFlagCondition>,
    /// Multivariate configuration for A/B tests with multiple variants
    #[serde(default)]
    pub multivariate: Option<MultivariateFilter>,
    /// JSON payloads associated with flag variants
    #[serde(default)]
    pub payloads: HashMap<String, serde_json::Value>,
    /// Group type index this flag targets at the flag level. `None` means person
    /// targeting (or mixed, when individual conditions set their own).
    #[serde(default)]
    pub aggregation_group_type_index: Option<i32>,
    /// When `true`, local evaluation stops and returns a definitive disabled
    /// result as soon as a condition group's property filters match (or it has
    /// no property filters) but the rollout percentage excludes the user,
    /// instead of falling through to later condition groups. Defaults to
    /// `false`, which preserves the legacy fall-through behavior.
    #[serde(default)]
    pub early_exit: bool,
}

/// A single condition group within a feature flag's targeting rules.
///
/// All properties within a condition must match (AND logic), and the user
/// must fall within the rollout percentage to be included.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FeatureFlagCondition {
    /// Property filters that must all match (AND logic)
    #[serde(default)]
    pub properties: Vec<Property>,
    /// Percentage of matching users who should see this flag (0-100)
    pub rollout_percentage: Option<f64>,
    /// Specific variant to serve for this condition (for variant overrides)
    pub variant: Option<String>,
    /// Optional per-condition aggregation override used by mixed-targeting flags.
    /// When set, this condition targets the specified group type instead of the
    /// flag-level aggregation. `None` means person targeting under a mixed flag.
    #[serde(default)]
    pub aggregation_group_type_index: Option<i32>,
}

/// A property filter used in feature flag targeting.
///
/// Supports various operators for matching user properties against expected values.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Property {
    /// The property key to match (e.g., "email", "country", "$feature/other-flag")
    pub key: String,
    /// The value to compare against
    pub value: serde_json::Value,
    /// Comparison operator. Supported property operators include `"exact"`,
    /// `"is_not"`, `"icontains"`, `"not_icontains"`, `"regex"`,
    /// `"not_regex"`, `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"is_set"`,
    /// `"is_not_set"`, `"is_date_before"`, `"is_date_after"`, and the
    /// `"semver_*"` operators used by PostHog version targeting.
    #[serde(default = "default_operator")]
    pub operator: String,
    /// Property type. Use `Some("cohort")` for cohort membership checks; flag
    /// dependency checks use a property key that starts with `$feature/`.
    #[serde(rename = "type")]
    pub property_type: Option<String>,
}

fn default_operator() -> String {
    "exact".to_string()
}

/// Definition of a cohort for local evaluation
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CohortDefinition {
    /// Unique identifier for the cohort.
    pub id: String,
    /// Properties can be either:
    /// - A JSON object with "type" and "values" for complex property groups
    /// - Or a direct `Vec<Property>` for simple cases
    #[serde(default)]
    pub properties: serde_json::Value,
}

impl CohortDefinition {
    /// Create a new cohort definition with a simple property list.
    ///
    /// # Parameters
    ///
    /// - `id`: Cohort identifier.
    /// - `properties`: Property filters that define cohort membership.
    pub fn new(id: String, properties: Vec<Property>) -> Self {
        Self {
            id,
            properties: serde_json::to_value(properties).unwrap_or_default(),
        }
    }

    /// Parse the properties from the JSON structure.
    ///
    /// PostHog cohort properties come in format:
    /// `{"type": "AND", "values": [{"type": "property", "key": "...", "value": "...", "operator": "..."}]}`.
    pub fn parse_properties(&self) -> Vec<Property> {
        // If it's an array, treat it as direct property list
        if let Some(arr) = self.properties.as_array() {
            return arr
                .iter()
                .filter_map(|v| serde_json::from_value::<Property>(v.clone()).ok())
                .collect();
        }

        // If it's an object with "values" key, extract properties from there
        if let Some(obj) = self.properties.as_object() {
            if let Some(values) = obj.get("values") {
                if let Some(values_arr) = values.as_array() {
                    return values_arr
                        .iter()
                        .filter_map(|v| {
                            // Handle both direct property objects and nested property groups
                            if v.get("type").and_then(|t| t.as_str()) == Some("property") {
                                serde_json::from_value::<Property>(v.clone()).ok()
                            } else if let Some(inner_values) = v.get("values") {
                                // Recursively handle nested groups
                                inner_values.as_array().and_then(|arr| {
                                    arr.iter()
                                        .filter_map(|inner| {
                                            serde_json::from_value::<Property>(inner.clone()).ok()
                                        })
                                        .next()
                                })
                            } else {
                                None
                            }
                        })
                        .collect();
                }
            }
        }

        Vec::new()
    }
}

/// Context for evaluating properties that may depend on cohorts or other flags.
///
/// `groups`, `group_properties`, and `group_type_mapping` are used to resolve
/// group-targeted and mixed-targeting flags. A group condition (one whose
/// `aggregation_group_type_index` is set, either at the flag or condition level)
/// is bucketed on the group key and matched against group properties looked up
/// via the group type mapping.
pub struct EvaluationContext<'a> {
    /// Cohort definitions available to local evaluation, keyed by cohort ID.
    pub cohorts: &'a HashMap<String, CohortDefinition>,
    /// Feature flag definitions available to evaluate flag dependencies, keyed
    /// by flag key.
    pub flags: &'a HashMap<String, FeatureFlag>,
    /// Distinct ID used for person-targeted flag bucketing.
    pub distinct_id: &'a str,
    /// Group keys for group-targeted flags, keyed by group type.
    pub groups: &'a HashMap<String, String>,
    /// Group properties for group-targeted flags, keyed by group type and then
    /// property name.
    pub group_properties: &'a HashMap<String, HashMap<String, serde_json::Value>>,
    /// Mapping from PostHog group type index to group type name.
    pub group_type_mapping: &'a HashMap<String, String>,
}

/// Configuration for multivariate (A/B/n) feature flags.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct MultivariateFilter {
    /// List of variants with their rollout percentages
    pub variants: Vec<MultivariateVariant>,
}

/// A single variant in a multivariate feature flag.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MultivariateVariant {
    /// Unique key for this variant (e.g., "control", "test", "variant-a")
    pub key: String,
    /// Percentage of users who should see this variant (0-100)
    pub rollout_percentage: f64,
}

/// Response from the PostHog feature flags API.
///
/// Supports both the v2 API format (with detailed flag information) and the
/// legacy format (simple flag values and payloads).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum FeatureFlagsResponse {
    /// v2 API format from `/flags/?v=2` endpoint
    V2 {
        /// Map of flag keys to their detailed evaluation results
        flags: HashMap<String, FlagDetail>,
        /// Whether any errors occurred during flag computation
        #[serde(rename = "errorsWhileComputingFlags")]
        #[serde(default)]
        errors_while_computing_flags: bool,
        /// Whether the response was returned without evaluation because the
        /// project is over its feature-flag quota.
        #[serde(rename = "quotaLimited")]
        #[serde(default)]
        quota_limited: bool,
        /// Unique identifier for this evaluation request, propagated to
        /// `$feature_flag_called` events as `$feature_flag_request_id`
        /// for experiment exposure tracking.
        #[serde(rename = "requestId")]
        #[serde(default)]
        request_id: Option<String>,
    },
    /// Legacy format from older decide endpoint
    Legacy {
        /// Map of flag keys to their values
        #[serde(rename = "featureFlags")]
        feature_flags: HashMap<String, FlagValue>,
        /// Map of flag keys to their JSON payloads
        #[serde(rename = "featureFlagPayloads")]
        #[serde(default)]
        feature_flag_payloads: HashMap<String, serde_json::Value>,
        /// Any errors that occurred during evaluation
        #[serde(default)]
        errors: Option<Vec<String>>,
    },
}

impl FeatureFlagsResponse {
    /// Convert the response to normalized flag values and payloads.
    ///
    /// # Returns
    ///
    /// A tuple of `(feature_flags, feature_flag_payloads)`, each keyed by flag
    /// key.
    pub fn normalize(
        self,
    ) -> (
        HashMap<String, FlagValue>,
        HashMap<String, serde_json::Value>,
    ) {
        match self {
            FeatureFlagsResponse::V2 { flags, .. } => {
                let mut feature_flags = HashMap::new();
                let mut payloads = HashMap::new();

                for (key, detail) in flags {
                    if detail.enabled {
                        if let Some(variant) = detail.variant {
                            feature_flags.insert(key.clone(), FlagValue::String(variant));
                        } else {
                            feature_flags.insert(key.clone(), FlagValue::Boolean(true));
                        }
                    } else {
                        feature_flags.insert(key.clone(), FlagValue::Boolean(false));
                    }

                    if let Some(metadata) = detail.metadata {
                        if let Some(payload) = metadata.payload {
                            payloads.insert(key, payload);
                        }
                    }
                }

                (feature_flags, payloads)
            }
            FeatureFlagsResponse::Legacy {
                feature_flags,
                feature_flag_payloads,
                ..
            } => (feature_flags, feature_flag_payloads),
        }
    }
}

/// Detailed information about a feature flag evaluation result.
///
/// Returned by the `/flags/?v=2` endpoint with extended information about why a
/// flag evaluated to a particular value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlagDetail {
    /// The feature flag key
    pub key: String,
    /// Whether the flag is enabled for this user
    pub enabled: bool,
    /// The variant key if this is a multivariate flag
    pub variant: Option<String>,
    /// Reason explaining why the flag evaluated to this value
    #[serde(default)]
    pub reason: Option<FlagReason>,
    /// Additional metadata about the flag
    #[serde(default)]
    pub metadata: Option<FlagMetadata>,
}

/// Explains why a feature flag evaluated to a particular value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlagReason {
    /// Reason code (e.g., "condition_match", "out_of_rollout_bound")
    pub code: String,
    /// Index of the condition that matched (if applicable)
    #[serde(default)]
    pub condition_index: Option<usize>,
    /// Human-readable description of the reason
    #[serde(default)]
    pub description: Option<String>,
}

/// Metadata about a feature flag from the PostHog server.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlagMetadata {
    /// Unique identifier for this flag
    pub id: u64,
    /// Version number of the flag definition
    pub version: u32,
    /// Optional description of what this flag controls
    pub description: Option<String>,
    /// Optional JSON payload associated with the flag
    pub payload: Option<serde_json::Value>,
}

const LONG_SCALE: f64 = 0xFFFFFFFFFFFFFFFu64 as f64; // Must be exactly 15 F's to match Python SDK

/// Compute a deterministic hash value for feature flag bucketing.
///
/// Uses SHA-1 to generate a consistent hash in the range [0, 1) for the given
/// key, distinct_id, and salt combination. This ensures users get consistent
/// flag values across requests.
pub fn hash_key(key: &str, distinct_id: &str, salt: &str) -> f64 {
    let hash_key = format!("{key}.{distinct_id}{salt}");
    let mut hasher = Sha1::new();
    hasher.update(hash_key.as_bytes());
    let result = hasher.finalize();
    let hex_str = format!("{result:x}");
    let hash_val = u64::from_str_radix(&hex_str[..15], 16).unwrap_or(0);
    hash_val as f64 / LONG_SCALE
}

/// Determine which variant a user should see for a multivariate flag.
///
/// Uses consistent hashing to assign users to variants based on their
/// rollout percentages. Returns `None` if the flag has no variants or
/// the user doesn't fall into any variant bucket.
pub fn get_matching_variant(flag: &FeatureFlag, distinct_id: &str) -> Option<String> {
    let hash_value = hash_key(&flag.key, distinct_id, VARIANT_HASH_SALT);
    let variants = flag.filters.multivariate.as_ref()?.variants.as_slice();

    let mut value_min = 0.0;
    for variant in variants {
        let value_max = value_min + variant.rollout_percentage / 100.0;
        if hash_value >= value_min && hash_value < value_max {
            return Some(variant.key.clone());
        }
        value_min = value_max;
    }
    None
}

/// Result of resolving a condition's effective bucketing + properties.
enum ConditionTarget<'a> {
    /// Use these for bucketing and property matching.
    Use {
        bucketing: String,
        properties: &'a HashMap<String, serde_json::Value>,
    },
    /// Skip this condition (group type unknown or required group not passed in).
    Skip,
    /// Required group properties not provided — try other conditions, surface
    /// inconclusive if nothing else matches.
    Inconclusive,
}

/// Resolve effective bucketing id and properties for a single condition based on
/// the (possibly per-condition) aggregation group type index. Pure-person flags
/// fall through with `distinct_id` and `person_properties`. Group conditions
/// (either flag-level or per-condition aggregation) require the corresponding
/// group key and group properties to be present.
fn resolve_condition_target<'a>(
    condition: &FeatureFlagCondition,
    flag_aggregation: Option<i32>,
    distinct_id: &str,
    person_properties: &'a HashMap<String, serde_json::Value>,
    groups: &HashMap<String, String>,
    group_properties: &'a HashMap<String, HashMap<String, serde_json::Value>>,
    group_type_mapping: &HashMap<String, String>,
) -> ConditionTarget<'a> {
    // Per-condition aggregation falls back to the flag-level value when absent.
    // The two together drive whether this condition is person- or group-targeted.
    let effective_aggregation = condition.aggregation_group_type_index.or(flag_aggregation);

    match effective_aggregation {
        None => ConditionTarget::Use {
            bucketing: distinct_id.to_string(),
            properties: person_properties,
        },
        Some(idx) => {
            let key = idx.to_string();
            let Some(group_type) = group_type_mapping.get(&key) else {
                return ConditionTarget::Skip;
            };
            let Some(group_key) = groups.get(group_type) else {
                return ConditionTarget::Skip;
            };
            let Some(props) = group_properties.get(group_type) else {
                return ConditionTarget::Inconclusive;
            };
            ConditionTarget::Use {
                bucketing: group_key.clone(),
                properties: props,
            }
        }
    }
}

/// Evaluate a feature flag definition against person and optional group
/// context.
///
/// # Parameters
///
/// - `flag`: Feature flag definition to evaluate.
/// - `distinct_id`: Distinct ID used for person bucketing.
/// - `person_properties`: Person properties available to release conditions.
/// - `groups`: Group keys for group-targeted flags, keyed by group type.
/// - `group_properties`: Group properties for group-targeted flags.
/// - `group_type_mapping`: Mapping from PostHog group type index to group type
///   name.
///
/// # Returns
///
/// The matched flag value: `Boolean(false)` for inactive or unmatched flags,
/// `Boolean(true)` for matched boolean flags, or `String(variant)` for matched
/// multivariate flags.
///
/// # Errors
///
/// Returns [`InconclusiveMatchError`] when required properties are missing or an
/// operator cannot be evaluated locally.
#[must_use = "feature flag evaluation result should be used"]
#[allow(clippy::too_many_arguments)]
pub fn match_feature_flag(
    flag: &FeatureFlag,
    distinct_id: &str,
    person_properties: &HashMap<String, serde_json::Value>,
    groups: &HashMap<String, String>,
    group_properties: &HashMap<String, HashMap<String, serde_json::Value>>,
    group_type_mapping: &HashMap<String, String>,
) -> Result<FlagValue, InconclusiveMatchError> {
    if !flag.active {
        return Ok(FlagValue::Boolean(false));
    }

    let conditions = &flag.filters.groups;
    let flag_aggregation = flag.filters.aggregation_group_type_index;

    // Sort conditions to evaluate variant overrides first
    let mut sorted_conditions = conditions.clone();
    sorted_conditions.sort_by_key(|c| if c.variant.is_some() { 0 } else { 1 });

    let mut is_inconclusive = false;

    for condition in sorted_conditions {
        let (effective_bucketing, effective_properties) = match resolve_condition_target(
            &condition,
            flag_aggregation,
            distinct_id,
            person_properties,
            groups,
            group_properties,
            group_type_mapping,
        ) {
            ConditionTarget::Use {
                bucketing,
                properties,
            } => (bucketing, properties),
            ConditionTarget::Skip => continue,
            ConditionTarget::Inconclusive => {
                is_inconclusive = true;
                continue;
            }
        };

        match is_condition_match(flag, &effective_bucketing, &condition, effective_properties) {
            Ok(ConditionMatch::Match) => {
                if let Some(variant_override) = &condition.variant {
                    // Check if variant is valid
                    if let Some(ref multivariate) = flag.filters.multivariate {
                        let valid_variants: Vec<String> = multivariate
                            .variants
                            .iter()
                            .map(|v| v.key.clone())
                            .collect();

                        if valid_variants.contains(variant_override) {
                            return Ok(FlagValue::String(variant_override.clone()));
                        }
                    }
                }

                // Try to get matching variant or return true
                if let Some(variant) = get_matching_variant(flag, &effective_bucketing) {
                    return Ok(FlagValue::String(variant));
                }
                return Ok(FlagValue::Boolean(true));
            }
            Ok(ConditionMatch::OutOfRolloutBound) => {
                // The user's properties matched this group but the rollout
                // excluded them. With early_exit enabled the flag is
                // definitively disabled; otherwise fall through to later groups.
                // Only short-circuit when no prior group was inconclusive — an
                // inconclusive result means we can't evaluate locally and must
                // fall back to the server, so it takes priority over early_exit.
                if flag.filters.early_exit && !is_inconclusive {
                    return Ok(FlagValue::Boolean(false));
                }
            }
            Ok(ConditionMatch::NoMatch) => continue,
            Err(_) => {
                is_inconclusive = true;
            }
        }
    }

    if is_inconclusive {
        return Err(InconclusiveMatchError::new(
            "Can't determine if feature flag is enabled or not with given properties",
        ));
    }

    Ok(FlagValue::Boolean(false))
}

/// Outcome of evaluating a single condition group, mirroring the PostHog Rust
/// evaluation engine's tri-state so the local loop can distinguish a
/// property-filter miss (always fall through) from a rollout exclusion (which
/// can short-circuit when `early_exit` is enabled).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ConditionMatch {
    /// Property filters matched (or there were none) and the rollout included
    /// the user — the flag matches.
    Match,
    /// A property filter did not match — always continue to the next group.
    NoMatch,
    /// Property filters matched (or there were none) but the rollout excluded
    /// the user.
    OutOfRolloutBound,
}

fn is_condition_match(
    flag: &FeatureFlag,
    bucketing_id: &str,
    condition: &FeatureFlagCondition,
    properties: &HashMap<String, serde_json::Value>,
) -> Result<ConditionMatch, InconclusiveMatchError> {
    // Check properties first
    for prop in &condition.properties {
        if !match_property(prop, properties)? {
            return Ok(ConditionMatch::NoMatch);
        }
    }

    // If all properties match (or no properties), check rollout percentage
    if let Some(rollout_percentage) = condition.rollout_percentage {
        let hash_value = hash_key(&flag.key, bucketing_id, ROLLOUT_HASH_SALT);
        if hash_value > (rollout_percentage / 100.0) {
            return Ok(ConditionMatch::OutOfRolloutBound);
        }
    }

    Ok(ConditionMatch::Match)
}

/// Match a feature flag with full context (cohorts, other flags).
///
/// This version supports cohort membership checks and flag dependency checks.
/// `person_properties` carries person-level property values; group-level
/// properties are looked up from `ctx.group_properties` when a condition (or
/// the flag itself) targets a group via `aggregation_group_type_index`.
///
/// # Errors
///
/// Returns [`InconclusiveMatchError`] when local evaluation cannot determine a
/// result with the provided context.
#[must_use = "feature flag evaluation result should be used"]
pub fn match_feature_flag_with_context(
    flag: &FeatureFlag,
    person_properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<FlagValue, InconclusiveMatchError> {
    if !flag.active {
        return Ok(FlagValue::Boolean(false));
    }

    let conditions = &flag.filters.groups;
    let flag_aggregation = flag.filters.aggregation_group_type_index;

    // Sort conditions to evaluate variant overrides first
    let mut sorted_conditions = conditions.clone();
    sorted_conditions.sort_by_key(|c| if c.variant.is_some() { 0 } else { 1 });

    let mut is_inconclusive = false;

    for condition in sorted_conditions {
        let (effective_bucketing, effective_properties) = match resolve_condition_target(
            &condition,
            flag_aggregation,
            ctx.distinct_id,
            person_properties,
            ctx.groups,
            ctx.group_properties,
            ctx.group_type_mapping,
        ) {
            ConditionTarget::Use {
                bucketing,
                properties,
            } => (bucketing, properties),
            ConditionTarget::Skip => continue,
            ConditionTarget::Inconclusive => {
                is_inconclusive = true;
                continue;
            }
        };

        match is_condition_match_with_context(
            flag,
            &effective_bucketing,
            &condition,
            effective_properties,
            ctx,
        ) {
            Ok(ConditionMatch::Match) => {
                if let Some(variant_override) = &condition.variant {
                    // Check if variant is valid
                    if let Some(ref multivariate) = flag.filters.multivariate {
                        let valid_variants: Vec<String> = multivariate
                            .variants
                            .iter()
                            .map(|v| v.key.clone())
                            .collect();

                        if valid_variants.contains(variant_override) {
                            return Ok(FlagValue::String(variant_override.clone()));
                        }
                    }
                }

                // Try to get matching variant or return true
                if let Some(variant) = get_matching_variant(flag, &effective_bucketing) {
                    return Ok(FlagValue::String(variant));
                }
                return Ok(FlagValue::Boolean(true));
            }
            Ok(ConditionMatch::OutOfRolloutBound) => {
                // The user's properties matched this group but the rollout
                // excluded them. With early_exit enabled the flag is
                // definitively disabled; otherwise fall through to later groups.
                // Only short-circuit when no prior group was inconclusive — an
                // inconclusive result means we can't evaluate locally and must
                // fall back to the server, so it takes priority over early_exit.
                if flag.filters.early_exit && !is_inconclusive {
                    return Ok(FlagValue::Boolean(false));
                }
            }
            Ok(ConditionMatch::NoMatch) => continue,
            Err(_) => {
                is_inconclusive = true;
            }
        }
    }

    if is_inconclusive {
        return Err(InconclusiveMatchError::new(
            "Can't determine if feature flag is enabled or not with given properties",
        ));
    }

    Ok(FlagValue::Boolean(false))
}

fn is_condition_match_with_context(
    flag: &FeatureFlag,
    bucketing_id: &str,
    condition: &FeatureFlagCondition,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<ConditionMatch, InconclusiveMatchError> {
    // Check properties first (using context-aware matching for cohorts/flag dependencies)
    for prop in &condition.properties {
        if !match_property_with_context(prop, properties, ctx)? {
            return Ok(ConditionMatch::NoMatch);
        }
    }

    // If all properties match (or no properties), check rollout percentage
    if let Some(rollout_percentage) = condition.rollout_percentage {
        let hash_value = hash_key(&flag.key, bucketing_id, ROLLOUT_HASH_SALT);
        if hash_value > (rollout_percentage / 100.0) {
            return Ok(ConditionMatch::OutOfRolloutBound);
        }
    }

    Ok(ConditionMatch::Match)
}

/// Match a property with additional context for cohorts and flag dependencies.
///
/// Use this when evaluating local feature flag conditions that can reference
/// cohort membership (`type = "cohort"`) or another feature flag via
/// `$feature/<flag-key>`.
///
/// # Errors
///
/// Returns [`InconclusiveMatchError`] when the property, cohort, or dependent
/// flag cannot be evaluated from the supplied context.
pub fn match_property_with_context(
    property: &Property,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<bool, InconclusiveMatchError> {
    // Check if this is a cohort membership check
    if property.property_type.as_deref() == Some("cohort") {
        return match_cohort_property(property, properties, ctx);
    }

    // Check if this is a flag dependency check
    if property.key.starts_with("$feature/") {
        return match_flag_dependency_property(property, ctx);
    }

    // Fall back to regular property matching
    match_property(property, properties)
}

/// Evaluate cohort membership
fn match_cohort_property(
    property: &Property,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<bool, InconclusiveMatchError> {
    let cohort_id = property
        .value
        .as_str()
        .ok_or_else(|| InconclusiveMatchError::new("Cohort ID must be a string"))?;

    let cohort = ctx.cohorts.get(cohort_id).ok_or_else(|| {
        InconclusiveMatchError::new(&format!("Cohort '{}' not found in local cache", cohort_id))
    })?;

    // Parse and evaluate all cohort properties against the user's properties
    let cohort_properties = cohort.parse_properties();
    let mut is_in_cohort = true;
    for cohort_prop in &cohort_properties {
        match match_property(cohort_prop, properties) {
            Ok(true) => continue,
            Ok(false) => {
                is_in_cohort = false;
                break;
            }
            Err(e) => {
                // If we can't evaluate a cohort property, the cohort membership is inconclusive
                return Err(InconclusiveMatchError::new(&format!(
                    "Cannot evaluate cohort '{}' property '{}': {}",
                    cohort_id, cohort_prop.key, e.message
                )));
            }
        }
    }

    // Handle "in" vs "not_in" operator
    Ok(match property.operator.as_str() {
        "in" => is_in_cohort,
        "not_in" => !is_in_cohort,
        op => {
            return Err(InconclusiveMatchError::new(&format!(
                "Unknown cohort operator: {}",
                op
            )));
        }
    })
}

/// Evaluate flag dependency
fn match_flag_dependency_property(
    property: &Property,
    ctx: &EvaluationContext,
) -> Result<bool, InconclusiveMatchError> {
    // Extract flag key from "$feature/flag-key"
    let flag_key = property
        .key
        .strip_prefix("$feature/")
        .ok_or_else(|| InconclusiveMatchError::new("Invalid flag dependency format"))?;

    let flag = ctx.flags.get(flag_key).ok_or_else(|| {
        InconclusiveMatchError::new(&format!("Flag '{}' not found in local cache", flag_key))
    })?;

    // Evaluate the dependent flag for this user (with empty properties to avoid recursion issues).
    // Group context flows through from the outer ctx so dependent group/mixed flags can resolve.
    let empty_props = HashMap::new();
    let flag_value = match_feature_flag(
        flag,
        ctx.distinct_id,
        &empty_props,
        ctx.groups,
        ctx.group_properties,
        ctx.group_type_mapping,
    )?;

    // Compare the flag value with the expected value
    let expected = &property.value;

    let matches = match (&flag_value, expected) {
        (FlagValue::Boolean(b), serde_json::Value::Bool(expected_b)) => b == expected_b,
        (FlagValue::String(s), serde_json::Value::String(expected_s)) => {
            s.eq_ignore_ascii_case(expected_s)
        }
        (FlagValue::Boolean(true), serde_json::Value::String(s)) => {
            // Flag is enabled (boolean true) but we're checking for a specific variant
            // This should not match
            s.is_empty() || s == "true"
        }
        (FlagValue::Boolean(false), serde_json::Value::String(s)) => s.is_empty() || s == "false",
        (FlagValue::String(s), serde_json::Value::Bool(true)) => {
            // Flag returns a variant string, checking for "enabled" (any variant is enabled)
            !s.is_empty()
        }
        (FlagValue::String(_), serde_json::Value::Bool(false)) => false,
        _ => false,
    };

    // Handle different operators
    Ok(match property.operator.as_str() {
        "exact" => matches,
        "is_not" => !matches,
        op => {
            return Err(InconclusiveMatchError::new(&format!(
                "Unknown flag dependency operator: {}",
                op
            )));
        }
    })
}

/// Parse a relative date string like "-7d", "-24h", "-2w", "-3m", "-1y"
/// Returns the DateTime<Utc> that the relative date represents
fn parse_relative_date(value: &str) -> Option<DateTime<Utc>> {
    let value = value.trim();
    // Need at least 3 chars: "-", digit(s), and unit (e.g., "-7d")
    if value.len() < 3 || !value.starts_with('-') {
        return None;
    }

    let (num_str, unit) = value[1..].split_at(value.len() - 2);
    let num: i64 = num_str.parse().ok()?;

    let duration = match unit {
        "h" => chrono::Duration::hours(num),
        "d" => chrono::Duration::days(num),
        "w" => chrono::Duration::weeks(num),
        "m" => chrono::Duration::days(num * 30), // Approximate month as 30 days
        "y" => chrono::Duration::days(num * 365), // Approximate year as 365 days
        _ => return None,
    };

    Some(Utc::now() - duration)
}

/// Parse a date value from a string (ISO date, ISO datetime, or relative date)
fn parse_date_value(value: &serde_json::Value) -> Option<DateTime<Utc>> {
    let date_str = value.as_str()?;

    // Try relative date first (e.g., "-7d")
    if date_str.starts_with('-') && date_str.len() > 1 {
        if let Some(dt) = parse_relative_date(date_str) {
            return Some(dt);
        }
    }

    // Try ISO datetime with timezone (e.g., "2024-06-15T10:30:00Z")
    if let Ok(dt) = DateTime::parse_from_rfc3339(date_str) {
        return Some(dt.with_timezone(&Utc));
    }

    // Try ISO date only (e.g., "2024-06-15")
    if let Ok(date) = NaiveDate::parse_from_str(date_str, "%Y-%m-%d") {
        return Some(
            date.and_hms_opt(0, 0, 0)
                .expect("midnight is always valid")
                .and_utc(),
        );
    }

    None
}

/// A parsed semantic version as (major, minor, patch)
type SemverTuple = (u64, u64, u64);

/// Parse a semantic version string into a (major, minor, patch) tuple.
///
/// Rules:
/// 1. Strip leading/trailing whitespace
/// 2. Strip `v` or `V` prefix (e.g., "v1.2.3" → "1.2.3")
/// 3. Strip pre-release and build metadata suffixes (split on `-` or `+`, take first part)
/// 4. Split on `.` and parse first 3 components as integers
/// 5. Default missing components to 0 (e.g., "1.2" → (1, 2, 0), "1" → (1, 0, 0))
/// 6. Ignore extra components beyond the third (e.g., "1.2.3.4" → (1, 2, 3))
/// 7. Return None for invalid input (empty string, non-numeric parts, leading dot,
///    or numeric components with leading zeros per semver 2.0.0 §2)
fn parse_semver(value: &str) -> Option<SemverTuple> {
    let value = value.trim();
    if value.is_empty() {
        return None;
    }

    // Strip v/V prefix
    let value = value
        .strip_prefix('v')
        .or_else(|| value.strip_prefix('V'))
        .unwrap_or(value);
    if value.is_empty() {
        return None;
    }

    // Strip pre-release/build metadata (everything after - or +)
    let value = value.split(['-', '+']).next().unwrap_or(value);
    if value.is_empty() {
        return None;
    }

    // Leading dot is invalid
    if value.starts_with('.') {
        return None;
    }

    // Split on dots and parse components
    let parts: Vec<&str> = value.split('.').collect();
    if parts.is_empty() {
        return None;
    }

    let major = parse_semver_numeric(parts.first()?)?;
    let minor = parts.get(1).map_or(Some(0), |s| parse_semver_numeric(s))?;
    let patch = parts.get(2).map_or(Some(0), |s| parse_semver_numeric(s))?;

    Some((major, minor, patch))
}

/// Parse a single semver numeric identifier.
///
/// Per semver 2.0.0 §2, numeric identifiers MUST NOT include leading zeros, so
/// "07" and "001" are rejected while the literal "0" remains valid.
fn parse_semver_numeric(part: &str) -> Option<u64> {
    if part.is_empty() || !part.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    if part.len() > 1 && part.starts_with('0') {
        return None;
    }
    part.parse().ok()
}

/// Parse a wildcard pattern like "1.*" or "1.2.*" and return (lower_bound, upper_bound)
/// Returns None if the pattern is invalid
fn parse_semver_wildcard(pattern: &str) -> Option<(SemverTuple, SemverTuple)> {
    let pattern = pattern.trim();
    if pattern.is_empty() {
        return None;
    }

    // Strip v/V prefix
    let pattern = pattern
        .strip_prefix('v')
        .or_else(|| pattern.strip_prefix('V'))
        .unwrap_or(pattern);
    if pattern.is_empty() {
        return None;
    }

    let parts: Vec<&str> = pattern.split('.').collect();

    match parts.as_slice() {
        // "X.*" pattern
        [major_str, "*"] => {
            let major = parse_semver_numeric(major_str)?;
            Some(((major, 0, 0), (major + 1, 0, 0)))
        }
        // "X.Y.*" pattern
        [major_str, minor_str, "*"] => {
            let major = parse_semver_numeric(major_str)?;
            let minor = parse_semver_numeric(minor_str)?;
            Some(((major, minor, 0), (major, minor + 1, 0)))
        }
        _ => None,
    }
}

/// Compute bounds for tilde range: ~X.Y.Z means >=X.Y.Z and <X.(Y+1).0
fn compute_tilde_bounds(version: SemverTuple) -> (SemverTuple, SemverTuple) {
    let (major, minor, patch) = version;
    ((major, minor, patch), (major, minor + 1, 0))
}

/// Compute bounds for caret range per semver spec:
/// - ^X.Y.Z where X > 0: >=X.Y.Z <(X+1).0.0
/// - ^0.Y.Z where Y > 0: >=0.Y.Z <0.(Y+1).0
/// - ^0.0.Z: >=0.0.Z <0.0.(Z+1)
fn compute_caret_bounds(version: SemverTuple) -> (SemverTuple, SemverTuple) {
    let (major, minor, patch) = version;
    if major > 0 {
        ((major, minor, patch), (major + 1, 0, 0))
    } else if minor > 0 {
        ((0, minor, patch), (0, minor + 1, 0))
    } else {
        ((0, 0, patch), (0, 0, patch + 1))
    }
}

fn parse_target_semver(
    target_value: &serde_json::Value,
) -> Result<SemverTuple, InconclusiveMatchError> {
    let target_str = value_to_string(target_value);
    parse_semver(&target_str).ok_or_else(|| {
        InconclusiveMatchError::new(&format!(
            "Unable to parse target semver value: {:?}",
            target_value
        ))
    })
}

fn match_property(
    property: &Property,
    properties: &HashMap<String, serde_json::Value>,
) -> Result<bool, InconclusiveMatchError> {
    let value = match properties.get(&property.key) {
        Some(v) => v,
        None => {
            // Handle is_not_set operator
            if property.operator == "is_not_set" {
                return Ok(true);
            }
            // Handle is_set operator
            if property.operator == "is_set" {
                return Ok(false);
            }
            // For other operators, missing property is inconclusive
            return Err(InconclusiveMatchError::new(&format!(
                "Property '{}' not found in provided properties",
                property.key
            )));
        }
    };

    let parse_property_semver = || {
        let prop_str = value_to_string(value);
        parse_semver(&prop_str).ok_or_else(|| {
            InconclusiveMatchError::new(&format!(
                "Unable to parse property semver value for '{}': {:?}",
                property.key, value
            ))
        })
    };
    let parse_semver_operands = || {
        Ok((
            parse_property_semver()?,
            parse_target_semver(&property.value)?,
        ))
    };

    Ok(match property.operator.as_str() {
        "exact" => {
            if property.value.is_array() {
                if let Some(arr) = property.value.as_array() {
                    for val in arr {
                        if compare_values(val, value) {
                            return Ok(true);
                        }
                    }
                    return Ok(false);
                }
            }
            compare_values(&property.value, value)
        }
        "is_not" => {
            if property.value.is_array() {
                if let Some(arr) = property.value.as_array() {
                    for val in arr {
                        if compare_values(val, value) {
                            return Ok(false);
                        }
                    }
                    return Ok(true);
                }
            }
            !compare_values(&property.value, value)
        }
        "is_set" => true,      // We already know the property exists
        "is_not_set" => false, // We already know the property exists
        "icontains" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            prop_str.to_lowercase().contains(&search_str.to_lowercase())
        }
        "not_icontains" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            !prop_str.to_lowercase().contains(&search_str.to_lowercase())
        }
        "regex" => {
            let prop_str = value_to_string(value);
            let regex_str = value_to_string(&property.value);
            get_cached_regex(&regex_str)
                .map(|re| re.is_match(&prop_str))
                .unwrap_or(false)
        }
        "not_regex" => {
            let prop_str = value_to_string(value);
            let regex_str = value_to_string(&property.value);
            get_cached_regex(&regex_str)
                .map(|re| !re.is_match(&prop_str))
                .unwrap_or(true)
        }
        "gt" | "gte" | "lt" | "lte" => compare_numeric(&property.operator, &property.value, value),
        "is_date_before" | "is_date_after" => {
            let target_date = parse_date_value(&property.value).ok_or_else(|| {
                InconclusiveMatchError::new(&format!(
                    "Unable to parse target date value: {:?}",
                    property.value
                ))
            })?;

            let prop_date = parse_date_value(value).ok_or_else(|| {
                InconclusiveMatchError::new(&format!(
                    "Unable to parse property date value for '{}': {:?}",
                    property.key, value
                ))
            })?;

            if property.operator == "is_date_before" {
                prop_date < target_date
            } else {
                prop_date > target_date
            }
        }
        // Semver comparison operators
        "semver_eq" | "semver_neq" | "semver_gt" | "semver_gte" | "semver_lt" | "semver_lte" => {
            let (prop_version, target_version) = parse_semver_operands()?;

            match property.operator.as_str() {
                "semver_eq" => prop_version == target_version,
                "semver_neq" => prop_version != target_version,
                "semver_gt" => prop_version > target_version,
                "semver_gte" => prop_version >= target_version,
                "semver_lt" => prop_version < target_version,
                "semver_lte" => prop_version <= target_version,
                _ => unreachable!(),
            }
        }
        "semver_tilde" => {
            let (prop_version, target_version) = parse_semver_operands()?;
            let (lower, upper) = compute_tilde_bounds(target_version);
            prop_version >= lower && prop_version < upper
        }
        "semver_caret" => {
            let (prop_version, target_version) = parse_semver_operands()?;
            let (lower, upper) = compute_caret_bounds(target_version);
            prop_version >= lower && prop_version < upper
        }
        "semver_wildcard" => {
            let prop_version = parse_property_semver()?;
            let target_str = value_to_string(&property.value);

            let (lower, upper) = parse_semver_wildcard(&target_str).ok_or_else(|| {
                InconclusiveMatchError::new(&format!(
                    "Unable to parse target semver wildcard pattern: {:?}",
                    property.value
                ))
            })?;

            prop_version >= lower && prop_version < upper
        }
        unknown => {
            return Err(InconclusiveMatchError::new(&format!(
                "Unknown operator: {}",
                unknown
            )));
        }
    })
}

fn compare_values(a: &serde_json::Value, b: &serde_json::Value) -> bool {
    // Case-insensitive string comparison
    if let (Some(a_str), Some(b_str)) = (a.as_str(), b.as_str()) {
        return a_str.eq_ignore_ascii_case(b_str);
    }

    // Direct comparison for other types
    a == b
}

fn value_to_string(value: &serde_json::Value) -> String {
    match value {
        serde_json::Value::String(s) => s.clone(),
        serde_json::Value::Number(n) => n.to_string(),
        serde_json::Value::Bool(b) => b.to_string(),
        _ => value.to_string(),
    }
}

fn compare_numeric(
    operator: &str,
    property_value: &serde_json::Value,
    value: &serde_json::Value,
) -> bool {
    let prop_num = match property_value {
        serde_json::Value::Number(n) => n.as_f64(),
        serde_json::Value::String(s) => s.parse::<f64>().ok(),
        _ => None,
    };

    let val_num = match value {
        serde_json::Value::Number(n) => n.as_f64(),
        serde_json::Value::String(s) => s.parse::<f64>().ok(),
        _ => None,
    };

    if let (Some(prop), Some(val)) = (prop_num, val_num) {
        match operator {
            "gt" => val > prop,
            "gte" => val >= prop,
            "lt" => val < prop,
            "lte" => val <= prop,
            _ => false,
        }
    } else {
        // Fall back to string comparison
        let prop_str = value_to_string(property_value);
        let val_str = value_to_string(value);
        match operator {
            "gt" => val_str > prop_str,
            "gte" => val_str >= prop_str,
            "lt" => val_str < prop_str,
            "lte" => val_str <= prop_str,
            _ => false,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    /// Test salt constant to avoid CodeQL warnings about empty cryptographic values
    const TEST_SALT: &str = "test-salt";

    #[test]
    fn test_hash_key() {
        let hash = hash_key("test-flag", "user-123", TEST_SALT);
        assert!((0.0..=1.0).contains(&hash));

        // Same inputs should produce same hash
        let hash2 = hash_key("test-flag", "user-123", TEST_SALT);
        assert_eq!(hash, hash2);

        // Different inputs should produce different hash
        let hash3 = hash_key("test-flag", "user-456", TEST_SALT);
        assert_ne!(hash, hash3);
    }

    #[test]
    fn test_simple_flag_match() {
        let flag = FeatureFlag {
            key: "test-flag".to_string(),
            active: true,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(100.0),
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(true));
    }

    #[test]
    fn test_property_matching() {
        let prop = Property {
            key: "country".to_string(),
            value: json!("US"),
            operator: "exact".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));

        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_multivariate_variants() {
        let flag = FeatureFlag {
            key: "test-flag".to_string(),
            active: true,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(100.0),
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: Some(MultivariateFilter {
                    variants: vec![
                        MultivariateVariant {
                            key: "control".to_string(),
                            rollout_percentage: 50.0,
                        },
                        MultivariateVariant {
                            key: "test".to_string(),
                            rollout_percentage: 50.0,
                        },
                    ],
                }),
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();

        match result {
            FlagValue::String(variant) => {
                assert!(variant == "control" || variant == "test");
            }
            _ => panic!("Expected string variant"),
        }
    }

    #[test]
    fn test_inactive_flag() {
        let flag = FeatureFlag {
            key: "inactive-flag".to_string(),
            active: false,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(100.0),
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(false));
    }

    #[test]
    fn test_rollout_percentage() {
        let flag = FeatureFlag {
            key: "rollout-flag".to_string(),
            active: true,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(30.0), // 30% rollout
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();

        // Test with multiple users to ensure distribution
        let mut enabled_count = 0;
        for i in 0..1000 {
            let result = match_feature_flag(
                &flag,
                &format!("user-{}", i),
                &properties,
                &HashMap::new(),
                &HashMap::new(),
                &HashMap::new(),
            )
            .unwrap();
            if result == FlagValue::Boolean(true) {
                enabled_count += 1;
            }
        }

        // Should be roughly 30% enabled (allow for some variance)
        assert!(enabled_count > 250 && enabled_count < 350);
    }

    #[test]
    fn test_regex_operator() {
        let prop = Property {
            key: "email".to_string(),
            value: json!(".*@company\\.com$"),
            operator: "regex".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("email".to_string(), json!("user@company.com"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("email".to_string(), json!("user@example.com"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_icontains_operator() {
        let prop = Property {
            key: "name".to_string(),
            value: json!("ADMIN"),
            operator: "icontains".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("name".to_string(), json!("admin_user"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("regular_user"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_numeric_operators() {
        // Greater than
        let prop_gt = Property {
            key: "age".to_string(),
            value: json!(18),
            operator: "gt".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("age".to_string(), json!(25));
        assert!(match_property(&prop_gt, &properties).unwrap());

        properties.insert("age".to_string(), json!(15));
        assert!(!match_property(&prop_gt, &properties).unwrap());

        // Less than or equal
        let prop_lte = Property {
            key: "score".to_string(),
            value: json!(100),
            operator: "lte".to_string(),
            property_type: None,
        };

        properties.insert("score".to_string(), json!(100));
        assert!(match_property(&prop_lte, &properties).unwrap());

        properties.insert("score".to_string(), json!(101));
        assert!(!match_property(&prop_lte, &properties).unwrap());
    }

    #[test]
    fn test_is_set_operator() {
        let prop = Property {
            key: "email".to_string(),
            value: json!(true),
            operator: "is_set".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("email".to_string(), json!("test@example.com"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.remove("email");
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_not_set_operator() {
        let prop = Property {
            key: "phone".to_string(),
            value: json!(true),
            operator: "is_not_set".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("phone".to_string(), json!("+1234567890"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_empty_groups() {
        let flag = FeatureFlag {
            key: "empty-groups".to_string(),
            active: true,
            filters: FeatureFlagFilters {
                groups: vec![],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(false));
    }

    #[test]
    fn test_hash_scale_constant() {
        // Verify the constant is exactly 15 F's (not 16)
        assert_eq!(LONG_SCALE, 0xFFFFFFFFFFFFFFFu64 as f64);
        assert_ne!(LONG_SCALE, 0xFFFFFFFFFFFFFFFFu64 as f64);
    }

    // ==================== Tests for missing operators ====================

    #[test]
    fn test_unknown_operator_returns_inconclusive_error() {
        let prop = Property {
            key: "status".to_string(),
            value: json!("active"),
            operator: "unknown_operator".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("status".to_string(), json!("active"));

        let result = match_property(&prop, &properties);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(err.message.contains("unknown_operator"));
    }

    #[test]
    fn test_is_date_before_with_relative_date() {
        let prop = Property {
            key: "signup_date".to_string(),
            value: json!("-7d"), // 7 days ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Date 10 days ago should be before -7d
        let ten_days_ago = chrono::Utc::now() - chrono::Duration::days(10);
        properties.insert(
            "signup_date".to_string(),
            json!(ten_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // Date 3 days ago should NOT be before -7d
        let three_days_ago = chrono::Utc::now() - chrono::Duration::days(3);
        properties.insert(
            "signup_date".to_string(),
            json!(three_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_after_with_relative_date() {
        let prop = Property {
            key: "last_seen".to_string(),
            value: json!("-30d"), // 30 days ago
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Date 10 days ago should be after -30d
        let ten_days_ago = chrono::Utc::now() - chrono::Duration::days(10);
        properties.insert(
            "last_seen".to_string(),
            json!(ten_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // Date 60 days ago should NOT be after -30d
        let sixty_days_ago = chrono::Utc::now() - chrono::Duration::days(60);
        properties.insert(
            "last_seen".to_string(),
            json!(sixty_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_before_with_iso_date() {
        let prop = Property {
            key: "expiry_date".to_string(),
            value: json!("2024-06-15"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("expiry_date".to_string(), json!("2024-06-10"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("expiry_date".to_string(), json!("2024-06-20"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_after_with_iso_date() {
        let prop = Property {
            key: "start_date".to_string(),
            value: json!("2024-01-01"),
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("start_date".to_string(), json!("2024-03-15"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("start_date".to_string(), json!("2023-12-01"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_hours() {
        let prop = Property {
            key: "last_active".to_string(),
            value: json!("-24h"), // 24 hours ago
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 12 hours ago should be after -24h
        let twelve_hours_ago = chrono::Utc::now() - chrono::Duration::hours(12);
        properties.insert(
            "last_active".to_string(),
            json!(twelve_hours_ago.to_rfc3339()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 48 hours ago should NOT be after -24h
        let forty_eight_hours_ago = chrono::Utc::now() - chrono::Duration::hours(48);
        properties.insert(
            "last_active".to_string(),
            json!(forty_eight_hours_ago.to_rfc3339()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_weeks() {
        let prop = Property {
            key: "joined".to_string(),
            value: json!("-2w"), // 2 weeks ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 3 weeks ago should be before -2w
        let three_weeks_ago = chrono::Utc::now() - chrono::Duration::weeks(3);
        properties.insert(
            "joined".to_string(),
            json!(three_weeks_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 1 week ago should NOT be before -2w
        let one_week_ago = chrono::Utc::now() - chrono::Duration::weeks(1);
        properties.insert(
            "joined".to_string(),
            json!(one_week_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_months() {
        let prop = Property {
            key: "subscription_date".to_string(),
            value: json!("-3m"), // 3 months ago
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 1 month ago should be after -3m
        let one_month_ago = chrono::Utc::now() - chrono::Duration::days(30);
        properties.insert(
            "subscription_date".to_string(),
            json!(one_month_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 6 months ago should NOT be after -3m
        let six_months_ago = chrono::Utc::now() - chrono::Duration::days(180);
        properties.insert(
            "subscription_date".to_string(),
            json!(six_months_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_years() {
        let prop = Property {
            key: "created_at".to_string(),
            value: json!("-1y"), // 1 year ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 2 years ago should be before -1y
        let two_years_ago = chrono::Utc::now() - chrono::Duration::days(730);
        properties.insert(
            "created_at".to_string(),
            json!(two_years_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 6 months ago should NOT be before -1y
        let six_months_ago = chrono::Utc::now() - chrono::Duration::days(180);
        properties.insert(
            "created_at".to_string(),
            json!(six_months_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_invalid_date_format() {
        let prop = Property {
            key: "date".to_string(),
            value: json!("-7d"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("date".to_string(), json!("not-a-date"));

        // Invalid date formats should return inconclusive
        let result = match_property(&prop, &properties);
        assert!(result.is_err());
    }

    #[test]
    fn test_is_date_with_iso_datetime() {
        let prop = Property {
            key: "event_time".to_string(),
            value: json!("2024-06-15T10:30:00Z"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("event_time".to_string(), json!("2024-06-15T08:00:00Z"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("event_time".to_string(), json!("2024-06-15T12:00:00Z"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Tests for cohort membership ====================

    #[test]
    fn test_cohort_membership_in() {
        // Create a cohort that matches users with country = US
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "cohort_1".to_string(),
            CohortDefinition::new(
                "cohort_1".to_string(),
                vec![Property {
                    key: "country".to_string(),
                    value: json!("US"),
                    operator: "exact".to_string(),
                    property_type: None,
                }],
            ),
        );

        // Property filter checking cohort membership
        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("cohort_1"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        // User with country = US should be in the cohort
        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));

        let ctx = EvaluationContext {
            cohorts: &cohorts,
            flags: &HashMap::new(),
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        // User with country = UK should NOT be in the cohort
        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_cohort_membership_not_in() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "cohort_blocked".to_string(),
            CohortDefinition::new(
                "cohort_blocked".to_string(),
                vec![Property {
                    key: "status".to_string(),
                    value: json!("blocked"),
                    operator: "exact".to_string(),
                    property_type: None,
                }],
            ),
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("cohort_blocked"),
            operator: "not_in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        let mut properties = HashMap::new();
        properties.insert("status".to_string(), json!("active"));

        let ctx = EvaluationContext {
            cohorts: &cohorts,
            flags: &HashMap::new(),
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };
        // User with status = active should NOT be in the blocked cohort (so not_in returns true)
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        // User with status = blocked IS in the cohort (so not_in returns false)
        properties.insert("status".to_string(), json!("blocked"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_cohort_not_found_returns_inconclusive() {
        let cohorts = HashMap::new(); // No cohorts defined

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("nonexistent_cohort"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &cohorts,
            flags: &HashMap::new(),
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        let result = match_property_with_context(&prop, &properties, &ctx);
        assert!(result.is_err());
        assert!(result.unwrap_err().message.contains("Cohort"));
    }

    // ==================== Tests for flag dependencies ====================

    #[test]
    fn test_flag_dependency_enabled() {
        let mut flags = HashMap::new();
        flags.insert(
            "prerequisite-flag".to_string(),
            FeatureFlag {
                key: "prerequisite-flag".to_string(),
                active: true,
                filters: FeatureFlagFilters {
                    groups: vec![FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    }],
                    multivariate: None,
                    payloads: HashMap::new(),
                    aggregation_group_type_index: None,
                    early_exit: false,
                },
            },
        );

        // Property checking if prerequisite-flag is enabled
        let prop = Property {
            key: "$feature/prerequisite-flag".to_string(),
            value: json!(true),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        // The prerequisite flag is enabled for user-123, so this should match
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_flag_dependency_disabled() {
        let mut flags = HashMap::new();
        flags.insert(
            "disabled-flag".to_string(),
            FeatureFlag {
                key: "disabled-flag".to_string(),
                active: false, // Flag is inactive
                filters: FeatureFlagFilters {
                    groups: vec![],
                    multivariate: None,
                    payloads: HashMap::new(),
                    aggregation_group_type_index: None,
                    early_exit: false,
                },
            },
        );

        // Property checking if disabled-flag is enabled
        let prop = Property {
            key: "$feature/disabled-flag".to_string(),
            value: json!(true),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        // The flag is disabled, so checking for true should fail
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_flag_dependency_variant_match() {
        let mut flags = HashMap::new();
        flags.insert(
            "ab-test-flag".to_string(),
            FeatureFlag {
                key: "ab-test-flag".to_string(),
                active: true,
                filters: FeatureFlagFilters {
                    groups: vec![FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    }],
                    multivariate: Some(MultivariateFilter {
                        variants: vec![
                            MultivariateVariant {
                                key: "control".to_string(),
                                rollout_percentage: 50.0,
                            },
                            MultivariateVariant {
                                key: "test".to_string(),
                                rollout_percentage: 50.0,
                            },
                        ],
                    }),
                    payloads: HashMap::new(),
                    aggregation_group_type_index: None,
                    early_exit: false,
                },
            },
        );

        // Check if user is in "control" variant
        let prop = Property {
            key: "$feature/ab-test-flag".to_string(),
            value: json!("control"),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-gets-control", // This distinct_id should deterministically get "control"
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        // The result depends on the hash - we just check it doesn't error
        let result = match_property_with_context(&prop, &properties, &ctx);
        assert!(result.is_ok());
    }

    #[test]
    fn test_flag_dependency_not_found_returns_inconclusive() {
        let flags = HashMap::new(); // No flags defined

        let prop = Property {
            key: "$feature/nonexistent-flag".to_string(),
            value: json!(true),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        let result = match_property_with_context(&prop, &properties, &ctx);
        assert!(result.is_err());
        assert!(result.unwrap_err().message.contains("Flag"));
    }

    // ==================== Date parsing edge case tests ====================

    #[test]
    fn test_parse_relative_date_edge_cases() {
        // These test the internal parse_relative_date function indirectly via match_property
        let prop = Property {
            key: "date".to_string(),
            value: json!("placeholder"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("date".to_string(), json!("2024-01-01"));

        // Empty string as target date should fail
        let empty_prop = Property {
            value: json!(""),
            ..prop.clone()
        };
        assert!(match_property(&empty_prop, &properties).is_err());

        // Single dash should fail
        let dash_prop = Property {
            value: json!("-"),
            ..prop.clone()
        };
        assert!(match_property(&dash_prop, &properties).is_err());

        // Missing unit (just "-7") should fail
        let no_unit_prop = Property {
            value: json!("-7"),
            ..prop.clone()
        };
        assert!(match_property(&no_unit_prop, &properties).is_err());

        // Missing number (just "-d") should fail
        let no_number_prop = Property {
            value: json!("-d"),
            ..prop.clone()
        };
        assert!(match_property(&no_number_prop, &properties).is_err());

        // Invalid unit should fail
        let invalid_unit_prop = Property {
            value: json!("-7x"),
            ..prop.clone()
        };
        assert!(match_property(&invalid_unit_prop, &properties).is_err());
    }

    #[test]
    fn test_parse_relative_date_large_values() {
        // Very large relative dates should work
        let prop = Property {
            key: "created_at".to_string(),
            value: json!("-1000d"), // ~2.7 years ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Date 5 years ago should be before -1000d
        let five_years_ago = chrono::Utc::now() - chrono::Duration::days(1825);
        properties.insert(
            "created_at".to_string(),
            json!(five_years_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());
    }

    // ==================== Tests for invalid regex patterns ====================

    #[test]
    fn test_regex_with_invalid_pattern_returns_false() {
        // Invalid regex pattern (unclosed group)
        let prop = Property {
            key: "email".to_string(),
            value: json!("(unclosed"),
            operator: "regex".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("email".to_string(), json!("test@example.com"));

        // Invalid regex should return false (not match)
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_not_regex_with_invalid_pattern_returns_true() {
        // Invalid regex pattern (unclosed group)
        let prop = Property {
            key: "email".to_string(),
            value: json!("(unclosed"),
            operator: "not_regex".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("email".to_string(), json!("test@example.com"));

        // Invalid regex with not_regex should return true (no match means "not matching")
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_regex_with_various_invalid_patterns() {
        let invalid_patterns = vec![
            "(unclosed", // Unclosed group
            "[unclosed", // Unclosed bracket
            "*invalid",  // Invalid quantifier at start
            "(?P<bad",   // Unclosed named group
            r"\",        // Trailing backslash
        ];

        for pattern in invalid_patterns {
            let prop = Property {
                key: "value".to_string(),
                value: json!(pattern),
                operator: "regex".to_string(),
                property_type: None,
            };

            let mut properties = HashMap::new();
            properties.insert("value".to_string(), json!("test"));

            // All invalid patterns should return false for regex
            assert!(
                !match_property(&prop, &properties).unwrap(),
                "Invalid pattern '{}' should return false for regex",
                pattern
            );

            // And true for not_regex
            let not_regex_prop = Property {
                operator: "not_regex".to_string(),
                ..prop
            };
            assert!(
                match_property(&not_regex_prop, &properties).unwrap(),
                "Invalid pattern '{}' should return true for not_regex",
                pattern
            );
        }
    }

    // ==================== Semver parsing tests ====================

    #[test]
    fn test_parse_semver_basic() {
        assert_eq!(parse_semver("1.2.3"), Some((1, 2, 3)));
        assert_eq!(parse_semver("0.0.0"), Some((0, 0, 0)));
        assert_eq!(parse_semver("10.20.30"), Some((10, 20, 30)));
    }

    #[test]
    fn test_parse_semver_v_prefix() {
        assert_eq!(parse_semver("v1.2.3"), Some((1, 2, 3)));
        assert_eq!(parse_semver("V1.2.3"), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_whitespace() {
        assert_eq!(parse_semver("  1.2.3  "), Some((1, 2, 3)));
        assert_eq!(parse_semver(" v1.2.3 "), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_prerelease_stripped() {
        assert_eq!(parse_semver("1.2.3-alpha"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3-beta.1"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3-rc.1+build.123"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3+build.456"), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_partial_versions() {
        assert_eq!(parse_semver("1.2"), Some((1, 2, 0)));
        assert_eq!(parse_semver("1"), Some((1, 0, 0)));
        assert_eq!(parse_semver("v1.2"), Some((1, 2, 0)));
    }

    #[test]
    fn test_parse_semver_extra_components_ignored() {
        assert_eq!(parse_semver("1.2.3.4"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3.4.5.6"), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_leading_zeros_rejected() {
        // Per semver 2.0.0 §2, numeric identifiers must not include leading zeros.
        assert_eq!(parse_semver("01.02.03"), None);
        assert_eq!(parse_semver("001.002.003"), None);
        assert_eq!(parse_semver("1.07.3"), None);
        assert_eq!(parse_semver("1.2.03"), None);
        assert_eq!(parse_semver("v01.2.3"), None);

        // Literal "0" components remain valid.
        assert_eq!(parse_semver("0.1.0"), Some((0, 1, 0)));
        assert_eq!(parse_semver("1.0.0"), Some((1, 0, 0)));
        assert_eq!(parse_semver("0.0.0"), Some((0, 0, 0)));
    }

    #[test]
    fn test_parse_semver_invalid() {
        assert_eq!(parse_semver(""), None);
        assert_eq!(parse_semver("   "), None);
        assert_eq!(parse_semver("v"), None);
        assert_eq!(parse_semver(".1.2.3"), None);
        assert_eq!(parse_semver("abc"), None);
        assert_eq!(parse_semver("1.abc.3"), None);
        assert_eq!(parse_semver("1.2.abc"), None);
        assert_eq!(parse_semver("not-a-version"), None);
    }

    // ==================== Semver eq/neq tests ====================

    #[test]
    fn test_semver_eq_basic() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.3.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_eq_with_v_prefix() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // v-prefix on property value
        properties.insert("version".to_string(), json!("v1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // v-prefix on target value
        let prop_with_v = Property {
            value: json!("v1.2.3"),
            ..prop.clone()
        };
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop_with_v, &properties).unwrap());
    }

    #[test]
    fn test_semver_eq_prerelease_stripped() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("1.2.3-alpha"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3-beta.1"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3+build.456"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_eq_partial_versions() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.0"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // "1.2" should equal "1.2.0"
        properties.insert("version".to_string(), json!("1.2"));
        assert!(match_property(&prop, &properties).unwrap());

        // Target as partial version
        let partial_prop = Property {
            value: json!("1.2"),
            ..prop.clone()
        };
        properties.insert("version".to_string(), json!("1.2.0"));
        assert!(match_property(&partial_prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_neq() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_neq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver gt/gte/lt/lte tests ====================

    #[test]
    fn test_semver_gt() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_gt".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_gte() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_gte".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_lt() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_lt".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_lte() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_lte".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver tilde tests ====================

    #[test]
    fn test_semver_tilde_basic() {
        // ~1.2.3 means >=1.2.3 <1.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_tilde".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("1.3.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_tilde_zero_versions() {
        // ~0.2.3 means >=0.2.3 <0.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.2.3"),
            operator: "semver_tilde".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("0.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.2.9"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver caret tests ====================

    #[test]
    fn test_semver_caret_major_nonzero() {
        // ^1.2.3 means >=1.2.3 <2.0.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_caret".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.99.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("2.0.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_caret_major_zero_minor_nonzero() {
        // ^0.2.3 means >=0.2.3 <0.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.2.3"),
            operator: "semver_caret".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("0.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("0.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.2.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("0.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("0.3.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("0.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_caret_major_zero_minor_zero() {
        // ^0.0.3 means >=0.0.3 <0.0.4
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.0.3"),
            operator: "semver_caret".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("0.0.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("0.0.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("0.0.5"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.1.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("0.0.2"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver wildcard tests ====================

    #[test]
    fn test_semver_wildcard_major() {
        // 1.* means >=1.0.0 <2.0.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.*"),
            operator: "semver_wildcard".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // At lower bound
        properties.insert("version".to_string(), json!("1.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.99.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("2.0.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_wildcard_minor() {
        // 1.2.* means >=1.2.0 <1.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.*"),
            operator: "semver_wildcard".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // At lower bound
        properties.insert("version".to_string(), json!("1.2.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("1.3.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_wildcard_zero() {
        // 0.* means >=0.0.0 <1.0.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.*"),
            operator: "semver_wildcard".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("0.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.99.99"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver error handling tests ====================

    #[test]
    fn test_semver_invalid_property_value() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Invalid semver strings
        properties.insert("version".to_string(), json!("not-a-version"));
        assert!(match_property(&prop, &properties).is_err());

        properties.insert("version".to_string(), json!(""));
        assert!(match_property(&prop, &properties).is_err());

        properties.insert("version".to_string(), json!(".1.2.3"));
        assert!(match_property(&prop, &properties).is_err());

        properties.insert("version".to_string(), json!("abc.def.ghi"));
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_invalid_target_value() {
        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1.2.3"));

        // Invalid target semver
        let prop = Property {
            key: "version".to_string(),
            value: json!("not-valid"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };
        assert!(match_property(&prop, &properties).is_err());

        let prop = Property {
            key: "version".to_string(),
            value: json!(""),
            operator: "semver_gt".to_string(),
            property_type: None,
        };
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_invalid_wildcard_pattern() {
        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1.2.3"));

        // Invalid wildcard patterns
        let invalid_patterns = vec![
            "*",       // Just wildcard
            "*.2.3",   // Wildcard in wrong position
            "1.*.3",   // Wildcard in wrong position
            "1.2.3.*", // Too many parts
            "abc.*",   // Non-numeric major
        ];

        for pattern in invalid_patterns {
            let prop = Property {
                key: "version".to_string(),
                value: json!(pattern),
                operator: "semver_wildcard".to_string(),
                property_type: None,
            };
            assert!(
                match_property(&prop, &properties).is_err(),
                "Pattern '{}' should be invalid",
                pattern
            );
        }
    }

    #[test]
    fn test_semver_missing_property() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let properties = HashMap::new(); // Empty properties
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_null_property_value() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!(null));

        // null converts to "null" string which is not a valid semver
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_numeric_property_value() {
        // When property value is a number, it gets converted to string
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.0.0"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Number 1 becomes "1" which parses as (1, 0, 0)
        properties.insert("version".to_string(), json!(1));
        assert!(match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver edge cases ====================

    #[test]
    fn test_semver_four_part_versions() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3.4"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // 1.2.3.4 should equal 1.2.3 (extra parts ignored)
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3.999"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_large_version_numbers() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1000.2000.3000"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1000.2000.3000"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_comparison_ordering() {
        // Test that version ordering is correct across major/minor/patch
        let cases = vec![
            ("0.0.1", "0.0.2", "semver_lt", true),
            ("0.1.0", "0.0.99", "semver_gt", true),
            ("1.0.0", "0.99.99", "semver_gt", true),
            ("1.0.0", "1.0.0", "semver_eq", true),
            ("2.0.0", "10.0.0", "semver_lt", true), // Numeric, not string comparison
            ("9.0.0", "10.0.0", "semver_lt", true), // Numeric, not string comparison
            ("1.9.0", "1.10.0", "semver_lt", true), // Numeric, not string comparison
            ("1.2.9", "1.2.10", "semver_lt", true), // Numeric, not string comparison
        ];

        for (prop_val, target_val, op, expected) in cases {
            let prop = Property {
                key: "version".to_string(),
                value: json!(target_val),
                operator: op.to_string(),
                property_type: None,
            };

            let mut properties = HashMap::new();
            properties.insert("version".to_string(), json!(prop_val));

            assert_eq!(
                match_property(&prop, &properties).unwrap(),
                expected,
                "{} {} {} should be {}",
                prop_val,
                op,
                target_val,
                expected
            );
        }
    }

    #[test]
    fn test_match_property_semver_rejects_leading_zeros() {
        // Per semver 2.0.0 §2, numeric identifiers must not include leading zeros.
        // Both property (override) values and target (flag) values should fail to
        // parse, surfacing InconclusiveMatchError so the condition does not match.

        let bad_versions = ["1.07.3", "01.02.03", "1.2.03", "v01.2.3", "001.0.0"];

        // Override values are rejected across semver_eq.
        for bad in bad_versions {
            let prop = Property {
                key: "version".to_string(),
                value: json!("1.2.3"),
                operator: "semver_eq".to_string(),
                property_type: None,
            };
            let mut properties = HashMap::new();
            properties.insert("version".to_string(), json!(bad));
            assert!(
                match_property(&prop, &properties).is_err(),
                "override '{}' should be rejected",
                bad
            );
        }

        // Literal "0" components still work for semver_eq.
        for good in ["0.1.0", "1.0.0", "0.0.0"] {
            let prop = Property {
                key: "version".to_string(),
                value: json!(good),
                operator: "semver_eq".to_string(),
                property_type: None,
            };
            let mut properties = HashMap::new();
            properties.insert("version".to_string(), json!(good));
            assert!(
                match_property(&prop, &properties).unwrap(),
                "'{}' should parse and match itself",
                good
            );
        }

        // Flag (target) values are rejected across the remaining operators.
        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1.2.3"));

        for op in ["semver_gt", "semver_caret", "semver_tilde"] {
            for bad in bad_versions {
                let prop = Property {
                    key: "version".to_string(),
                    value: json!(bad),
                    operator: op.to_string(),
                    property_type: None,
                };
                assert!(
                    match_property(&prop, &properties).is_err(),
                    "target '{}' for {} should be rejected",
                    bad,
                    op
                );
            }
        }

        // Wildcard patterns with leading-zero numeric components are rejected.
        for bad_pattern in ["01.*", "1.07.*", "v01.2.*"] {
            let prop = Property {
                key: "version".to_string(),
                value: json!(bad_pattern),
                operator: "semver_wildcard".to_string(),
                property_type: None,
            };
            assert!(
                match_property(&prop, &properties).is_err(),
                "wildcard target '{}' should be rejected",
                bad_pattern
            );
        }
    }

    // ==================== Tests for early_exit ====================

    /// Build a two-group flag where the first group always lands
    /// out-of-rollout-bound (no property filters, 0% rollout) and the second
    /// group always matches (no property filters, 100% rollout). Without
    /// `early_exit`, evaluation falls through to the matching second group.
    fn early_exit_flag(early_exit: bool) -> FeatureFlag {
        FeatureFlag {
            key: "early-exit-flag".to_string(),
            active: true,
            filters: FeatureFlagFilters {
                groups: vec![
                    // Group 1: matches on properties (none) but rollout excludes
                    // everyone -> OUT_OF_ROLLOUT_BOUND.
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(0.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                    // Group 2: would match everyone -> MATCH.
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                ],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit,
            },
        }
    }

    macro_rules! test_early_exit {
        ($name:ident, $early_exit:expr, $expected:expr) => {
            #[test]
            fn $name() {
                let flag = early_exit_flag($early_exit);
                let result = match_feature_flag(
                    &flag,
                    "user-123",
                    &HashMap::new(),
                    &HashMap::new(),
                    &HashMap::new(),
                    &HashMap::new(),
                )
                .unwrap();
                assert_eq!(result, $expected);
            }
        };
    }

    test_early_exit!(
        test_early_exit_enabled_returns_false_without_evaluating_later_group,
        true,
        FlagValue::Boolean(false)
    );
    test_early_exit!(
        test_early_exit_unset_falls_through_to_matching_group,
        false,
        FlagValue::Boolean(true)
    );

    #[test]
    fn test_early_exit_default_is_false_from_json() {
        // A flag definition that omits `early_exit` must deserialize to false
        // and preserve the legacy fall-through behavior.
        let flag: FeatureFlag = serde_json::from_value(json!({
            "key": "early-exit-flag",
            "active": true,
            "filters": {
                "groups": [
                    { "properties": [], "rollout_percentage": 0.0, "variant": null },
                    { "properties": [], "rollout_percentage": 100.0, "variant": null }
                ]
            }
        }))
        .unwrap();
        assert!(!flag.filters.early_exit);
        let result = match_feature_flag(
            &flag,
            "user-123",
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(true));
    }

    #[test]
    fn test_early_exit_explicit_false_falls_through() {
        let flag: FeatureFlag = serde_json::from_value(json!({
            "key": "early-exit-flag",
            "active": true,
            "filters": {
                "early_exit": false,
                "groups": [
                    { "properties": [], "rollout_percentage": 0.0, "variant": null },
                    { "properties": [], "rollout_percentage": 100.0, "variant": null }
                ]
            }
        }))
        .unwrap();
        assert!(!flag.filters.early_exit);
        let result = match_feature_flag(
            &flag,
            "user-123",
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(true));
    }

    #[test]
    fn test_early_exit_property_mismatch_does_not_short_circuit() {
        // First group fails on a property filter (NO_MATCH), not rollout, so
        // even with early_exit enabled we must fall through to the matching
        // second group.
        let flag = FeatureFlag {
            key: "early-exit-flag".to_string(),
            active: true,
            filters: FeatureFlagFilters {
                groups: vec![
                    FeatureFlagCondition {
                        properties: vec![Property {
                            key: "country".to_string(),
                            value: json!("US"),
                            operator: "exact".to_string(),
                            property_type: None,
                        }],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                ],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: true,
            },
        };

        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("UK")); // does not match "US"

        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        // Property mismatch must not trigger early-exit; second group matches.
        assert_eq!(result, FlagValue::Boolean(true));
    }

    macro_rules! test_early_exit_with_context {
        ($name:ident, $early_exit:expr, $expected:expr) => {
            #[test]
            fn $name() {
                let flag = early_exit_flag($early_exit);
                let ctx = EvaluationContext {
                    cohorts: &HashMap::new(),
                    flags: &HashMap::new(),
                    distinct_id: "user-123",
                    groups: &HashMap::new(),
                    group_properties: &HashMap::new(),
                    group_type_mapping: &HashMap::new(),
                };
                let result = match_feature_flag_with_context(&flag, &HashMap::new(), &ctx).unwrap();
                assert_eq!(result, $expected);
            }
        };
    }

    test_early_exit_with_context!(
        test_early_exit_enabled_short_circuits_with_context,
        true,
        FlagValue::Boolean(false)
    );
    test_early_exit_with_context!(
        test_early_exit_unset_falls_through_with_context,
        false,
        FlagValue::Boolean(true)
    );

    #[test]
    fn test_early_exit_does_not_short_circuit_when_prior_group_inconclusive() {
        // Group 1: group-targeted (aggregation_group_type_index = 0). The
        // group_type_mapping resolves "0" → "company" and groups supplies the
        // company key, but group_properties has no entry for "company" →
        // ConditionTarget::Inconclusive → is_inconclusive = true.
        // Group 2: person-targeted, rollout 0% → OutOfRolloutBound.
        // With early_exit = true, the !is_inconclusive guard must prevent
        // short-circuiting, and the overall result must be InconclusiveMatchError.
        let flag = FeatureFlag {
            key: "early-exit-flag".to_string(),
            active: true,
            filters: FeatureFlagFilters {
                groups: vec![
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: Some(0),
                    },
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(0.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                ],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: true,
            },
        };

        let mut group_type_mapping = HashMap::new();
        group_type_mapping.insert("0".to_string(), "company".to_string());

        let mut groups = HashMap::new();
        groups.insert("company".to_string(), "acme".to_string());

        // group_properties intentionally omitted for "company" → Inconclusive
        let result = match_feature_flag(
            &flag,
            "user-123",
            &HashMap::new(),
            &groups,
            &HashMap::new(), // empty group_properties
            &group_type_mapping,
        );
        assert!(
            result.is_err(),
            "expected InconclusiveMatchError, got {:?}",
            result
        );
    }
}