cloacina 0.6.1

/*
 *  Copyright 2025-2026 Colliery Software
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

//! Trigger rules for conditional task execution.
//!
//! This module defines the trigger rule types and operators used to determine
//! when tasks should be executed based on various conditions.

use serde::{Deserialize, Serialize};

/// Trigger rule definitions for conditional task execution.
///
/// Trigger rules determine when a task should be executed based on various conditions.
/// They can be combined to create complex execution logic.
///
/// # Examples
///
/// ```rust,ignore
/// use cloacina::execution_planner::{TriggerRule, TriggerCondition, ValueOperator};
/// use serde_json::json;
///
/// // Always execute
/// let always = TriggerRule::Always;
///
/// // Execute if all conditions are met
/// let all_conditions = TriggerRule::All {
///     conditions: vec![
///         TriggerCondition::TaskSuccess { task_name: "task1".to_string() },
///         TriggerCondition::ContextValue {
///             key: "status".to_string(),
///             operator: ValueOperator::Equals,
///             value: json!("ready")
///         }
///     ]
/// };
///
/// // Execute if any condition is met
/// let any_condition = TriggerRule::Any {
///     conditions: vec![
///         TriggerCondition::TaskFailed { task_name: "task1".to_string() },
///         TriggerCondition::TaskSkipped { task_name: "task2".to_string() }
///     ]
/// };
///
/// // Execute if no conditions are met
/// let none_condition = TriggerRule::None {
///     conditions: vec![
///         TriggerCondition::ContextValue {
///             key: "skip".to_string(),
///             operator: ValueOperator::Exists,
///             value: json!(true)
///         }
///     ]
/// };
/// ```
///
/// # Performance
///
/// Trigger rule evaluation:
/// - Is performed in memory
/// - Uses efficient context lookups
/// - Supports early termination for All/Any rules
/// - Caches context values where possible
///
/// # Thread Safety
///
/// Trigger rules are:
/// - Immutable after creation
/// - Safe to share across threads
/// - Free of side effects
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum TriggerRule {
    /// Always execute the task (default behavior).
    Always,
    /// Execute only if all conditions are met.
    All { conditions: Vec<TriggerCondition> },
    /// Execute if any condition is met.
    Any { conditions: Vec<TriggerCondition> },
    /// Execute only if none of the conditions are met.
    None { conditions: Vec<TriggerCondition> },
}

/// Individual conditions that can be evaluated for trigger rules.
///
/// Conditions are the building blocks of trigger rules, allowing tasks to be
/// executed based on the state of other tasks or context values.
///
/// # Examples
///
/// ```rust,ignore
/// use cloacina::execution_planner::{TriggerCondition, ValueOperator};
/// use serde_json::json;
///
/// // Task state conditions
/// let task_success = TriggerCondition::TaskSuccess { task_name: "task1".to_string() };
/// let task_failed = TriggerCondition::TaskFailed { task_name: "task2".to_string() };
/// let task_skipped = TriggerCondition::TaskSkipped { task_name: "task3".to_string() };
///
/// // Context value conditions
/// let context_equals = TriggerCondition::ContextValue {
///     key: "status".to_string(),
///     operator: ValueOperator::Equals,
///     value: json!("ready")
/// };
///
/// let context_exists = TriggerCondition::ContextValue {
///     key: "flag".to_string(),
///     operator: ValueOperator::Exists,
///     value: json!(true)
/// };
/// ```
///
/// # Performance
///
/// Condition evaluation:
/// - Task state conditions use efficient database lookups
/// - Context value conditions are evaluated in memory
/// - Results are cached where possible
/// - Supports early termination for complex conditions
///
/// # Thread Safety
///
/// Conditions are:
/// - Immutable after creation
/// - Safe to share across threads
/// - Free of side effects
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum TriggerCondition {
    /// Condition based on successful task completion.
    TaskSuccess { task_name: String },
    /// Condition based on task failure.
    TaskFailed { task_name: String },
    /// Condition based on task being skipped.
    TaskSkipped { task_name: String },
    /// Condition based on context value evaluation.
    ContextValue {
        key: String,
        operator: ValueOperator,
        value: serde_json::Value,
    },
}

/// Operators for evaluating context values in trigger conditions.
///
/// These operators define how context values should be compared and evaluated
/// in trigger conditions.
///
/// # Examples
///
/// ```rust,ignore
/// use cloacina::execution_planner::ValueOperator;
/// use serde_json::json;
///
/// // Basic comparisons
/// let equals = ValueOperator::Equals;      // ==
/// let not_equals = ValueOperator::NotEquals; // !=
/// let greater = ValueOperator::GreaterThan;  // >
/// let less = ValueOperator::LessThan;       // <
///
/// // String operations
/// let contains = ValueOperator::Contains;     // "hello".contains("ell")
/// let not_contains = ValueOperator::NotContains; // !"hello".contains("xyz")
///
/// // Existence checks
/// let exists = ValueOperator::Exists;       // key exists
/// let not_exists = ValueOperator::NotExists; // key doesn't exist
/// ```
///
/// # Performance
///
/// Operator evaluation:
/// - Uses efficient type-specific comparisons
/// - Supports early termination where possible
/// - Handles type coercion gracefully
/// - Caches results for repeated evaluations
///
/// # Thread Safety
///
/// Operators are:
/// - Immutable
/// - Safe to share across threads
/// - Free of side effects
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ValueOperator {
    /// Exact equality comparison.
    Equals,
    /// Inequality comparison.
    NotEquals,
    /// Greater than comparison (for numbers).
    GreaterThan,
    /// Less than comparison (for numbers).
    LessThan,
    /// Contains check (for strings and arrays).
    Contains,
    /// Does not contain check.
    NotContains,
    /// Key exists in context.
    Exists,
    /// Key does not exist in context.
    NotExists,
}

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

    // ── TriggerRule serialization ────────────────────────────────────

    #[test]
    fn trigger_rule_always_roundtrip() {
        let rule = TriggerRule::Always;
        let json = serde_json::to_string(&rule).unwrap();
        let deserialized: TriggerRule = serde_json::from_str(&json).unwrap();
        assert!(matches!(deserialized, TriggerRule::Always));
    }

    #[test]
    fn trigger_rule_all_roundtrip() {
        let rule = TriggerRule::All {
            conditions: vec![
                TriggerCondition::TaskSuccess {
                    task_name: "task1".to_string(),
                },
                TriggerCondition::ContextValue {
                    key: "status".to_string(),
                    operator: ValueOperator::Equals,
                    value: json!("ready"),
                },
            ],
        };
        let json = serde_json::to_string(&rule).unwrap();
        let deserialized: TriggerRule = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerRule::All { conditions } => assert_eq!(conditions.len(), 2),
            _ => panic!("Expected TriggerRule::All"),
        }
    }

    #[test]
    fn trigger_rule_any_roundtrip() {
        let rule = TriggerRule::Any {
            conditions: vec![TriggerCondition::TaskFailed {
                task_name: "task2".to_string(),
            }],
        };
        let json = serde_json::to_string(&rule).unwrap();
        let deserialized: TriggerRule = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerRule::Any { conditions } => assert_eq!(conditions.len(), 1),
            _ => panic!("Expected TriggerRule::Any"),
        }
    }

    #[test]
    fn trigger_rule_none_roundtrip() {
        let rule = TriggerRule::None {
            conditions: vec![TriggerCondition::TaskSkipped {
                task_name: "task3".to_string(),
            }],
        };
        let json = serde_json::to_string(&rule).unwrap();
        let deserialized: TriggerRule = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerRule::None { conditions } => assert_eq!(conditions.len(), 1),
            _ => panic!("Expected TriggerRule::None"),
        }
    }

    #[test]
    fn trigger_rule_all_empty_conditions() {
        let rule = TriggerRule::All { conditions: vec![] };
        let json = serde_json::to_string(&rule).unwrap();
        let deserialized: TriggerRule = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerRule::All { conditions } => assert!(conditions.is_empty()),
            _ => panic!("Expected TriggerRule::All"),
        }
    }

    // ── TriggerCondition serialization ───────────────────────────────

    #[test]
    fn condition_task_success_roundtrip() {
        let cond = TriggerCondition::TaskSuccess {
            task_name: "my_task".to_string(),
        };
        let json = serde_json::to_string(&cond).unwrap();
        assert!(json.contains("TaskSuccess"));
        let deserialized: TriggerCondition = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerCondition::TaskSuccess { task_name } => assert_eq!(task_name, "my_task"),
            _ => panic!("Expected TaskSuccess"),
        }
    }

    #[test]
    fn condition_task_failed_roundtrip() {
        let cond = TriggerCondition::TaskFailed {
            task_name: "fail_task".to_string(),
        };
        let json = serde_json::to_string(&cond).unwrap();
        let deserialized: TriggerCondition = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerCondition::TaskFailed { task_name } => assert_eq!(task_name, "fail_task"),
            _ => panic!("Expected TaskFailed"),
        }
    }

    #[test]
    fn condition_task_skipped_roundtrip() {
        let cond = TriggerCondition::TaskSkipped {
            task_name: "skip_task".to_string(),
        };
        let json = serde_json::to_string(&cond).unwrap();
        let deserialized: TriggerCondition = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerCondition::TaskSkipped { task_name } => assert_eq!(task_name, "skip_task"),
            _ => panic!("Expected TaskSkipped"),
        }
    }

    #[test]
    fn condition_context_value_roundtrip() {
        let cond = TriggerCondition::ContextValue {
            key: "count".to_string(),
            operator: ValueOperator::GreaterThan,
            value: json!(10),
        };
        let json = serde_json::to_string(&cond).unwrap();
        let deserialized: TriggerCondition = serde_json::from_str(&json).unwrap();
        match deserialized {
            TriggerCondition::ContextValue {
                key,
                operator,
                value,
            } => {
                assert_eq!(key, "count");
                assert!(matches!(operator, ValueOperator::GreaterThan));
                assert_eq!(value, json!(10));
            }
            _ => panic!("Expected ContextValue"),
        }
    }

    // ── ValueOperator serialization ─────────────────────────────────

    #[test]
    fn all_value_operators_roundtrip() {
        let operators = vec![
            ValueOperator::Equals,
            ValueOperator::NotEquals,
            ValueOperator::GreaterThan,
            ValueOperator::LessThan,
            ValueOperator::Contains,
            ValueOperator::NotContains,
            ValueOperator::Exists,
            ValueOperator::NotExists,
        ];
        for op in operators {
            let json = serde_json::to_string(&op).unwrap();
            let deserialized: ValueOperator = serde_json::from_str(&json).unwrap();
            // Verify the format string matches (Debug impl)
            assert_eq!(format!("{:?}", op), format!("{:?}", deserialized));
        }
    }

    // ── Deserialization from JSON literals ───────────────────────────

    #[test]
    fn trigger_rule_from_json_literal() {
        let json = r#"{"type":"Always"}"#;
        let rule: TriggerRule = serde_json::from_str(json).unwrap();
        assert!(matches!(rule, TriggerRule::Always));
    }

    #[test]
    fn trigger_rule_all_from_json_literal() {
        let json = r#"{
            "type": "All",
            "conditions": [
                {"type": "TaskSuccess", "task_name": "extract"},
                {"type": "ContextValue", "key": "ready", "operator": "Equals", "value": true}
            ]
        }"#;
        let rule: TriggerRule = serde_json::from_str(json).unwrap();
        match rule {
            TriggerRule::All { conditions } => {
                assert_eq!(conditions.len(), 2);
                assert!(matches!(
                    &conditions[0],
                    TriggerCondition::TaskSuccess { .. }
                ));
                assert!(matches!(
                    &conditions[1],
                    TriggerCondition::ContextValue { .. }
                ));
            }
            _ => panic!("Expected All"),
        }
    }
}