tellaro_query_language/parser/

mod.rs

//! TQL Parser module.
//!
//! This module provides parsing functionality for TQL query strings using pest.

pub mod ast;

use pest::Parser as PestParser;
use pest_derive::Parser;

pub use ast::{
    Aggregation, AstNode, ComparisonNode, CollectionOpNode, GeoExprNode, GroupBy,
    LogicalOpNode, Mutator, NslookupExprNode, QueryWithStatsNode, StatsNode,
    UnaryOpNode, Value,
};

use crate::error::{Result, TqlError};

/// pest parser for TQL grammar
#[derive(Parser)]
#[grammar = "parser/grammar.pest"]
pub struct TqlPestParser;

/// Main TQL parser
pub struct TqlParser {
    /// Maximum allowed query depth to prevent stack overflow
    max_depth: usize,
}

impl Default for TqlParser {
    fn default() -> Self {
        Self::new()
    }
}

impl TqlParser {
    /// Maximum query depth (matches Python implementation)
    pub const MAX_QUERY_DEPTH: usize = 50;

    /// Create a new parser with default settings
    pub fn new() -> Self {
        Self {
            max_depth: Self::MAX_QUERY_DEPTH,
        }
    }

    /// Create a new parser with custom max depth
    pub fn with_max_depth(max_depth: usize) -> Self {
        Self { max_depth }
    }

    /// Parse a TQL query string into an AST
    ///
    /// # Arguments
    ///
    /// * `query` - The TQL query string to parse
    ///
    /// # Returns
    ///
    /// An AST node representing the parsed query
    ///
    /// # Errors
    ///
    /// Returns a `TqlError` if the query has invalid syntax or exceeds max depth
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use tql::parser::TqlParser;
    ///
    /// let parser = TqlParser::new();
    /// let ast = parser.parse("field eq 'value'").unwrap();
    /// ```
    pub fn parse(&self, query: &str) -> Result<AstNode> {
        // Handle empty or whitespace-only queries
        if query.trim().is_empty() {
            return Ok(AstNode::MatchAll);
        }

        // Parse with pest
        let pairs = TqlPestParser::parse(Rule::query, query).map_err(|e| {
            let location = match &e.location {
                pest::error::InputLocation::Pos(pos) => *pos,
                pest::error::InputLocation::Span((start, _)) => *start,
            };

            TqlError::ParseError {
                message: format!("Parse error: {}", e),
                position: location,
                query: Some(query.to_string()),
            }
        })?;

        // Build AST from pest pairs
        self.build_ast_from_pairs(pairs, 0)
    }

    /// Build AST from pest parse pairs
    fn build_ast_from_pairs(
        &self,
        pairs: pest::iterators::Pairs<Rule>,
        depth: usize,
    ) -> Result<AstNode> {
        // Check depth limit
        if depth > self.max_depth {
            return Err(TqlError::SyntaxError {
                message: format!(
                    "Query depth exceeds maximum allowed depth of {}",
                    self.max_depth
                ),
                position: Some(0),
                query: None,
                suggestions: vec![
                    "Reduce query nesting depth".to_string(),
                    "Split into multiple simpler queries".to_string(),
                ],
            });
        }

        // Get the first pair (should be query rule)
        for pair in pairs {
            match pair.as_rule() {
                Rule::query => {
                    // Query contains one of: query_with_stats | stats_expr | logical_expr
                    let inner = pair.into_inner();
                    return self.build_ast_from_pairs(inner, depth);
                }
                Rule::query_with_stats => {
                    return self.parse_query_with_stats(pair, depth + 1);
                }
                Rule::stats_expr => {
                    return self.parse_stats_expr(pair, depth + 1);
                }
                Rule::logical_expr => {
                    return self.parse_logical_expr(pair, depth + 1);
                }
                _ => {
                    return Err(TqlError::ParseError {
                        message: format!("Unexpected rule: {:?}", pair.as_rule()),
                        position: 0,
                        query: None,
                    });
                }
            }
        }

        // Empty query returns MatchAll
        Ok(AstNode::MatchAll)
    }

