aimx/

rule.rs

//! Agentic Inference Markup (AIM) Rules
//! 
//! This module defines the core Rule structure used in AIM workflows.
//! A Rule represents a single entry in an AIM structure, consisting of
//! an identifier, type definition, expression, and computed value.
//! 
//! # Rule Structure
//! 
//! ```text
//! rule_name: Type = expression @ value
//! formatted_name: Format = "Instruction" "Example1" "Example2"
//! evaluation_name: Eval = 80/100
//! _assignment: Number = @reference
//! ```
//! 
//! # Categories
//! 
//! Rules fall into three categories based on their identifier format:
//! - **Standard rules**: lowercase identifiers (e.g., `temperature`)
//! - **Modifier rules**: all-uppercase identifiers (e.g., `UNIT`)
//! - **Assignment rules**: identifiers starting with underscore (e.g., `_result`)

use anyhow::{Result, anyhow};
use bitflags::bitflags;
use std::{
    fmt,
};
use nom::{
    Finish, IResult,
    character::complete::{char, multispace0},
    error::{Error, ErrorKind},
};
use crate::{
    ContextLike,
    ExpressionLike,
    statically_evaluate, 
    Expression,
    parse_expression,
    expressions::{parse_identifier, parse_reference},
    Node,
    Typedef,
    parse_typedef,
    Value,
    values::{Errata, parse_eval, parse_format},
    parse_value,
    Writer,
};

// ----- FLAGS -----

bitflags! {
    /// Internal flags that track the state and category of a Rule
    /// 
    /// These bitflags are used to efficiently track various properties without
    /// requiring additional storage space. The flags are determined automatically
    /// from the rule's identifier and updated when the rule changes.
    #[derive(Debug, Clone, PartialEq)]
    struct Flags: usize {
        /// The rule has been modified and needs saving
        const IS_TOUCHED    = 0b0001;
        /// Rule identifier is all uppercase (modifier rule)
        const IS_MODIFIER   = 0b0010;
        /// Rule identifier starts with underscore (assignment rule)
        const IS_ASSIGNMENT = 0b0100;
        /// Expression has been statically evaluated to constant value
        const IS_STATIC     = 0b1000;
    }
}

/// Check if a string contains only uppercase characters.
pub fn is_uppercase(s: &str) -> bool {
    s.chars().all(|c| c.is_uppercase())
}

/// Check if a string contains only lowercase characters.
pub fn is_lowercase(s: &str) -> bool {
    s.chars().all(|c| c.is_lowercase())
}

/// Test if an identifier should be considered a modifier rule.
pub fn test_for_modifier(identifier: &str) -> bool {
    if is_uppercase(identifier) {
        true
    } else {
        false
    }
}

/// Test if an identifier should be considered an assignment rule.
pub fn test_for_assignment(identifier: &str) -> bool {
    identifier.starts_with('_')
}

/// Initialize rule flags based on an identifier.
fn init_flags(identifier: &str) -> Flags {
    let mut flags = Flags::empty();
    if test_for_modifier(&identifier) {
        flags.insert(Flags::IS_MODIFIER);
    }
    if test_for_assignment(&identifier) {
        flags.insert(Flags::IS_ASSIGNMENT);
    }
    flags
}

// ----- RULE -----

/// A single rule in an AIM structure representing a workflow component
/// 
/// Rules are the fundamental building blocks of AIM workflows, defining
/// how values are computed, formatted, evaluated, or assigned. Each rule
/// consists of:
/// - An identifier that uniquely names the rule
/// - A type definition that constrains valid values
/// - An expression that computes the rule's value
/// - A current value (computed or assigned)
/// - Internal flags tracking state and category
/// 
/// # Examples
/// 
/// ```rust
/// # use aimx::rule::Rule;
/// # use aimx::{Typedef, Expression, Value, Literal};
/// // Create a simple rule
/// let rule = Rule::new(
///     "temperature".to_string(),
///     Typedef::Number,
///     Expression::Empty,
///     Value::Literal(Literal::from_number(25.0))
/// );
/// ```
#[derive(Debug, Clone, PartialEq)]
pub struct Rule {
    /// The rule's identifier, which uniquely identifies it within an AIM structure
    identifier: String,
    /// The type definition that constrains what values this rule can hold
    typedef: Typedef,
    /// The expression that defines how the rule's value is computed or assigned
    expression: Expression,
    /// The current value of the rule, computed from the expression or set directly
    value: Value,
    /// Flags indicating the rule's state and category
    flags: Flags,
}

