Skip to main content

fel_core/
parser.rs

1//! FEL hand-rolled recursive descent parser with operator precedence.
2//!
3//! Chaining multiple `==` / `!=` or multiple comparison operators is a **parse error**; write
4//! explicit conjunction (e.g. `0 <= $x and $x <= 10`).
5//!
6//! Private `parse_*` / `current` / `advance` implement the precedence ladder listed below.
7//!
8//! `peek().clone()` clones token payloads when inspecting or taking ownership; unavoidable
9//! for heap-backed tokens until the lexer borrows source text directly.
10#![allow(clippy::missing_docs_in_private_items)]
11
12/// Operator precedence (lowest → highest):
13/// 0: let...in, if...then...else
14/// 1: ternary ? :
15/// 2: or
16/// 3: and
17/// 4: = !=
18/// 5: < > <= >=
19/// 6: in, not in
20/// 7: ??
21/// 8: + - &
22/// 9: * / %
23/// 10: unary not, unary -
24/// 11: postfix . []
25use rust_decimal::prelude::*;
26
27use std::collections::HashSet;
28
29use crate::ast::*;
30use crate::error::{Error, ParseError};
31use crate::lexer::{Lexer, SpannedToken, Token};
32
33/// Recursive-descent parser over a [`SpannedToken`] stream (use [`parse`] to build from source).
34pub struct Parser {
35    tokens: Vec<SpannedToken>,
36    pos: usize,
37    /// When > 0, suppress `in` as membership operator (inside let-value).
38    no_in_depth: usize,
39    recursion_depth: usize,
40    max_recursion_depth: usize,
41}
42
43/// Parse a FEL expression string into an AST.
44pub fn parse(input: &str) -> Result<Expr, Error> {
45    let mut lexer = Lexer::new(input);
46    let tokens = lexer.tokenize().map_err(Error::Parse)?;
47    let mut parser = Parser {
48        tokens,
49        pos: 0,
50        no_in_depth: 0,
51        recursion_depth: 0,
52        max_recursion_depth: 32,
53    };
54    let expr = parser.parse_expression()?;
55    if !parser.at_eof() {
56        return Err(parser.parse_err_current(format!(
57            "unexpected token {:?} at position {}",
58            parser.current().token,
59            parser.current().span.start
60        )));
61    }
62    Ok(expr)
63}
64
65impl Parser {
66    fn parse_err_token(&self, tok: &SpannedToken, message: impl Into<String>) -> Error {
67        Error::Parse(ParseError::with_span(
68            tok.span.start..tok.span.end,
69            message.into(),
70        ))
71    }
72
73    fn parse_err_current(&self, message: impl Into<String>) -> Error {
74        self.parse_err_token(self.current(), message)
75    }
76
77    fn current(&self) -> &SpannedToken {
78        &self.tokens[self.pos.min(self.tokens.len() - 1)]
79    }
80
81    fn peek(&self) -> &Token {
82        &self.current().token
83    }
84
85    fn at_eof(&self) -> bool {
86        matches!(self.peek(), Token::Eof)
87    }
88
89    fn advance(&mut self) -> &SpannedToken {
90        let tok = &self.tokens[self.pos.min(self.tokens.len() - 1)];
91        if self.pos < self.tokens.len() {
92            self.pos += 1;
93        }
94        tok
95    }
96
97    fn expect(&mut self, expected: &Token) -> Result<(), Error> {
98        if self.peek() == expected {
99            self.advance();
100            Ok(())
101        } else {
102            Err(self.parse_err_current(format!("expected {expected:?}, got {:?}", self.peek())))
103        }
104    }
105
106    fn eat_identifier(&mut self) -> Result<String, Error> {
107        match self.peek().clone() {
108            Token::Identifier(name) => {
109                self.advance();
110                Ok(name)
111            }
112            other => Err(self.parse_err_current(format!("expected identifier, got {other:?}"))),
113        }
114    }
115
116    fn parse_expression_with_in_allowed(&mut self) -> Result<Expr, Error> {
117        let saved_no_in = self.no_in_depth;
118        self.no_in_depth = 0;
119        let result = self.parse_expression();
120        self.no_in_depth = saved_no_in;
121        result
122    }
123
124    // ── Expression (entry point) ────────────────────────────────
125
126    fn parse_expression(&mut self) -> Result<Expr, Error> {
127        self.parse_let_or_if()
128    }
129
130    fn parse_let_or_if(&mut self) -> Result<Expr, Error> {
131        self.recursion_depth += 1;
132        if self.recursion_depth > self.max_recursion_depth {
133            self.recursion_depth -= 1;
134            return Err(self.parse_err_current(format!(
135                "expression nesting exceeds maximum depth of {}",
136                self.max_recursion_depth
137            )));
138        }
139        let result = self.parse_let_or_if_inner();
140        self.recursion_depth -= 1;
141        result
142    }
143
144    fn parse_let_or_if_inner(&mut self) -> Result<Expr, Error> {
145        // let <name> = <value> in <body>
146        if matches!(self.peek(), Token::Let) {
147            self.advance(); // let
148            let name = self.eat_identifier()?;
149            self.expect(&Token::Eq)?;
150            // Suppress top-level `in` as membership in let-value.
151            self.no_in_depth += 1;
152            let value = self.parse_ternary()?;
153            self.no_in_depth -= 1;
154            self.expect(&Token::In)?;
155            let body = self.parse_let_or_if()?;
156            return Ok(Expr::LetBinding {
157                name,
158                value: Box::new(value),
159                body: Box::new(body),
160            });
161        }
162
163        // if <cond> then <then> else <else>
164        if matches!(self.peek(), Token::If) {
165            // Disambiguate: if followed by identifier+( could be function call if()
166            // Check for if...then pattern (keyword form)
167            if self.is_if_then_else() {
168                self.advance(); // if
169                let condition = self.parse_ternary()?;
170                self.expect(&Token::Then)?;
171                let then_branch = self.parse_let_or_if()?;
172                self.expect(&Token::Else)?;
173                let else_branch = self.parse_let_or_if()?;
174                return Ok(Expr::IfThenElse {
175                    condition: Box::new(condition),
176                    then_branch: Box::new(then_branch),
177                    else_branch: Box::new(else_branch),
178                });
179            }
180        }
181
182        self.parse_ternary()
183    }
184
185    /// Look ahead to determine if this is `if ... then ... else` (keyword form)
186    /// vs `if(...)` (function call form).
187    fn is_if_then_else(&self) -> bool {
188        let starts_with_paren = matches!(
189            self.tokens.get(self.pos + 1).map(|token| &token.token),
190            Some(Token::LParen)
191        );
192
193        if self.pos + 1 >= self.tokens.len() {
194            return false;
195        }
196
197        // Scan only this expression. A nested `if(...)` function in an array,
198        // object, or argument list must not see the outer keyword form's `then`.
199        let mut depth = 0;
200        let mut i = self.pos + 1;
201        while i < self.tokens.len() {
202            match &self.tokens[i].token {
203                Token::Then if depth == 0 => return true,
204                Token::Comma if starts_with_paren && depth == 1 => return false,
205                Token::Comma | Token::RParen | Token::RBracket | Token::RBrace if depth == 0 => {
206                    return false;
207                }
208                Token::LParen | Token::LBracket | Token::LBrace => depth += 1,
209                Token::RParen | Token::RBracket | Token::RBrace => {
210                    if depth > 0 {
211                        depth -= 1;
212                    } else {
213                        return false;
214                    }
215                }
216                Token::Eof => return false,
217                _ => {}
218            }
219            i += 1;
220        }
221        false
222    }
223
224    // ── Ternary ─────────────────────────────────────────────────
225
226    fn parse_ternary(&mut self) -> Result<Expr, Error> {
227        let expr = self.parse_logical_or()?;
228        if matches!(self.peek(), Token::Question) {
229            self.advance(); // ?
230            let then_branch = self.parse_let_or_if()?;
231            self.expect(&Token::Colon)?;
232            let else_branch = self.parse_let_or_if()?;
233            Ok(Expr::Ternary {
234                condition: Box::new(expr),
235                then_branch: Box::new(then_branch),
236                else_branch: Box::new(else_branch),
237            })
238        } else {
239            Ok(expr)
240        }
241    }
242
243    // ── Logical ─────────────────────────────────────────────────
244
245    fn parse_logical_or(&mut self) -> Result<Expr, Error> {
246        let mut left = self.parse_logical_and()?;
247        while matches!(self.peek(), Token::Or) {
248            self.advance();
249            let right = self.parse_logical_and()?;
250            left = Expr::BinaryOp {
251                op: BinaryOp::Or,
252                left: Box::new(left),
253                right: Box::new(right),
254            };
255        }
256        Ok(left)
257    }
258
259    fn parse_logical_and(&mut self) -> Result<Expr, Error> {
260        let mut left = self.parse_equality()?;
261        while matches!(self.peek(), Token::And) {
262            self.advance();
263            let right = self.parse_equality()?;
264            left = Expr::BinaryOp {
265                op: BinaryOp::And,
266                left: Box::new(left),
267                right: Box::new(right),
268            };
269        }
270        Ok(left)
271    }
272
273    // ── Equality / Comparison ───────────────────────────────────
274
275    fn parse_equality(&mut self) -> Result<Expr, Error> {
276        let left = self.parse_comparison()?;
277        let op = match self.peek() {
278            Token::Eq => BinaryOp::Eq,
279            Token::NotEq => BinaryOp::NotEq,
280            _ => return Ok(left),
281        };
282        self.advance();
283        let right = self.parse_comparison()?;
284        if matches!(self.peek(), Token::Eq | Token::NotEq) {
285            return Err(self.parse_err_current(
286                "chained equality is not supported; use explicit logical conjunction",
287            ));
288        }
289        Ok(Expr::BinaryOp {
290            op,
291            left: Box::new(left),
292            right: Box::new(right),
293        })
294    }
295
296    fn parse_comparison(&mut self) -> Result<Expr, Error> {
297        let left = self.parse_membership()?;
298        let op = match self.peek() {
299            Token::Lt => BinaryOp::Lt,
300            Token::Gt => BinaryOp::Gt,
301            Token::LtEq => BinaryOp::LtEq,
302            Token::GtEq => BinaryOp::GtEq,
303            _ => return Ok(left),
304        };
305        self.advance();
306        let right = self.parse_membership()?;
307        if matches!(
308            self.peek(),
309            Token::Lt | Token::Gt | Token::LtEq | Token::GtEq
310        ) {
311            return Err(self.parse_err_current(
312                "chained comparisons are not supported; use explicit logical conjunction",
313            ));
314        }
315        Ok(Expr::BinaryOp {
316            op,
317            left: Box::new(left),
318            right: Box::new(right),
319        })
320    }
321
322    // ── Membership ──────────────────────────────────────────────
323
324    fn parse_membership(&mut self) -> Result<Expr, Error> {
325        let left = self.parse_null_coalesce()?;
326
327        if self.no_in_depth > 0 {
328            return Ok(left);
329        }
330
331        // Check for `in` or `not in`
332        if matches!(self.peek(), Token::Not) {
333            // Peek ahead for `not in`
334            if self.pos + 1 < self.tokens.len()
335                && matches!(self.tokens[self.pos + 1].token, Token::In)
336            {
337                self.advance(); // not
338                self.advance(); // in
339                let right = self.parse_null_coalesce()?;
340                return Ok(Expr::Membership {
341                    value: Box::new(left),
342                    container: Box::new(right),
343                    negated: true,
344                });
345            }
346        }
347
348        if matches!(self.peek(), Token::In) {
349            self.advance(); // in
350            let right = self.parse_null_coalesce()?;
351            return Ok(Expr::Membership {
352                value: Box::new(left),
353                container: Box::new(right),
354                negated: false,
355            });
356        }
357
358        Ok(left)
359    }
360
361    // ── Null coalesce ───────────────────────────────────────────
362
363    fn parse_null_coalesce(&mut self) -> Result<Expr, Error> {
364        let mut left = self.parse_addition()?;
365        while matches!(self.peek(), Token::DoubleQuestion) {
366            self.advance();
367            let right = self.parse_addition()?;
368            left = Expr::NullCoalesce {
369                left: Box::new(left),
370                right: Box::new(right),
371            };
372        }
373        Ok(left)
374    }
375
376    // ── Arithmetic ──────────────────────────────────────────────
377
378    fn parse_addition(&mut self) -> Result<Expr, Error> {
379        let mut left = self.parse_multiplication()?;
380        loop {
381            let op = match self.peek() {
382                Token::Plus => BinaryOp::Add,
383                Token::Minus => BinaryOp::Sub,
384                Token::Ampersand => BinaryOp::Concat,
385                _ => break,
386            };
387            self.advance();
388            let right = self.parse_multiplication()?;
389            left = Expr::BinaryOp {
390                op,
391                left: Box::new(left),
392                right: Box::new(right),
393            };
394        }
395        Ok(left)
396    }
397
398    fn parse_multiplication(&mut self) -> Result<Expr, Error> {
399        let mut left = self.parse_unary()?;
400        loop {
401            let op = match self.peek() {
402                Token::Star => BinaryOp::Mul,
403                Token::Slash => BinaryOp::Div,
404                Token::Percent => BinaryOp::Mod,
405                _ => break,
406            };
407            self.advance();
408            let right = self.parse_unary()?;
409            left = Expr::BinaryOp {
410                op,
411                left: Box::new(left),
412                right: Box::new(right),
413            };
414        }
415        Ok(left)
416    }
417
418    // ── Unary ───────────────────────────────────────────────────
419
420    fn parse_unary(&mut self) -> Result<Expr, Error> {
421        let is_bang = matches!(self.peek(), Token::Bang);
422        if matches!(self.peek(), Token::Not | Token::Bang) {
423            // Make sure it's not `not in` (handled by membership) — `!` cannot mean `! in`
424            if !is_bang
425                && self.pos + 1 < self.tokens.len()
426                && matches!(self.tokens[self.pos + 1].token, Token::In)
427            {
428                return self.parse_postfix();
429            }
430            self.advance();
431            let operand = self.parse_unary()?;
432            return Ok(Expr::UnaryOp {
433                op: UnaryOp::Not,
434                operand: Box::new(operand),
435                bang: is_bang,
436            });
437        }
438        if matches!(self.peek(), Token::Minus) {
439            // Disambiguate: unary minus vs binary minus
440            // Unary if at start of expression or after an operator/opening bracket
441            self.advance();
442            let operand = self.parse_unary()?;
443            return Ok(Expr::UnaryOp {
444                op: UnaryOp::Neg,
445                operand: Box::new(operand),
446                bang: false,
447            });
448        }
449        self.parse_postfix()
450    }
451
452    // ── Postfix (dot/bracket access) ────────────────────────────
453
454    fn parse_postfix(&mut self) -> Result<Expr, Error> {
455        let mut expr = self.parse_atom()?;
456        loop {
457            match self.peek() {
458                Token::Dot => {
459                    self.advance();
460                    let name = self.eat_identifier()?;
461                    expr = self.attach_postfix_segment(expr, PathSegment::Dot(name));
462                }
463                Token::LBracket => {
464                    self.advance();
465                    let seg = self.parse_bracket_segment("")?;
466                    expr = self.attach_postfix_segment(expr, seg);
467                }
468                _ => break,
469            }
470        }
471        Ok(expr)
472    }
473
474    fn attach_postfix_segment(&mut self, expr: Expr, seg: PathSegment) -> Expr {
475        Expr::PostfixAccess {
476            expr: Box::new(expr),
477            path: vec![seg],
478        }
479    }
480
481    /// Parse `[*]` or `[N]` after the opening `[` has been consumed; consumes `]`.
482    fn parse_bracket_segment(&mut self, bracket_context: &str) -> Result<PathSegment, Error> {
483        let seg = match self.peek().clone() {
484            Token::Star => {
485                self.advance();
486                PathSegment::Wildcard
487            }
488            Token::Number(n) => {
489                let token = self.current().clone();
490                if !n.fract().is_zero() || n.is_sign_negative() {
491                    return Err(self.parse_err_token(&token, format!(
492                        "expected non-negative integer index in {bracket_context}brackets, got {n}"
493                    )));
494                }
495                let Some(idx_u64) = n.to_u64() else {
496                    return Err(self.parse_err_token(
497                        &token,
498                        format!("index out of range in {bracket_context}brackets, got {n}"),
499                    ));
500                };
501                let Ok(idx) = usize::try_from(idx_u64) else {
502                    return Err(self.parse_err_token(
503                        &token,
504                        format!("index out of range in {bracket_context}brackets, got {n}"),
505                    ));
506                };
507                self.advance();
508                PathSegment::Index(idx)
509            }
510            other => {
511                return Err(self.parse_err_current(format!(
512                    "expected number or * in {bracket_context}brackets, got {other:?}"
513                )));
514            }
515        };
516        self.expect(&Token::RBracket)?;
517        Ok(seg)
518    }
519
520    // ── Atoms ───────────────────────────────────────────────────
521
522    fn parse_atom(&mut self) -> Result<Expr, Error> {
523        match self.peek().clone() {
524            Token::Number(n) => {
525                self.advance();
526                Ok(Expr::Number(n))
527            }
528            Token::StringLit(s) => {
529                let s = s.clone();
530                self.advance();
531                Ok(Expr::String(s))
532            }
533            Token::True => {
534                self.advance();
535                Ok(Expr::Boolean(true))
536            }
537            Token::False => {
538                self.advance();
539                Ok(Expr::Boolean(false))
540            }
541            Token::Null => {
542                self.advance();
543                Ok(Expr::Null)
544            }
545            Token::DateLiteral(s) => {
546                let s = s.clone();
547                self.advance();
548                Ok(Expr::DateLiteral(s))
549            }
550            Token::DateTimeLiteral(s) => {
551                let s = s.clone();
552                self.advance();
553                Ok(Expr::DateTimeLiteral(s))
554            }
555            Token::Dollar => {
556                self.advance(); // $
557                self.parse_field_ref()
558            }
559            Token::At => {
560                self.advance(); // @
561                self.parse_context_ref()
562            }
563            Token::LParen => {
564                self.advance();
565                let expr = self.parse_expression_with_in_allowed()?;
566                self.expect(&Token::RParen)?;
567                Ok(expr)
568            }
569            Token::LBracket => self.parse_array_literal(),
570            Token::LBrace => self.parse_object_literal(),
571            Token::Identifier(name) => {
572                let name = name.clone();
573                self.advance();
574                // Check for function call
575                if matches!(self.peek(), Token::LParen) {
576                    self.parse_function_call(name)
577                } else {
578                    // Bare identifier — let-bound variable or unqualified field path
579                    Ok(Expr::VarRef { name, path: vec![] })
580                }
581            }
582            Token::If => {
583                // if(...) function form
584                self.advance();
585                if matches!(self.peek(), Token::LParen) {
586                    self.parse_function_call("if".to_string())
587                } else {
588                    Err(self.parse_err_current("unexpected 'if' — use if...then...else or if(...)"))
589                }
590            }
591            _ => Err(self.parse_err_current(format!("unexpected token {:?}", self.peek()))),
592        }
593    }
594
595    fn parse_field_ref(&mut self) -> Result<Expr, Error> {
596        let mut name: Option<String> = None;
597        let mut path = Vec::new();
598
599        // Optional identifier after $
600        if let Token::Identifier(n) = self.peek().clone() {
601            name = Some(n.clone());
602            self.advance();
603        }
604
605        // Path segments
606        loop {
607            match self.peek() {
608                Token::Dot => {
609                    self.advance();
610                    let seg_name = self.eat_identifier()?;
611                    path.push(PathSegment::Dot(seg_name));
612                }
613                Token::LBracket => {
614                    self.advance();
615                    path.push(self.parse_bracket_segment("field ref ")?);
616                }
617                _ => break,
618            }
619        }
620
621        Ok(Expr::FieldRef { name, path })
622    }
623
624    fn parse_context_ref(&mut self) -> Result<Expr, Error> {
625        let name = self.eat_identifier()?;
626        let mut called = false;
627        let mut arg = None;
628        let mut tail = Vec::new();
629
630        // Optional argument: @instance('name')
631        if matches!(self.peek(), Token::LParen) {
632            called = true;
633            self.advance();
634            if let Token::StringLit(s) = self.peek().clone() {
635                arg = Some(s.clone());
636                self.advance();
637            }
638            self.expect(&Token::RParen)?;
639        }
640
641        // Dot-chain: @instance('name').field.subfield
642        while matches!(self.peek(), Token::Dot) {
643            self.advance();
644            tail.push(self.eat_identifier()?);
645        }
646
647        Ok(Expr::ContextRef {
648            name,
649            called,
650            arg,
651            tail,
652        })
653    }
654
655    fn parse_function_call(&mut self, name: String) -> Result<Expr, Error> {
656        self.expect(&Token::LParen)?;
657        let mut args = Vec::new();
658        if !matches!(self.peek(), Token::RParen) {
659            args.push(self.parse_expression_with_in_allowed()?);
660            while matches!(self.peek(), Token::Comma) {
661                self.advance();
662                args.push(self.parse_expression_with_in_allowed()?);
663            }
664        }
665        self.expect(&Token::RParen)?;
666        Ok(Expr::FunctionCall { name, args })
667    }
668
669    fn parse_array_literal(&mut self) -> Result<Expr, Error> {
670        self.expect(&Token::LBracket)?;
671        let mut elements = Vec::new();
672        if !matches!(self.peek(), Token::RBracket) {
673            elements.push(self.parse_expression_with_in_allowed()?);
674            while matches!(self.peek(), Token::Comma) {
675                self.advance();
676                elements.push(self.parse_expression_with_in_allowed()?);
677            }
678        }
679        self.expect(&Token::RBracket)?;
680        Ok(Expr::Array(elements))
681    }
682
683    fn parse_object_literal(&mut self) -> Result<Expr, Error> {
684        self.expect(&Token::LBrace)?;
685        let mut entries = Vec::new();
686        let mut seen_keys = HashSet::new();
687        if !matches!(self.peek(), Token::RBrace) {
688            let entry = self.parse_object_entry()?;
689            seen_keys.insert(entry.0.clone());
690            entries.push(entry);
691            while matches!(self.peek(), Token::Comma) {
692                self.advance();
693                // Allow trailing comma
694                if matches!(self.peek(), Token::RBrace) {
695                    break;
696                }
697                let entry = self.parse_object_entry()?;
698                if !seen_keys.insert(entry.0.clone()) {
699                    return Err(self.parse_err_current(format!(
700                        "duplicate key '{}' in object literal",
701                        entry.0
702                    )));
703                }
704                entries.push(entry);
705            }
706        }
707        self.expect(&Token::RBrace)?;
708        Ok(Expr::Object(entries))
709    }
710
711    fn parse_object_entry(&mut self) -> Result<(String, Expr), Error> {
712        let key = match self.peek().clone() {
713            Token::Identifier(name) => {
714                self.advance();
715                name.clone()
716            }
717            Token::StringLit(s) => {
718                self.advance();
719                s.clone()
720            }
721            _ => {
722                return Err(
723                    self.parse_err_current(format!("expected object key, got {:?}", self.peek()))
724                );
725            }
726        };
727        self.expect(&Token::Colon)?;
728        let value = self.parse_expression_with_in_allowed()?;
729        Ok((key, value))
730    }
731}
732
733#[cfg(test)]
734mod tests {
735    #![allow(clippy::missing_docs_in_private_items)]
736    use super::*;
737
738    #[test]
739    fn test_parse_number() {
740        let expr = parse("42").unwrap();
741        assert_eq!(expr, Expr::Number(rust_decimal::Decimal::from(42)));
742    }
743
744    #[test]
745    fn test_parse_string() {
746        let expr = parse("\"hello\"").unwrap();
747        assert_eq!(expr, Expr::String("hello".into()));
748    }
749
750    #[test]
751    fn test_parse_boolean() {
752        assert_eq!(parse("true").unwrap(), Expr::Boolean(true));
753        assert_eq!(parse("false").unwrap(), Expr::Boolean(false));
754    }
755
756    #[test]
757    fn test_parse_null() {
758        assert_eq!(parse("null").unwrap(), Expr::Null);
759    }
760
761    #[test]
762    fn test_parse_field_ref() {
763        let expr = parse("$name").unwrap();
764        assert_eq!(
765            expr,
766            Expr::FieldRef {
767                name: Some("name".into()),
768                path: vec![]
769            }
770        );
771    }
772
773    #[test]
774    fn test_parse_bare_dollar() {
775        let expr = parse("$").unwrap();
776        assert_eq!(
777            expr,
778            Expr::FieldRef {
779                name: None,
780                path: vec![]
781            }
782        );
783    }
784
785    #[test]
786    fn test_parse_field_with_path() {
787        let expr = parse("$address.city").unwrap();
788        assert_eq!(
789            expr,
790            Expr::FieldRef {
791                name: Some("address".into()),
792                path: vec![PathSegment::Dot("city".into())]
793            }
794        );
795    }
796
797    /// Spec: fel-grammar.md §7 — precedence-preserving parse tree.
798    /// `1 + 2 * 3` must parse as Add(1, Mul(2, 3)), not Mul(Add(1, 2), 3).
799    #[test]
800    fn test_parse_arithmetic_precedence() {
801        let expr = parse("1 + 2 * 3").unwrap();
802        match expr {
803            Expr::BinaryOp {
804                op: BinaryOp::Add,
805                left,
806                right,
807            } => {
808                assert_eq!(*left, Expr::Number(Decimal::from(1)));
809                match *right {
810                    Expr::BinaryOp {
811                        op: BinaryOp::Mul,
812                        left: rl,
813                        right: rr,
814                    } => {
815                        assert_eq!(*rl, Expr::Number(Decimal::from(2)));
816                        assert_eq!(*rr, Expr::Number(Decimal::from(3)));
817                    }
818                    other => panic!("expected Mul on right, got {other:?}"),
819                }
820            }
821            other => panic!("expected Add at top, got {other:?}"),
822        }
823    }
824
825    /// Spec: fel-grammar.md §7 — function call with nested field ref + wildcard.
826    #[test]
827    fn test_parse_function_call() {
828        let expr = parse("sum($items[*].qty)").unwrap();
829        match expr {
830            Expr::FunctionCall { name, args } => {
831                assert_eq!(name, "sum");
832                assert_eq!(args.len(), 1);
833                assert_eq!(
834                    args[0],
835                    Expr::FieldRef {
836                        name: Some("items".into()),
837                        path: vec![PathSegment::Wildcard, PathSegment::Dot("qty".into())],
838                    }
839                );
840            }
841            other => panic!("expected FunctionCall, got {other:?}"),
842        }
843    }
844
845    /// Spec: fel-grammar.md §7 — if...then...else keyword form.
846    #[test]
847    fn test_parse_if_then_else() {
848        let expr = parse("if $x > 0 then 'positive' else 'non-positive'").unwrap();
849        match expr {
850            Expr::IfThenElse {
851                condition,
852                then_branch,
853                else_branch,
854            } => {
855                // condition: $x > 0
856                match *condition {
857                    Expr::BinaryOp {
858                        op: BinaryOp::Gt,
859                        left,
860                        right,
861                    } => {
862                        assert_eq!(
863                            *left,
864                            Expr::FieldRef {
865                                name: Some("x".into()),
866                                path: vec![]
867                            }
868                        );
869                        assert_eq!(*right, Expr::Number(Decimal::from(0)));
870                    }
871                    other => panic!("expected Gt condition, got {other:?}"),
872                }
873                assert_eq!(*then_branch, Expr::String("positive".into()));
874                assert_eq!(*else_branch, Expr::String("non-positive".into()));
875            }
876            other => panic!("expected IfThenElse, got {other:?}"),
877        }
878    }
879
880    /// Spec: fel-grammar.md §7 — if(...) function call form.
881    #[test]
882    fn test_parse_if_function() {
883        let expr = parse("if($x > 0, 'yes', 'no')").unwrap();
884        match expr {
885            Expr::FunctionCall { name, args } => {
886                assert_eq!(name, "if");
887                assert_eq!(args.len(), 3);
888                match &args[0] {
889                    Expr::BinaryOp {
890                        op: BinaryOp::Gt, ..
891                    } => {}
892                    other => panic!("expected Gt as first arg, got {other:?}"),
893                }
894                assert_eq!(args[1], Expr::String("yes".into()));
895                assert_eq!(args[2], Expr::String("no".into()));
896            }
897            other => panic!("expected FunctionCall, got {other:?}"),
898        }
899    }
900
901    #[test]
902    fn test_parse_if_function_inside_keyword_condition() {
903        let expr = parse("if if(null, null, null) then 1 else 2").unwrap();
904        match expr {
905            Expr::IfThenElse { condition, .. } => match *condition {
906                Expr::FunctionCall { name, args } => {
907                    assert_eq!(name, "if");
908                    assert_eq!(args.as_slice(), &[Expr::Null, Expr::Null, Expr::Null]);
909                }
910                other => panic!("expected if() FunctionCall condition, got {other:?}"),
911            },
912            other => panic!("expected IfThenElse, got {other:?}"),
913        }
914    }
915
916    #[test]
917    fn test_parse_nested_if_function_does_not_see_outer_then() {
918        let expr = parse("if [if(null, null, null)] then typeOf(1) else floor(2)[2]").unwrap();
919        match expr {
920            Expr::IfThenElse { condition, .. } => match *condition {
921                Expr::Array(elements) => match elements.as_slice() {
922                    [Expr::FunctionCall { name, args }] => {
923                        assert_eq!(name, "if");
924                        assert_eq!(args.as_slice(), &[Expr::Null, Expr::Null, Expr::Null]);
925                    }
926                    other => panic!("expected array containing if() call, got {other:?}"),
927                },
928                other => panic!("expected array condition, got {other:?}"),
929            },
930            other => panic!("expected IfThenElse, got {other:?}"),
931        }
932    }
933
934    #[test]
935    fn test_parse_parenthesized_keyword_if_condition() {
936        let expr = parse("if ($x > 0) and true then 'yes' else 'no'").unwrap();
937        match expr {
938            Expr::IfThenElse { condition, .. } => match *condition {
939                Expr::BinaryOp {
940                    op: BinaryOp::And, ..
941                } => {}
942                other => panic!("expected And condition, got {other:?}"),
943            },
944            other => panic!("expected IfThenElse, got {other:?}"),
945        }
946    }
947
948    #[test]
949    fn test_parse_membership_inside_let_value_containers() {
950        let expr = parse(
951            "let aa = {'object': null in [], 'array': [null in []], 'call': startsWith(null in [], true)} in aa",
952        )
953        .unwrap();
954        match expr {
955            Expr::LetBinding { value, .. } => match *value {
956                Expr::Object(entries) => {
957                    let [object_entry, array_entry, call_entry] = entries.as_slice() else {
958                        panic!("expected three object entries, got {entries:?}");
959                    };
960                    assert!(matches!(object_entry.1, Expr::Membership { .. }));
961                    match &array_entry.1 {
962                        Expr::Array(elements) => {
963                            assert!(matches!(elements.as_slice(), [Expr::Membership { .. }]));
964                        }
965                        other => panic!("expected array entry, got {other:?}"),
966                    }
967                    match &call_entry.1 {
968                        Expr::FunctionCall { args, .. } => {
969                            assert!(matches!(
970                                args.as_slice(),
971                                [Expr::Membership { .. }, Expr::Boolean(true)]
972                            ));
973                        }
974                        other => panic!("expected function call entry, got {other:?}"),
975                    }
976                }
977                other => panic!("expected object let value, got {other:?}"),
978            },
979            other => panic!("expected LetBinding, got {other:?}"),
980        }
981    }
982
983    /// Spec: fel-grammar.md §7 — ternary `? :` with condition, branches.
984    #[test]
985    fn test_parse_ternary() {
986        let expr = parse("$x > 0 ? 'yes' : 'no'").unwrap();
987        match expr {
988            Expr::Ternary {
989                condition,
990                then_branch,
991                else_branch,
992            } => {
993                match *condition {
994                    Expr::BinaryOp {
995                        op: BinaryOp::Gt,
996                        left,
997                        right,
998                    } => {
999                        assert_eq!(
1000                            *left,
1001                            Expr::FieldRef {
1002                                name: Some("x".into()),
1003                                path: vec![]
1004                            }
1005                        );
1006                        assert_eq!(*right, Expr::Number(Decimal::from(0)));
1007                    }
1008                    other => panic!("expected Gt condition, got {other:?}"),
1009                }
1010                assert_eq!(*then_branch, Expr::String("yes".into()));
1011                assert_eq!(*else_branch, Expr::String("no".into()));
1012            }
1013            other => panic!("expected Ternary, got {other:?}"),
1014        }
1015    }
1016
1017    /// Spec: fel-grammar.md §7 — let binding structure.
1018    #[test]
1019    fn test_parse_let_binding() {
1020        let expr = parse("let x = 5 in x + 1").unwrap();
1021        match expr {
1022            Expr::LetBinding { name, value, body } => {
1023                assert_eq!(name, "x");
1024                assert_eq!(*value, Expr::Number(Decimal::from(5)));
1025                match *body {
1026                    Expr::BinaryOp {
1027                        op: BinaryOp::Add,
1028                        left,
1029                        right,
1030                    } => {
1031                        assert_eq!(
1032                            *left,
1033                            Expr::VarRef {
1034                                name: "x".into(),
1035                                path: vec![]
1036                            }
1037                        );
1038                        assert_eq!(*right, Expr::Number(Decimal::from(1)));
1039                    }
1040                    other => panic!("expected Add in body, got {other:?}"),
1041                }
1042            }
1043            other => panic!("expected LetBinding, got {other:?}"),
1044        }
1045    }
1046
1047    /// Spec: fel-grammar.md §7 — `in` membership with array literal.
1048    #[test]
1049    fn test_parse_membership() {
1050        let expr = parse("$status in ['active', 'pending']").unwrap();
1051        match expr {
1052            Expr::Membership {
1053                value,
1054                container,
1055                negated,
1056            } => {
1057                assert!(!negated);
1058                assert_eq!(
1059                    *value,
1060                    Expr::FieldRef {
1061                        name: Some("status".into()),
1062                        path: vec![]
1063                    }
1064                );
1065                match *container {
1066                    Expr::Array(ref elems) => {
1067                        assert_eq!(elems.len(), 2);
1068                        assert_eq!(elems[0], Expr::String("active".into()));
1069                        assert_eq!(elems[1], Expr::String("pending".into()));
1070                    }
1071                    other => panic!("expected Array container, got {other:?}"),
1072                }
1073            }
1074            other => panic!("expected Membership, got {other:?}"),
1075        }
1076    }
1077
1078    /// Spec: fel-grammar.md §7 — `not in` membership.
1079    #[test]
1080    fn test_parse_not_in() {
1081        let expr = parse("$status not in ['deleted']").unwrap();
1082        match expr {
1083            Expr::Membership {
1084                value,
1085                container,
1086                negated,
1087            } => {
1088                assert!(negated);
1089                assert_eq!(
1090                    *value,
1091                    Expr::FieldRef {
1092                        name: Some("status".into()),
1093                        path: vec![]
1094                    }
1095                );
1096                match *container {
1097                    Expr::Array(ref elems) => {
1098                        assert_eq!(elems.len(), 1);
1099                        assert_eq!(elems[0], Expr::String("deleted".into()));
1100                    }
1101                    other => panic!("expected Array container, got {other:?}"),
1102                }
1103            }
1104            other => panic!("expected Membership, got {other:?}"),
1105        }
1106    }
1107
1108    /// Spec: fel-grammar.md §7 — null coalesce `??` structure.
1109    #[test]
1110    fn test_parse_null_coalesce() {
1111        let expr = parse("$x ?? 0").unwrap();
1112        match expr {
1113            Expr::NullCoalesce { left, right } => {
1114                assert_eq!(
1115                    *left,
1116                    Expr::FieldRef {
1117                        name: Some("x".into()),
1118                        path: vec![]
1119                    }
1120                );
1121                assert_eq!(*right, Expr::Number(Decimal::from(0)));
1122            }
1123            other => panic!("expected NullCoalesce, got {other:?}"),
1124        }
1125    }
1126
1127    #[test]
1128    fn test_parse_context_ref() {
1129        let expr = parse("@index").unwrap();
1130        assert_eq!(
1131            expr,
1132            Expr::ContextRef {
1133                name: "index".into(),
1134                called: false,
1135                arg: None,
1136                tail: vec![]
1137            }
1138        );
1139    }
1140
1141    #[test]
1142    fn test_parse_context_ref_with_arg() {
1143        let expr = parse("@instance('priorYear').total").unwrap();
1144        assert_eq!(
1145            expr,
1146            Expr::ContextRef {
1147                name: "instance".into(),
1148                called: true,
1149                arg: Some("priorYear".into()),
1150                tail: vec!["total".into()]
1151            }
1152        );
1153    }
1154
1155    #[test]
1156    fn test_parse_date_literal() {
1157        let expr = parse("@2024-01-15").unwrap();
1158        assert_eq!(expr, Expr::DateLiteral("@2024-01-15".into()));
1159    }
1160
1161    #[test]
1162    fn test_parse_object_literal() {
1163        let expr = parse("{name: 'Alice', age: 30}").unwrap();
1164        assert!(matches!(expr, Expr::Object(_)));
1165    }
1166
1167    #[test]
1168    fn test_parse_array_literal() {
1169        let expr = parse("[1, 2, 3]").unwrap();
1170        assert!(matches!(expr, Expr::Array(_)));
1171    }
1172
1173    #[test]
1174    fn test_parse_wildcard() {
1175        let expr = parse("$items[*].name").unwrap();
1176        assert_eq!(
1177            expr,
1178            Expr::FieldRef {
1179                name: Some("items".into()),
1180                path: vec![PathSegment::Wildcard, PathSegment::Dot("name".into())]
1181            }
1182        );
1183    }
1184
1185    #[test]
1186    fn parse_bracket_rejects_fractional_index() {
1187        let err = parse("$rows[1.5].id").unwrap_err();
1188        assert!(
1189            err.to_string().contains("non-negative integer index"),
1190            "got: {err}"
1191        );
1192    }
1193
1194    #[test]
1195    fn parse_bracket_error_messages_differ_by_context() {
1196        let postfix = parse("items[foo]").unwrap_err().to_string();
1197        let field_ref = parse("$rows[foo]").unwrap_err().to_string();
1198        assert!(postfix.contains("brackets"), "postfix: {postfix}");
1199        assert!(
1200            field_ref.contains("field ref") && field_ref.contains("brackets"),
1201            "field ref: {field_ref}"
1202        );
1203    }
1204
1205    #[test]
1206    fn test_parse_bracket_index_field_ref_and_postfix() {
1207        assert_eq!(
1208            parse("$rows[2].id").unwrap(),
1209            Expr::FieldRef {
1210                name: Some("rows".into()),
1211                path: vec![PathSegment::Index(2), PathSegment::Dot("id".into())]
1212            }
1213        );
1214        let expr = parse("items[1]").unwrap();
1215        match expr {
1216            Expr::PostfixAccess { expr, path } => {
1217                assert_eq!(
1218                    *expr,
1219                    Expr::VarRef {
1220                        name: "items".into(),
1221                        path: vec![]
1222                    }
1223                );
1224                assert_eq!(path, vec![PathSegment::Index(1)]);
1225            }
1226            other => panic!("expected PostfixAccess, got {other:?}"),
1227        }
1228    }
1229
1230    #[test]
1231    fn bare_identifier_postfix_is_postfix_access() {
1232        let expr = parse("x.a.b[0]").unwrap();
1233        assert!(matches!(expr, Expr::PostfixAccess { .. }));
1234    }
1235
1236    #[test]
1237    fn parenthesized_expression_postfix_is_nested_postfix() {
1238        let expr = parse("(1 + 2).a.b").unwrap();
1239        match expr {
1240            Expr::PostfixAccess { expr, path } => {
1241                assert!(matches!(*expr, Expr::PostfixAccess { .. }));
1242                assert_eq!(path, vec![PathSegment::Dot("b".into())]);
1243            }
1244            other => panic!("expected PostfixAccess, got {other:?}"),
1245        }
1246    }
1247
1248    #[test]
1249    fn test_parse_unary_not() {
1250        let expr = parse("not true").unwrap();
1251        assert!(matches!(
1252            expr,
1253            Expr::UnaryOp {
1254                op: UnaryOp::Not,
1255                ..
1256            }
1257        ));
1258    }
1259
1260    #[test]
1261    fn test_parse_complex_nested() {
1262        parse("if $items[*].qty > 0 then sum($items[*].qty) * $rate else 0").unwrap();
1263    }
1264
1265    #[test]
1266    fn test_parse_let_in_does_not_trigger_membership() {
1267        // `in` in `let x = $a in x + 1` should be the let-body separator,
1268        // not the membership operator
1269        let expr = parse("let x = $a in x + 1").unwrap();
1270        assert!(matches!(expr, Expr::LetBinding { .. }));
1271    }
1272
1273    #[test]
1274    fn test_parse_let_with_parenthesized_in() {
1275        // Parens reset the no_in suppression, so the inner `in` is membership
1276        let expr = parse("let x = (1 in [1, 2, 3]) in x").unwrap();
1277        match expr {
1278            Expr::LetBinding { value, body, .. } => {
1279                assert!(matches!(*value, Expr::Membership { negated: false, .. }));
1280                assert!(matches!(*body, Expr::VarRef { .. }));
1281            }
1282            other => panic!("expected LetBinding, got {other:?}"),
1283        }
1284    }
1285
1286    #[test]
1287    fn test_parse_let_nested_parens_restore_suppression() {
1288        // After the closing paren, `in` should still be the let-body separator
1289        let expr = parse("let y = ($a + 1) in y * 2").unwrap();
1290        match expr {
1291            Expr::LetBinding { name, .. } => assert_eq!(name, "y"),
1292            other => panic!("expected LetBinding, got {other:?}"),
1293        }
1294    }
1295
1296    /// Kills `src/parser.rs:153:30` — `replace -= with /= in
1297    /// Parser::parse_let_or_if_inner` on `self.no_in_depth -= 1`. The
1298    /// counter is incremented before parsing the let-value to suppress
1299    /// `in` as membership; if it's never decremented (mutant: `/= 1`
1300    /// is a no-op), then subsequent `in` operators in the let body
1301    /// would be silently skipped. Pin this by parsing a let whose body
1302    /// uses `in` as membership.
1303    #[test]
1304    fn test_parse_let_body_in_membership_after_value() {
1305        let expr = parse("let x = 1 in x in [1, 2]").expect("must parse");
1306        match expr {
1307            Expr::LetBinding { name, body, .. } => {
1308                assert_eq!(name, "x");
1309                match *body {
1310                    Expr::Membership { negated, .. } => {
1311                        assert!(!negated, "expected non-negated membership");
1312                    }
1313                    other => panic!("expected Membership in let-body, got {other:?}"),
1314                }
1315            }
1316            other => panic!("expected LetBinding, got {other:?}"),
1317        }
1318    }
1319
1320    /// Pins the Eof-clamp invariant in `current()` and `advance()`
1321    /// (lines 78, 90, 91). Architecture-review F4 noted that the
1322    /// Category A equivalence claim for these mutants rested on
1323    /// un-enumerated call-site discipline; a direct test converts the
1324    /// ambiguous "no input distinguishes" claim into a pinned
1325    /// invariant. Specifically, repeatedly calling `advance()` and
1326    /// `current()` after parsing must clamp `pos` and never panic on
1327    /// out-of-bounds token access — even if `pos` reaches
1328    /// `tokens.len()`. Mutants on `tokens.len() - 1` arithmetic
1329    /// (`- → +|/`) that turn the clamp upper bound into something
1330    /// `>= tokens.len()` will panic here when `pos.min(...) == len`.
1331    #[test]
1332    fn parser_clamps_pos_past_eof_without_panic() {
1333        use crate::lexer::Lexer;
1334        let mut lexer = Lexer::new("42");
1335        let tokens = lexer.tokenize().expect("tokenize");
1336        let mut parser = Parser {
1337            tokens,
1338            pos: 0,
1339            no_in_depth: 0,
1340            recursion_depth: 0,
1341            max_recursion_depth: 32,
1342        };
1343        // Parse the expression to consume tokens up to Eof.
1344        let _ = parser.parse_expression().expect("parse");
1345        // Try to advance past Eof many times; the advance() guard at
1346        // line 91 (`pos < tokens.len()`) plus the current() clamp at
1347        // line 78 (`pos.min(tokens.len() - 1)`) must hold together.
1348        for _ in 0..16 {
1349            let _ = parser.advance();
1350            let cur = parser.current();
1351            assert!(
1352                matches!(cur.token, Token::Eof),
1353                "current() past Eof must return Eof, got {:?}",
1354                cur.token
1355            );
1356        }
1357    }
1358}