    /// Parse a query with stats (filter | stats)
    fn parse_query_with_stats(&self, pair: pest::iterators::Pair<Rule>, depth: usize) -> Result<AstNode> {
        let mut inner = pair.into_inner();

        // First part is the logical_expr (filter)
        let filter_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing filter expression in query_with_stats".to_string(),
            position: 0,
            query: None,
        })?;
        let filter = Box::new(self.parse_logical_expr(filter_pair, depth + 1)?);

        // Second part is stats_expr
        let stats_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing stats expression in query_with_stats".to_string(),
            position: 0,
            query: None,
        })?;

        // Parse stats_expr and extract StatsNode
        match self.parse_stats_expr(stats_pair, depth + 1)? {
            AstNode::StatsExpr(stats) => {
                Ok(AstNode::QueryWithStats(QueryWithStatsNode { filter, stats }))
            }
            _ => Err(TqlError::ParseError {
                message: "Expected stats expression".to_string(),
                position: 0,
                query: None,
            }),
        }
    }

    /// Parse a stats expression
    fn parse_stats_expr(&self, pair: pest::iterators::Pair<Rule>, _depth: usize) -> Result<AstNode> {
        let mut aggregations = Vec::new();
        let mut group_by = Vec::new();
        let mut viz_hint = None;

        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::aggregation => {
                    aggregations.push(self.parse_aggregation(inner_pair)?);
                }
                Rule::group_by_list => {
                    group_by = self.parse_group_by_list(inner_pair)?;
                }
                Rule::viz_hint => {
                    viz_hint = Some(inner_pair.into_inner().next()
                        .ok_or_else(|| TqlError::ParseError {
                            message: "Missing viz hint identifier".to_string(),
                            position: 0,
                            query: None,
                        })?
                        .as_str().to_string());
                }
                _ => {}
            }
        }

        Ok(AstNode::StatsExpr(StatsNode {
            aggregations,
            group_by,
            viz_hint,
        }))
    }

    /// Parse an aggregation function
    fn parse_aggregation(&self, pair: pest::iterators::Pair<Rule>) -> Result<Aggregation> {
        let mut function = String::new();
        let mut field = None;
        let mut alias = None;
        let mut modifier = None;
        let mut limit = None;
        let mut percentile_values = None;
        let rank_values = None;
        let mut field_mutators = None;

        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::agg_func_name => {
                    function = inner_pair.as_str().to_lowercase();
                }
                Rule::agg_field => {
                    let field_str = inner_pair.as_str();
                    if field_str != "*" {
                        // Parse field_with_mutators
                        let mut field_name = String::new();
                        let mut mutators = Vec::new();

                        for field_inner in inner_pair.into_inner() {
                            match field_inner.as_rule() {
                                Rule::field_name => {
                                    field_name = field_inner.as_str().to_string();
                                }
                                Rule::mutator => {
                                    mutators.push(self.parse_mutator(field_inner)?);
                                }
                                _ => {}
                            }
                        }

                        field = Some(field_name);
                        if !mutators.is_empty() {
                            field_mutators = Some(mutators);
                        }
                    } else {
                        field = Some("*".to_string());
                    }
                }
                Rule::agg_modifier => {
                    let mod_text = inner_pair.as_str();
                    if mod_text.starts_with("top") {
                        modifier = Some("top".to_string());
                    } else if mod_text.starts_with("bottom") {
                        modifier = Some("bottom".to_string());
                    }
                    // Extract number from modifier
                    for mod_inner in inner_pair.into_inner() {
                        if mod_inner.as_rule() == Rule::integer {
                            limit = Some(mod_inner.as_str().parse().unwrap_or(10));
                        }
                    }
                }
                Rule::percentile_values => {
                    let values: Vec<f64> = inner_pair
                        .into_inner()
                        .filter_map(|p| {
                            if p.as_rule() == Rule::number {
                                p.as_str().parse().ok()
                            } else {
                                None
                            }
                        })
                        .collect();
                    percentile_values = Some(values);
                }
                Rule::identifier => {
                    // This is the alias after "as"
                    alias = Some(inner_pair.as_str().to_string());
                }
                _ => {}
            }
        }

        Ok(Aggregation {
            function,
            field,
            alias,
            modifier,
            limit,
            percentile_values,
            rank_values,
            field_mutators,
        })
    }

    /// Parse group by list
    fn parse_group_by_list(&self, pair: pest::iterators::Pair<Rule>) -> Result<Vec<GroupBy>> {
        let mut group_by = Vec::new();

        for inner_pair in pair.into_inner() {
            if inner_pair.as_rule() == Rule::group_by_field {
                let mut field = String::new();
                let mut bucket_size = None;

                for field_inner in inner_pair.into_inner() {
                    match field_inner.as_rule() {
                        Rule::field_with_mutators => {
                            // Extract field name from field_with_mutators
                            for fwm_inner in field_inner.into_inner() {
                                if fwm_inner.as_rule() == Rule::field_name {
                                    field = fwm_inner.as_str().to_string();
                                    break;
                                }
                            }
                        }
                        Rule::integer => {
                            bucket_size = Some(field_inner.as_str().parse().unwrap_or(10));
                        }
                        _ => {}
                    }
                }

                group_by.push(GroupBy { field, bucket_size });
            }
        }

        Ok(group_by)
    }

    /// Parse a logical expression (AND/OR chain)
    fn parse_logical_expr(&self, pair: pest::iterators::Pair<Rule>, depth: usize) -> Result<AstNode> {
        let mut inner = pair.into_inner();

        // Parse first term
        let first_term_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing term in logical expression".to_string(),
            position: 0,
            query: None,
        })?;
        let mut left = self.parse_term(first_term_pair, depth + 1)?;

        // Process operator and term pairs
        while let Some(op_pair) = inner.next() {
            if op_pair.as_rule() != Rule::logical_op {
                return Err(TqlError::ParseError {
                    message: "Expected logical operator".to_string(),
                    position: 0,
                    query: None,
                });
            }

            let operator = op_pair.as_str().to_lowercase();

            let right_pair = inner.next().ok_or_else(|| TqlError::ParseError {
                message: "Missing right operand after logical operator".to_string(),
                position: 0,
                query: None,
            })?;
            let right = self.parse_term(right_pair, depth + 1)?;

            left = AstNode::LogicalOp(LogicalOpNode {
                operator,
                left: Box::new(left),
                right: Box::new(right),
            });
        }

        Ok(left)
    }

    /// Parse a term (NOT expression or primary)
    fn parse_term(&self, pair: pest::iterators::Pair<Rule>, depth: usize) -> Result<AstNode> {
        match pair.as_rule() {
            Rule::term => {
                // Term contains either not_expr or primary
                let inner_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
                    message: "Empty term".to_string(),
                    position: 0,
                    query: None,
                })?;
                self.parse_term(inner_pair, depth + 1)
            }
            Rule::not_expr => {
                let mut inner = pair.into_inner();
                let _op = inner.next(); // Skip the NOT operator
                let operand_pair = inner.next().ok_or_else(|| TqlError::ParseError {
                    message: "Missing operand after NOT".to_string(),
                    position: 0,
                    query: None,
                })?;
                let operand = self.parse_primary(operand_pair, depth + 1)?;

                Ok(AstNode::UnaryOp(UnaryOpNode {
                    operator: "not".to_string(),
                    operand: Box::new(operand),
                }))
            }
            Rule::primary => {
                self.parse_primary(pair, depth + 1)
            }
            _ => Err(TqlError::ParseError {
                message: format!("Unexpected rule in term: {:?}", pair.as_rule()),
                position: 0,
                query: None,
            }),
        }
    }

    /// Parse a primary expression (paren_expr or comparison)
    fn parse_primary(&self, pair: pest::iterators::Pair<Rule>, depth: usize) -> Result<AstNode> {
        match pair.as_rule() {
            Rule::primary => {
                let inner_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
                    message: "Empty primary".to_string(),
                    position: 0,
                    query: None,
                })?;
                self.parse_primary(inner_pair, depth + 1)
            }
            Rule::paren_expr => {
                let inner_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
                    message: "Empty parenthesized expression".to_string(),
                    position: 0,
                    query: None,
                })?;
                self.parse_logical_expr(inner_pair, depth + 1)
            }
            Rule::comparison => {
                self.parse_comparison(pair, depth + 1)
            }
            _ => Err(TqlError::ParseError {
                message: format!("Unexpected rule in primary: {:?}", pair.as_rule()),
                position: 0,
                query: None,
            }),
        }
    }

    /// Parse a comparison expression
    fn parse_comparison(&self, pair: pest::iterators::Pair<Rule>, _depth: usize) -> Result<AstNode> {
        let inner_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
            message: "Empty comparison".to_string(),
            position: 0,
            query: None,
        })?;

        match inner_pair.as_rule() {
            Rule::collection_comparison => self.parse_collection_comparison(inner_pair),
            Rule::between_comparison => self.parse_between_comparison(inner_pair),
            Rule::in_fields_comparison => self.parse_in_fields_comparison(inner_pair),
            Rule::is_null_comparison => self.parse_is_null_comparison(inner_pair),
            Rule::unary_comparison => self.parse_unary_comparison(inner_pair),
            Rule::binary_comparison => self.parse_binary_comparison(inner_pair),
            Rule::field_only_expression => self.parse_field_only_expression(inner_pair),
            _ => Err(TqlError::ParseError {
                message: format!("Unknown comparison type: {:?}", inner_pair.as_rule()),
                position: 0,
                query: None,
            }),
        }
    }

    /// Parse collection comparison (ANY/ALL/NONE field op value)
    fn parse_collection_comparison(&self, pair: pest::iterators::Pair<Rule>) -> Result<AstNode> {
        let mut inner = pair.into_inner();

        let coll_op_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing collection operator".to_string(),
            position: 0,
            query: None,
        })?;
        let operator = coll_op_pair.as_str().to_lowercase().replace(" ", "_");

        let field_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing field in collection comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let (field, field_mutators, type_hint) = self.parse_field_with_mutators(field_pair)?;

        let comp_op_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing comparison operator in collection comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let comparison_operator = self.normalize_operator(comp_op_pair.as_str());

        let value_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing value in collection comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let (value, _value_mutators) = self.parse_value_with_mutators(value_pair)?;

        Ok(AstNode::CollectionOp(CollectionOpNode {
            operator,
            field,
            comparison_operator,
            value,
            field_mutators,
            type_hint,
        }))
    }

    /// Parse between comparison (field between [val1, val2])
    fn parse_between_comparison(&self, pair: pest::iterators::Pair<Rule>) -> Result<AstNode> {
        let mut inner = pair.into_inner();

        let field_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing field in between comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let (field, field_mutators, type_hint) = self.parse_field_with_mutators(field_pair)?;

        let op_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing operator in between comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let operator = self.normalize_operator(op_pair.as_str());

        let list_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing value list in between comparison".to_string(),
            position: 0,
            query: None,
        })?;
        // list_value comes directly, not wrapped in value rule
        let value = self.parse_list(list_pair)?;

        Ok(AstNode::Comparison(ComparisonNode {
            field,
            operator,
            value: Some(value),
            field_mutators,
            value_mutators: None,
            type_hint,
        }))
    }

    /// Parse in fields comparison (value in [field1, field2])
    fn parse_in_fields_comparison(&self, _pair: pest::iterators::Pair<Rule>) -> Result<AstNode> {
        // This is a special case that would need custom handling
        // For now, return a placeholder
        Ok(AstNode::MatchAll)
    }

    /// Parse is null comparison (field IS NULL / IS NOT NULL)
    fn parse_is_null_comparison(&self, pair: pest::iterators::Pair<Rule>) -> Result<AstNode> {
        let mut inner = pair.into_inner();

        let field_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing field in is null comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let (field, field_mutators, type_hint) = self.parse_field_with_mutators(field_pair)?;

        let op_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing operator in is null comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let operator = self.normalize_operator(op_pair.as_str());

        Ok(AstNode::Comparison(ComparisonNode {
            field,
            operator,
            value: Some(Value::Null),
            field_mutators,
            value_mutators: None,
            type_hint,
        }))
    }

    /// Parse unary comparison (field EXISTS / field NOT EXISTS)
    fn parse_unary_comparison(&self, pair: pest::iterators::Pair<Rule>) -> Result<AstNode> {
        let mut inner = pair.into_inner();

        let field_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing field in unary comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let (field, field_mutators, type_hint) = self.parse_field_with_mutators(field_pair)?;

        let op_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing operator in unary comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let operator = self.normalize_operator(op_pair.as_str());

        Ok(AstNode::Comparison(ComparisonNode {
            field,
            operator,
            value: None,
            field_mutators,
            value_mutators: None,
            type_hint,
        }))
    }

    /// Parse binary comparison (field op value)
    fn parse_binary_comparison(&self, pair: pest::iterators::Pair<Rule>) -> Result<AstNode> {
        let mut inner = pair.into_inner();

        let field_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing field in binary comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let (field, field_mutators, type_hint) = self.parse_field_with_mutators(field_pair)?;

        let op_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing operator in binary comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let operator = self.normalize_operator(op_pair.as_str());

        let value_pair = inner.next().ok_or_else(|| TqlError::ParseError {
            message: "Missing value in binary comparison".to_string(),
            position: 0,
            query: None,
        })?;
        let (value, value_mutators) = self.parse_value_with_mutators(value_pair)?;

        Ok(AstNode::Comparison(ComparisonNode {
            field,
            operator,
            value: Some(value),
            field_mutators,
            value_mutators,
            type_hint,
        }))
    }

    /// Parse field-only expression (enrichment without filtering)
    /// Matches all records and applies mutators to the field
    fn parse_field_only_expression(&self, pair: pest::iterators::Pair<Rule>) -> Result<AstNode> {
        // field_only_expression contains field_with_mutators
        let field_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
            message: "Missing field in field-only expression".to_string(),
            position: 0,
            query: None,
        })?;

        let (field, field_mutators, type_hint) = self.parse_field_with_mutators(field_pair)?;

        // Create a comparison that always matches (exists with no value check)
        // This allows the field and mutators to be processed without filtering
        Ok(AstNode::Comparison(ComparisonNode {
            field,
            operator: "exists".to_string(),
            value: None,
            field_mutators,
            value_mutators: None,
            type_hint,
        }))
    }

    /// Parse field with mutators and type hint
    fn parse_field_with_mutators(&self, pair: pest::iterators::Pair<Rule>) -> Result<(String, Option<Vec<Mutator>>, Option<String>)> {
        let mut field = String::new();
        let mut mutators = Vec::new();
        let mut type_hint = None;

        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::field_name => {
                    field = inner_pair.as_str().to_string();
                }
                Rule::mutator => {
                    mutators.push(self.parse_mutator(inner_pair)?);
                }
                Rule::type_hint => {
                    for type_inner in inner_pair.into_inner() {
                        if type_inner.as_rule() == Rule::type_name {
                            type_hint = Some(type_inner.as_str().to_lowercase());
                        }
                    }
                }
                _ => {}
            }
        }

        let field_mutators = if mutators.is_empty() { None } else { Some(mutators) };
        Ok((field, field_mutators, type_hint))
    }

    /// Parse value with mutators
    fn parse_value_with_mutators(&self, pair: pest::iterators::Pair<Rule>) -> Result<(Value, Option<Vec<Mutator>>)> {
        let mut value = Value::Null;
        let mut mutators = Vec::new();

        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::value => {
                    value = self.parse_value(inner_pair)?;
                }
                Rule::mutator => {
                    mutators.push(self.parse_mutator(inner_pair)?);
                }
                _ => {}
            }
        }

        let value_mutators = if mutators.is_empty() { None } else { Some(mutators) };
        Ok((value, value_mutators))
    }

    /// Parse a value
    fn parse_value(&self, pair: pest::iterators::Pair<Rule>) -> Result<Value> {
        let inner_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
            message: "Empty value".to_string(),
            position: 0,
            query: None,
        })?;

        match inner_pair.as_rule() {
            Rule::string => self.parse_string(inner_pair),
            Rule::number => self.parse_number(inner_pair),
            Rule::boolean => Ok(Value::Boolean(inner_pair.as_str().to_lowercase() == "true")),
            Rule::null => Ok(Value::Null),
            Rule::list_value => self.parse_list(inner_pair),
            _ => Err(TqlError::ParseError {
                message: format!("Unknown value type: {:?}", inner_pair.as_rule()),
                position: 0,
                query: None,
            }),
        }
    }

    /// Parse a string value
    fn parse_string(&self, pair: pest::iterators::Pair<Rule>) -> Result<Value> {
        // string -> string_double/string_single
        let string_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
            message: "Empty string rule".to_string(),
            position: 0,
            query: None,
        })?;

        // string_double/string_single -> inner_double/inner_single (quotes are matched but not captured as pairs)
        let inner_pair = string_pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
            message: "No inner string content".to_string(),
            position: 0,
            query: None,
        })?;

        // inner_double/inner_single has the actual string content without quotes
        let content = inner_pair.as_str();

        // Handle escape sequences
        let unescaped = content
            .replace("\\n", "\n")
            .replace("\\r", "\r")
            .replace("\\t", "\t")
            .replace("\\\\", "\\")
            .replace("\\\"", "\"")
            .replace("\\'", "'");

        Ok(Value::String(unescaped))
    }

    /// Parse a number value
    fn parse_number(&self, pair: pest::iterators::Pair<Rule>) -> Result<Value> {
        let inner_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
            message: "Empty number".to_string(),
            position: 0,
            query: None,
        })?;

        match inner_pair.as_rule() {
            Rule::float => {
                let f = inner_pair.as_str().parse::<f64>().map_err(|_| TqlError::ParseError {
                    message: format!("Invalid float: {}", inner_pair.as_str()),
                    position: 0,
                    query: None,
                })?;
                Ok(Value::Float(f))
            }
            Rule::integer => {
                let i = inner_pair.as_str().parse::<i64>().map_err(|_| TqlError::ParseError {
                    message: format!("Invalid integer: {}", inner_pair.as_str()),
                    position: 0,
                    query: None,
                })?;
                Ok(Value::Integer(i))
            }
            _ => Err(TqlError::ParseError {
                message: format!("Unknown number type: {:?}", inner_pair.as_rule()),
                position: 0,
                query: None,
            }),
        }
    }

    /// Parse a list value
    fn parse_list(&self, pair: pest::iterators::Pair<Rule>) -> Result<Value> {
        let mut values = Vec::new();

        for inner_pair in pair.into_inner() {
            if inner_pair.as_rule() == Rule::value {
                values.push(self.parse_value(inner_pair)?);
            }
        }

        Ok(Value::List(values))
    }

    /// Parse a mutator
    fn parse_mutator(&self, pair: pest::iterators::Pair<Rule>) -> Result<Mutator> {
        let mut name = String::new();
        let mut args = Vec::new();

        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::mutator_name => {
                    name = inner_pair.as_str().to_string();
                }
                Rule::mutator_args => {
                    for arg_pair in inner_pair.into_inner() {
                        if arg_pair.as_rule() == Rule::mutator_arg {
                            args.push(self.parse_mutator_arg(arg_pair)?);
                        }
                    }
                }
                _ => {}
            }
        }

        Ok(Mutator { name, args })
    }

    /// Parse a mutator argument
    fn parse_mutator_arg(&self, pair: pest::iterators::Pair<Rule>) -> Result<Value> {
        let inner_pair = pair.into_inner().next().ok_or_else(|| TqlError::ParseError {
            message: "Empty mutator argument".to_string(),
            position: 0,
            query: None,
        })?;

        match inner_pair.as_rule() {
            Rule::string => self.parse_string(inner_pair),
            Rule::number => self.parse_number(inner_pair),
            Rule::boolean => Ok(Value::Boolean(inner_pair.as_str().to_lowercase() == "true")),
            Rule::null => Ok(Value::Null),
            Rule::identifier => Ok(Value::String(inner_pair.as_str().to_string())),
            _ => Err(TqlError::ParseError {
                message: format!("Invalid mutator argument type: {:?}", inner_pair.as_rule()),
                position: 0,
                query: None,
            }),
        }
    }

    /// Normalize operator to canonical form
    fn normalize_operator(&self, op: &str) -> String {
        let normalized = op.to_lowercase().replace(" ", "_");
        match normalized.as_str() {
            "=" => "eq".to_string(),
            "!=" => "ne".to_string(),
            ">" => "gt".to_string(),
            ">=" => "gte".to_string(),
            "<" => "lt".to_string(),
            "<=" => "lte".to_string(),
            "&&" => "and".to_string(),
            "||" => "or".to_string(),
            "!" => "not".to_string(),
            _ => normalized,
        }
    }

    /// Extract all field names referenced in a query
    ///
    /// # Arguments
    ///
    /// * `query` - The TQL query string
    ///
    /// # Returns
    ///
    /// A sorted list of unique field names
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let parser = TqlParser::new();
    /// let fields = parser.extract_fields("name eq 'John' AND age > 25").unwrap();
    /// assert_eq!(fields, vec!["age", "name"]);
    /// ```
    pub fn extract_fields(&self, query: &str) -> Result<Vec<String>> {
        let ast = self.parse(query)?;
        let mut fields = Vec::new();
        self.collect_fields(&ast, &mut fields);
        fields.sort();
        fields.dedup();
        Ok(fields)
    }

    /// Recursively collect field names from AST
    fn collect_fields(&self, node: &AstNode, fields: &mut Vec<String>) {
        match node {
            AstNode::Comparison(comp) => {
                fields.push(comp.field.clone());
            }
            AstNode::LogicalOp(logical) => {
                self.collect_fields(&logical.left, fields);
                self.collect_fields(&logical.right, fields);
            }
            AstNode::UnaryOp(unary) => {
                self.collect_fields(&unary.operand, fields);
            }
            AstNode::CollectionOp(coll) => {
                fields.push(coll.field.clone());
            }
            AstNode::GeoExpr(geo) => {
                fields.push(geo.field.clone());
                if let Some(ref cond) = geo.conditions {
                    self.collect_fields(cond, fields);
                }
            }
            AstNode::NslookupExpr(nslookup) => {
                fields.push(nslookup.field.clone());
                if let Some(ref cond) = nslookup.conditions {
                    self.collect_fields(cond, fields);
                }
            }
            AstNode::QueryWithStats(qws) => {
                self.collect_fields(&qws.filter, fields);
                for agg in &qws.stats.aggregations {
                    if let Some(ref field) = agg.field {
                        if field != "*" {
                            fields.push(field.clone());
                        }
                    }
                }
                for group_by in &qws.stats.group_by {
                    fields.push(group_by.field.clone());
                }
            }
            AstNode::StatsExpr(stats) => {
                for agg in &stats.aggregations {
                    if let Some(ref field) = agg.field {
                        if field != "*" {
                            fields.push(field.clone());
                        }
                    }
                }
                for group_by in &stats.group_by {
                    fields.push(group_by.field.clone());
                }
            }
            AstNode::MatchAll => {}
        }
    }
}

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

    #[test]
    fn test_parser_creation() {
        let parser = TqlParser::new();
        assert_eq!(parser.max_depth, TqlParser::MAX_QUERY_DEPTH);
    }

    #[test]
    fn test_empty_query() {
        let parser = TqlParser::new();
        let result = parser.parse("").unwrap();
        assert!(matches!(result, AstNode::MatchAll));
    }

    #[test]
    fn test_whitespace_only_query() {
        let parser = TqlParser::new();
        let result = parser.parse("   \t\n  ").unwrap();
        assert!(matches!(result, AstNode::MatchAll));
    }

    #[test]
    fn test_custom_max_depth() {
        let parser = TqlParser::with_max_depth(100);
        assert_eq!(parser.max_depth, 100);
    }
}