impl Rule {
    /// Create a new Rule with the given components
    /// 
    /// # Parameters
    /// - `identifier`: The rule's unique identifier
    /// - `typedef`: The type definition for the rule
    /// - `expression`: The expression that computes the rule's value
    /// - `value`: The initial value of the rule
    /// 
    /// # Returns
    /// A new Rule instance with appropriate flags set based on the identifier
    /// 
    /// # Notes
    /// - Automatically performs static evaluation of expressions when possible
    /// - Sets flags based on identifier format (modifier/assignment)
    pub fn new(identifier: String, typedef: Typedef, expression: Expression, value: Value) -> Self {
        let mut flags = init_flags(&identifier);
        if expression.is_empty() {
            Self {
                identifier,
                typedef,
                expression,
                value,
                flags,
            }
        } else {
            let (exp, val) = match statically_evaluate(&expression) {
                Ok(value) => {
                    flags.insert(Flags::IS_STATIC);
                    flags.insert(Flags::IS_TOUCHED);
                    (Expression::Empty, value)
                }
                _ => (expression, Value::Empty),
            };            
            Self {
                identifier,
                typedef,
                expression: exp,

                value: val,
                flags,
            }
        }
    }

    /// Create a new Rule by parsing operands from a string
    /// 
    /// This constructor parses the expression/value portion of a rule definition
    /// based on the rule's type definition and assignment status.
    /// 
    /// # Parameters
    /// - `input`: The string containing the rule's operands
    /// - `identifier`: The rule's identifier
    /// - `typedef`: The rule's type definition
    /// - `is_assignment`: Whether this is an assignment rule
    /// 
    /// # Returns
    /// A new Rule instance with parsed expression and value
    /// 
    /// # Errors
    /// Returns error expressions for incomplete or malformed input
    pub fn new_from(input: &str, identifier: &str, typedef: &Typedef, is_assignment: bool) -> Self {
        match parse_rule_operands(input, typedef, is_assignment) {
            Ok((_, (expression, value))) => {
                Self::new(identifier.to_string(), typedef.clone(), expression, value)
            }
            Err(nom::Err::Incomplete(_)) => {
                let expression = Errata::new_reason_expression(
                    "Incomplete Expression".to_owned(),
                    input.to_string()
                );
                Self::new(identifier.to_string(), typedef.clone(), expression, Value::Empty)
            }
            Err(nom::Err::Error(e)) | Err(nom::Err::Failure(e)) => {
                let expression = Errata::new_reason_expression_location(
                    format!("Syntax Error ({})", e),
                    input.to_string(),
                    e.input.to_string()
                );
                Self::new(identifier.to_string(), typedef.clone(), expression, Value::Empty)
            }
        }
    }

    /// Check if the rule is completely empty (no expression and no value)
    pub fn is_empty(&self) -> bool {
        match (&self.expression, &self.value) {
            (Expression::Empty, Value::Empty) => true,
            _ => false,
        }
    }

    /// Check if the rule contains any errors
    pub fn has_error(&self) -> bool {
        self.value.has_error() | self.expression.has_error()
    }

    /// Check if the rule has a non-empty expression
    pub fn has_expression(&self) -> bool {
        match &self.expression {
            Expression::Empty
            | Expression::Errata {..} => false,
            _ => true,
        }
    }

    /// Get the rule's identifier
    pub fn identifier(&self) -> &str {
        self.identifier.as_str()
    }

    /// Get the uppercase identifier (trimming leading underscore if present)
    /// 
    /// Useful for case-insensitive comparisons and display purposes
    pub fn ucid(&self) -> String {
        let mut ucid = self.identifier.to_uppercase();
        // Trim the leading underscore
        if ucid.starts_with('_') {
            // Trim first character
            ucid.remove(0);
        }
        ucid
    }

    /// Get the lowercase identifier (trimming leading underscore if present)
    /// 
    /// Useful for case-insensitive comparisons and display purposes
    pub fn lcid(&self) -> String {
        let mut ucid = self.identifier.to_lowercase();
        // Trim the leading underscore
        if ucid.starts_with('_') {
            // Trim first character
            ucid.remove(0);
        }
        ucid
    }

    /// Set a new identifier for the rule
    /// 
    /// Updates the identifier and automatically adjusts flags based on the new identifier format
    pub fn set_identifier(&mut self, identifier: String) {
        // Updating the identifier potentially changes a lot of flags
        if self.identifier != identifier {
            // Update flags
            if test_for_modifier(&identifier) {
                self.flags.insert(Flags::IS_MODIFIER);
            } else {
                self.flags.remove(Flags::IS_MODIFIER);
            }
            if test_for_assignment(&identifier) {
                self.flags.insert(Flags::IS_ASSIGNMENT);
            } else {
                self.flags.remove(Flags::IS_ASSIGNMENT);
            }
            self.identifier = identifier;
            self.flags.insert(Flags::IS_TOUCHED);
        }
    }

    /// Check if this is a modifier rule (all uppercase identifier)
    pub fn is_modifier(&self) -> bool {
        self.flags.contains(Flags::IS_MODIFIER)
    }

    /// Check if this is an assignment rule (identifier starts with underscore)
    pub fn is_assignment(&self) -> bool {
        self.flags.contains(Flags::IS_ASSIGNMENT)
    }

    /// Assign a value to this rule
    /// 
    /// # Parameters
    /// - `value`: The value to assign
    /// - `context`: The evaluation context for resolving references
    /// 
    /// # Returns
    /// `Ok(())` if assignment was successful, `Err` if type mismatch occurs
    /// 
    /// # Notes
    /// - For assignment rules, sets the referenced value in the context
    /// - For other rules, directly sets the rule's value
    pub fn assign(&mut self, value: Value, context: &mut dyn ContextLike) -> Result<()> {
        // Check the value type matches the rule typedef.
        if value.is_literal() && value.is_of_type(&self.typedef) {
            // Only literal types are allowed
            match &self.value {
                // The rule value is a reference
                Value::Assignment(reference) => {
                    context.set_referenced(reference, value)
                }
                // The Rule operand is a literal so assign the value
                _ => self.set_value(value),
            }
        } else {
            Err(anyhow!("Type mismatch with assignment"))
        }
    }
    
    /// Get the rule's type definition
    pub fn typedef(&self) -> &Typedef {
        &self.typedef
    }

    /// Set a new type definition for the rule
    /// 
    /// Resets the value to empty and marks the rule as touched
    pub fn set_typedef(&mut self, typedef: Typedef) {
        if self.typedef != typedef {
            self.typedef = typedef;
            self.value = Value::Empty;
            self.flags.insert(Flags::IS_TOUCHED);
        }
    }

    /// Get the rule's expression
    pub fn expression(&self) -> &Expression {
        &self.expression
    }

    /// Set a new expression for the rule
    /// 
    /// Marks the rule as touched if the expression differs from the current one
    pub fn set_expression(&mut self, expression: Expression) {
        if self.expression.to_formula() != expression.to_formula() {
            self.expression = expression;
            self.flags.insert(Flags::IS_TOUCHED);
        }
    }

    /// Get the rule's current value
    pub fn value(&self) -> &Value {
        &self.value
    }

    /// Set the rule's value
    /// 
    /// # Parameters
    /// - `value`: The value to set
    /// 
    /// # Returns
    /// `Ok(())` if the value matches the rule's type, `Err` otherwise
    pub fn set_value(&mut self, value: Value) -> Result<()> {
        if !self.typedef.is_special() && value.is_of_type(&self.typedef) {
            self.value = value;
            Ok(())
        } else {
            Err(anyhow!("Type mismatch, expecting {} found {}",
                self.typedef.as_string(), value.type_as_string()))
        }
    }

    /// Check if this is a format rule
    pub fn is_format(&self) -> bool {
        self.typedef.is_format() && self.value.is_format()
    }

    /// Check if this is an evaluation rule
    pub fn is_eval(&self) -> bool {
        self.typedef.is_eval() && self.value.is_eval()
    }

    /// Mark an evaluation rule as passing
    /// 
    /// Only affects rules with Eval type definitions
    pub fn set_pass(&mut self) {
        if self.is_eval() {
            match &mut self.value {
                Value::Eval(eval) => {
                    eval.set_pass();
                    self.flags.insert(Flags::IS_TOUCHED);
                }
                _ => {}
            }
        }
    }

    /// Mark an evaluation rule as failing
    /// 
    /// Only affects rules with Eval type definitions
    pub fn set_fail(&mut self) {
        if self.is_eval() {
            match &mut self.value {
                Value::Eval(eval) => {
                    eval.set_fail();
                    self.flags.insert(Flags::IS_TOUCHED);
                }
                _ => {}
            }
        }
    }

    /// Check if this is a node rule
    pub fn is_node(&self) -> bool {
        self.typedef.is_node() && self.value.is_node()
    }

    /// Get the node from this rule if it is a node rule
    /// 
    /// # Returns
    /// `Some(Node)` if this is a node rule with a node value, `None` otherwise
    pub fn get_node(&self) -> Option<Node> {
        // Check the Rule is a Node
        if self.is_node() {
            match &self.value {
                // Get the Rule Node
                Value::Node(node) => Some(node.clone()),
                _ => None,
            }
        } else {
            None
        }
    }

    /// Mark the rule as touched (modified and needing saving)
    pub fn touch(&mut self) {
        self.flags.insert(Flags::IS_TOUCHED);
    }

    /// Internal method for displaying rule content
    fn print(&self, writer: &mut Writer) {        
        if self.value.is_empty() {
            self.expression.write(writer);
        }
        else {
            self.value.write(writer);
        }
    }

    /// Save the rule to a writer
    /// 
    /// Writes the complete rule definition and clears the touched flag
    pub fn save(&mut self, writer: &mut Writer) {
        self.write(writer);
        writer.write_eol();
        self.flags.remove(Flags::IS_TOUCHED);
    }

    /// Perform a partial save of the rule
    /// 
    /// Only saves if the rule has been touched, prepending the rule index
    /// 
    /// # Parameters
    /// - `index`: The index of this rule in its parent structure
    /// - `writer`: The writer to save to
    pub fn partial_save(&mut self, index: usize, writer: &mut Writer) {
        if self.flags.contains(Flags::IS_TOUCHED) {
            // prepend the row index
            writer.write_unsigned(index as u32);
            writer.write_char(' ');
            self.write(writer);
            writer.write_eol();
            self.flags.remove(Flags::IS_TOUCHED);
        }
    }

}

/// Parse a rule from a string according to the AIM grammar.
/// 
/// This function parses a complete rule definition from a string, including its identifier,
/// optional quick evaluation status, type definition, operand, and optional value.
/// 
/// The grammar for a rule is:
/// `rule = WS?, identifier, WS?, ':', WS?, typedef, WS?, '=', WS?, value, WS?, EOL`
/// 
/// # Parameters
/// - `input`: The string to parse as a rule definition
/// 
/// # Returns
/// `Ok(Rule)` if parsing was successful, or an error with details if parsing failed
/// 
/// # Examples
/// 
/// ```
/// # use aimx::rule::parse_rule;
/// let rule = parse_rule(r#"test_rule: Number = 42"#).unwrap();
/// assert_eq!(rule.identifier(), "test_rule");
/// ```
pub fn parse_rule(input: &str) -> Result<Rule> {
    match parse_rule_elements(input).finish() {
        Ok((_, rule)) => Ok(rule),
        Err(e) => Err(anyhow!("Parse error: {}", e)),
    }
}

/// Parse the individual elements of a rule from a string according to AIM grammar.
fn parse_rule_elements(input: &str) -> IResult<&str, Rule> {
    // Parse identifier
    let (input, _) = multispace0(input)?; // WS ?
    let (input, identifier) = parse_identifier(input)?;
    let is_assignment = identifier.starts_with('_');

    // Parse colon
    let (input, _) = multispace0(input)?; // WS ?
    let (input, _) = char(':')(input)?;

    // Parse type declaration
    let (input, _) = multispace0(input)?; // WS ?
    let (input, typedef) = parse_typedef(input)?;

    // Parse equals sign
    let (input, _) = multispace0(input)?; // WS ?
    let (input, _) = char('=')(input)?;

    let (input, (expression, value)) = parse_rule_operands(input, &typedef, is_assignment)?;

    let rule = Rule::new(identifier, typedef, expression, value);
    Ok((input, rule))
}

/// Parse the expression and value operands of a rule.
fn parse_rule_operands<'a>(input: &'a str, typedef: &Typedef, is_assignment: bool) 
    -> IResult<&'a str, (Expression, Value)>
    {

    // Parse expression @ value
    let input = input.trim(); // WS ?

    // The parsing strategy depends on the typedef:
    // - Empty input results in `Expression::Empty`
    let (input, value) = if input.is_empty() {
        if typedef.is_format() {
            // Format should never be empty
            return Err(nom::Err::Error(Error::new(input, ErrorKind::Fail)))
        } else {
            (input, Value::Empty)
        }
    // - Constant values are from statically evaluated expressions
    } else if input.starts_with('@') {
        let (input, _) = char('@')(input)?;
        let (input, value) = parse_value(input)?;
        (input, value)
    // - Format types are parsed as "Instruction" <format> "Example", "Example", "Example"...
    } else if typedef.is_format() {
        let (input, value) = parse_format(input)?;
        (input, value)
    // - Eval types are parsed as ratio, score, count
    } else if typedef.is_eval() {
        let (input, value) = parse_eval(input)?;
        (input, value)
    // - Node types are parsed as a "Name" (Human readable)
    } else if typedef.is_node() {
        // Empty for now
        (input, Value::Empty)
    // - Assignment references are rules with a leading underscore
    } else if is_assignment {
        // Parse reference
        if let Ok((input, reference)) = parse_reference(input) {
            (input, Value::Assignment(reference))
        }
        else {
            let (input, value) = parse_value(input)?;
            (input, value)
        }
    // - Expression types are parsed as normal
    } else {
        // Parse expression
        let (input, expression) = parse_expression(input)?;
        let (input, _) = multispace0(input)?; // WS ?
        let (input, value) = if input.starts_with('@') {
            let (input, _) = char('@')(input)?;
            let (input, value) = parse_value(input)?;
            (input, value)
        } else {
            (input, Value::Empty)
        };
        return Ok((input, (expression, value)))
    };
    Ok((input, (Expression::Empty, value)))
}

impl ExpressionLike for Rule {
    /// Evaluate the rule's expression or value in the given context
    /// 
    /// If the rule has an expression, evaluates it. Otherwise, evaluates the rule's value.
    /// 
    /// # Parameters
    /// - `context`: The evaluation context
    /// 
    /// # Returns
    /// `Ok(Value)` containing the evaluated result
    fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Value> {
        if self.expression.is_empty() {
            self.value.evaluate(context)
        }
        else {
            self.expression.evaluate(context)
        }
    }

    /// Write the rule's complete definition to a writer
    /// 
    /// Outputs the rule in AIM format: `identifier: typedef = expression @ value`
    fn write(&self, writer: &mut Writer) {
        writer.write_str(&self.identifier);
        writer.write_str(": ");
        self.typedef.write(writer);
        writer.write_str(" = ");
        if self.expression.is_empty() {
            if self.value.is_constant() {
                 writer.write_str("@ ");
            }
            self.value.write(writer);
        } else {
            self.expression.write(writer);
            if self.value.is_constant() {
                writer.write_str(" @ ");
                self.value.write(writer);
            }
        }
    }

    /// Get a sanitized string representation of the rule
    /// 
    /// Removes sensitive information and produces a safe representation
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        self.write(&mut writer);
        writer.finish()
    }

    /// Get the rule's formula representation
    /// 
    /// Produces a string suitable for formula evaluation
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.write(&mut writer);
        writer.finish()
    }
}

impl fmt::Display for Rule {
    /// Display the rule's content (expression or value) for user-facing output
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::formulizer();
        self.print(&mut writer);
        write!(f, "{}", writer.finish())
    }
}