cel_parser/

ast.rs

//! A span-carrying CEL expression AST, built by [`AstContext`] as an
//! alternative to [`DynSegmentContext`](crate::parser_context::DynSegmentContext)'s direct
//! execution. Consumed as-is by adam-lang (method bodies/initializers), the language server, the
//! formatter, and the future macro-compilation backend. Carries no resolved types or operator
//! overloads: resolution and type/range validation are deferred to a later, separate phase.
//!
//! Array nodes preserve optional recursive type ascriptions exactly as written — for example
//! `[0, 1]: [i32]`, `[]: [[i32]]`, or `[]: [Custom]` — using unresolved [`TypeExpr`] leaves so a
//! later checker can resolve names through built-in CEL types or a host registry. Recursive
//! tuple, array, and callable types compose without per-shape host registrations.

use std::any::Any;
use std::ffi::CString;

use proc_macro2::Span;

use crate::op_table::OpLookup;
use crate::parser_context::ParserContext;
use crate::type_expr::TypeExpr;

/// Source range of an AST node: start of its first token to end of its last.
///
/// Two `proc_macro2::Span`s (not a [`crate::SourceSpan`]) so the future macro-compilation backend
/// can attach `compile_error!`/`quote_spanned!`, and so the (separate, deferred) comment/trivia
/// pass can call `Span::source_text()`. `crate::SourceSpan` remains the `Send + Sync` wire format
/// used only at the `CELError` diagnostic boundary; this AST is an internal parser artifact using
/// the same span currency the parser itself already does.
///
/// `proc_macro2::Span` isn't `PartialEq`, so neither is this type — shape tests should match
/// structurally and ignore spans rather than assert exact span equality.
///
/// # Examples
/// See [`Self::for_text`].
#[derive(Clone, Copy, Debug)]
pub struct ExprSpan {
    /// Start of the first token of the node.
    pub start: Span,
    /// End of the last token of the node.
    pub end: Span,
}

impl ExprSpan {
    /// A single-token range where start and end coincide.
    fn point(span: Span) -> Self {
        ExprSpan {
            start: span,
            end: span,
        }
    }

    /// Creates a span whose `source_text()` returns exactly `text`, by
    /// tokenizing it and taking the resulting token's span. For hand-built
    /// AST nodes (not produced by parsing real source), this gives leaves
    /// like a type name or literal a span the formatter can read back
    /// text from, the same way `cel-rs-macros` already does internally.
    ///
    /// - Precondition: `text` tokenizes to exactly one token tree.
    ///
    /// - Complexity: O(n) in `text.len()` (it lexes `text`).
    ///
    /// # Examples
    ///
    /// ```
    /// use cel_parser::ExprSpan;
    ///
    /// let span = ExprSpan::for_text("i64");
    /// assert_eq!(span.start.source_text().as_deref(), Some("i64"));
    /// ```
    #[must_use]
    pub fn for_text(text: &str) -> Self {
        let tokens: proc_macro2::TokenStream = text
            .parse()
            .expect("ExprSpan::for_text: text must be valid tokens");
        let mut iter = tokens.into_iter();
        let first = iter
            .next()
            .expect("ExprSpan::for_text: text must be non-empty");
        debug_assert!(
            iter.next().is_none(),
            "ExprSpan::for_text: text must tokenize to exactly one token"
        );
        let span = first.span();
        ExprSpan {
            start: span,
            end: span,
        }
    }
}

/// A CEL literal, one variant per concrete Rust type [`crate::ParserContext::push_literal`] can
/// receive from `push_literal_token` in `lib.rs`.
///
/// `Byte` literals (`b'A'`) and `u8`-suffixed integer literals (`65u8`) both arrive as `u8` and
/// are indistinguishable here — both become `Literal::U8`; a formatter that must reproduce exact
/// original syntax should re-slice the node's original source text from its span instead of
/// relying on this enum to recover lexical form.
///
/// # Examples
/// See [`crate::Parser::parse_tokens_ast`] for retained literal values.
#[derive(Clone, Debug, PartialEq)]
pub enum Literal {
    /// `i8` literal (e.g. `1i8`).
    I8(i8),
    /// `i16` literal (e.g. `1i16`).
    I16(i16),
    /// `i32` literal, the default integer suffix (e.g. `1` or `1i32`).
    I32(i32),
    /// `i64` literal (e.g. `1i64`).
    I64(i64),
    /// `i128` literal (e.g. `1i128`).
    I128(i128),
    /// `isize` literal (e.g. `1isize`).
    Isize(isize),
    /// `u8` literal or byte literal (e.g. `1u8` or `b'A'`).
    U8(u8),
    /// `u16` literal (e.g. `1u16`).
    U16(u16),
    /// `u32` literal (e.g. `1u32`).
    U32(u32),
    /// `u64` literal (e.g. `1u64`).
    U64(u64),
    /// `u128` literal (e.g. `1u128`).
    U128(u128),
    /// `usize` literal (e.g. `1usize`).
    Usize(usize),
    /// `f32` literal (e.g. `1.0f32`).
    F32(f32),
    /// `f64` literal, the default float suffix (e.g. `1.0` or `1.0f64`).
    F64(f64),
    /// Boolean literal (`true`/`false`).
    Bool(bool),
    /// Character literal (e.g. `'a'`).
    Char(char),
    /// String literal (e.g. `"x"`).
    Str(String),
    /// Byte-string literal (e.g. `b"x"`).
    ByteStr(Vec<u8>),
    /// C-string literal (e.g. `c"x"`).
    CStr(CString),
    /// Unit (`()`).
    Unit,
}

/// The two short-circuiting logical operators.
///
/// # Examples
/// See [`crate::ParserContext::apply_logical`] for lazy logical composition.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum LogicalOp {
    /// `&&`.
    And,
    /// `||`.
    Or,
}

/// A parsed CEL expression with source spans on every node.
///
/// Built by [`AstContext`]; consumed as-is by adam-lang (method
/// bodies/initializers), the language server (hover/goto), the formatter, and the future
/// macro-compilation backend. Carries no resolved types or operator overloads — resolution is
/// deferred to a later, separate type-checking phase.
///
/// `Logical` is kept distinct from `If` (rather than desugaring `a || b` to
/// `if a { true } else { b }`, which is how [`DynSegmentContext`](crate::parser_context::DynSegmentContext)
/// executes it) so a formatter can round-trip `a || b` as `a || b`.
///
/// # Examples
/// See [`crate::Parser::parse_tokens_ast`] for building retained expressions.
#[derive(Clone, Debug)]
pub enum Expr {
    /// A named record constructor, unresolved until semantic checking.
    ///
    /// # Examples
    /// ```
    /// use cel_parser::{AstContext, Expr, OpLookup, Parser};
    /// let expr = Parser::<AstContext>::new(OpLookup::new())
    ///     .parse_str_ast("Point { x: 1.0 }").unwrap();
    /// assert!(matches!(expr, Expr::Struct { fields, .. } if fields.len() == 1));
    /// ```
    Struct {
        /// The constructor's type name, not a value reference.
        name: String,
        /// The constructor name token's span.
        name_span: ExprSpan,
        /// Field labels and expressions in their written evaluation order.
        fields: Vec<RecordInit>,
        /// The whole constructor, including the closing brace.
        span: ExprSpan,
    },
    /// A literal value (`10i32`, `"x"`, `true`, `()`, ...).
    Literal {
        /// The literal's value.
        value: Literal,
        /// The literal token's span.
        span: ExprSpan,
    },
    /// A bare identifier reference or zero-arg builtin lookup (`x`, `pi`) — unresolved.
    Ident {
        /// The identifier's name.
        name: String,
        /// The identifier token's span.
        span: ExprSpan,
    },
    /// A prefix (arity 1) or infix (arity 2) operator application (`-x`, `a + b`, `a == b`).
    Op {
        /// The operator's name (e.g. `"+"`, `"-"`, `"=="`).
        name: String,
        /// The operand sub-expressions, in source order.
        operands: Vec<Expr>,
        /// The span of the whole operator application.
        span: ExprSpan,
    },
    /// A call: `callee(args...)` — the grammar's `"()"` operator.
    Apply {
        /// The expression being called.
        callee: Box<Expr>,
        /// The argument sub-expressions, in source order.
        args: Vec<Expr>,
        /// The span of the whole call, including its argument list.
        span: ExprSpan,
    },
    /// A direct receiver operation (`receiver.name` or `receiver.name(args...)`).
    ///
    /// The label is not an identifier reference. Type and overload resolution are deferred.
    ///
    /// # Examples
    /// ```
    /// use cel_parser::{AstContext, Expr, OpLookup, Parser};
    /// let expr = Parser::<AstContext>::new(OpLookup::new()).parse_str_ast("a.x()").unwrap();
    /// assert!(matches!(expr, Expr::Member { args: Some(args), .. } if args.is_empty()));
    /// ```
    Member {
        /// The receiver, evaluated before explicit arguments.
        receiver: Box<Expr>,
        /// The operation's name.
        name: String,
        /// The member name token's span.
        name_span: ExprSpan,
        /// Explicit arguments in source order; `None` preserves property spelling.
        args: Option<Vec<Expr>>,
        /// The span from the receiver through the name or closing parenthesis.
        span: ExprSpan,
    },
    /// A tuple literal (`(a, b, ...)`; a 1-tuple is `(a,)`).
    Tuple {
        /// The element sub-expressions, in source order.
        elements: Vec<Expr>,
        /// The span of the whole tuple, including its parentheses.
        span: ExprSpan,
    },
    /// An array literal (`[a, b, ...]`, `[a, b]: [T]`, or `[]: [T]`). An unannotated empty array
    /// is still rejected by the grammar (see <https://github.com/stlab/cel-rs/issues/212>), but
    /// a typed empty array is recorded here with `elements.is_empty()`. `type_annotation` stores
    /// the complete recursive array type exactly as written, including nested arrays and custom
    /// leaf names such as `Custom`. Whether the elements share one type, whether
    /// `type_annotation` names a complete array type are deferred to the later type-checking phase (see the module doc
    /// comment), same as `TupleIndex`'s deferred bounds check.
    Array {
        /// The element sub-expressions, in source order.
        elements: Vec<Expr>,
        /// The optional declared array type, as written after `:`.
        type_annotation: Option<TypeExpr>,
        /// The span from the `:` token through the end of the declared type, when present.
        annotation_span: Option<ExprSpan>,
        /// The span of the whole array literal, including its brackets and any annotation.
        span: ExprSpan,
    },
    /// A tuple index (`base.N`). Whether `base` is actually a tuple and `N` is in range is
    /// unchecked here — deferred to the type-checking phase (see the module doc comment).
    TupleIndex {
        /// The expression being indexed.
        base: Box<Expr>,
        /// The index.
        index: usize,
        /// The span from the start of `base` through the index token.
        span: ExprSpan,
    },
    /// An `if cond { then } else { else_ }` expression.
    If {
        /// The condition.
        cond: Box<Expr>,
        /// The then-branch.
        then_branch: Box<Expr>,
        /// The else-branch, or `None` if no `else`/`else if` was written.
        else_branch: Option<Box<Expr>>,
        /// The span of the whole `if`/`else` construct.
        span: ExprSpan,
    },
    /// A short-circuiting `&&`/`||`.
    Logical {
        /// Which logical operator.
        op: LogicalOp,
        /// The left-hand side.
        lhs: Box<Expr>,
        /// The right-hand side.
        rhs: Box<Expr>,
        /// The span of the whole logical expression.
        span: ExprSpan,
    },
    /// A cast (`expr as Type`). Whether `type_name` is a recognized type and whether a
    /// conversion from `expr`'s type exists is unchecked here — deferred to the type-checking
    /// phase (see the module doc comment), same as `TupleIndex`'s deferred bounds check.
    Cast {
        /// The expression being converted.
        expr: Box<Expr>,
        /// The target type's name, as written (e.g. `"i32"`) - unresolved.
        type_name: String,
        /// The span of the whole `expr as Type` construct.
        span: ExprSpan,
    },
    /// A closure literal (`|x: i32| x + 1`, or `|| 1i32` with no parameters).
    Closure {
        /// The closure's declared parameters, in source order.
        params: Vec<ClosureParam>,
        /// The closure's body expression.
        body: Box<Expr>,
        /// The span of the whole closure literal, from its opening `|`/`||` through `body`.
        span: ExprSpan,
    },
}

impl Expr {
    /// Returns this node's source span.
    ///
    /// # Examples
    /// ```
    /// use cel_parser::{AstContext, OpLookup, Parser};
    /// let expr = Parser::<AstContext>::new(OpLookup::new()).parse_str_ast("1 + 2").unwrap();
    /// assert_eq!(expr.span().start.start().column, 0);
    /// assert_eq!(expr.span().end.end().column, 5);
    /// ```
    pub fn span(&self) -> ExprSpan {
        match self {
            Expr::Literal { span, .. }
            | Expr::Struct { span, .. }
            | Expr::Ident { span, .. }
            | Expr::Op { span, .. }
            | Expr::Apply { span, .. }
            | Expr::Member { span, .. }
            | Expr::Tuple { span, .. }
            | Expr::Array { span, .. }
            | Expr::TupleIndex { span, .. }
            | Expr::If { span, .. }
            | Expr::Logical { span, .. }
            | Expr::Cast { span, .. }
            | Expr::Closure { span, .. } => *span,
        }
    }
}

/// One required record field initializer, retaining its written name, span, and value.
///
/// # Examples
/// ```
/// use cel_parser::{AstContext, Expr, OpLookup, Parser};
/// let expr = Parser::<AstContext>::new(OpLookup::new())
///     .parse_str_ast("Point { x: value }").unwrap();
/// if let Expr::Struct { fields, .. } = expr {
///     assert_eq!(fields[0].name, "x");
/// }
/// ```
#[derive(Clone, Debug)]
pub struct RecordInit {
    /// The field label, not an identifier reference.
    pub name: String,
    /// The field label token's span.
    pub name_span: ExprSpan,
    /// The source-order value expression.
    pub value: Expr,
}

/// One `closure_param = identifier ":" type_expression` — a closure literal's declared
/// parameter.
///
/// # Examples
/// ```
/// use cel_parser::{AstContext, Expr, OpLookup, Parser};
/// let expr = Parser::<AstContext>::new(OpLookup::new()).parse_str_ast("|x: i32| x").unwrap();
/// let Expr::Closure { params, .. } = expr else { unreachable!() };
/// assert_eq!(params[0].name, "x");
/// ```
#[derive(Clone, Debug)]
pub struct ClosureParam {
    /// The parameter's declared name.
    pub name: String,
    /// The name token's span.
    pub name_span: ExprSpan,
    /// The parameter's declared, unresolved type.
    pub type_expr: crate::TypeExpr,
}

/// Reports reserved or repeated parameter names without resolving their type annotations.
///
/// - Complexity: Expected O(n + b) time and O(n) space for n parameters and b name bytes.
pub(crate) fn closure_parameter_diagnostics(params: &[ClosureParam]) -> Vec<crate::ParseError> {
    let mut names = std::collections::HashSet::with_capacity(params.len());
    params
        .iter()
        .filter_map(|param| {
            let message = if matches!(param.name.as_str(), "if" | "else" | "as" | "true" | "false")
            {
                "reserved keyword is not a closure parameter name"
            } else if !names.insert(param.name.as_str()) {
                "duplicate closure parameter name"
            } else {
                return None;
            };
            Some(crate::ParseError::new_range(
                message,
                param.name_span.start,
                param.name_span.end,
            ))
        })
        .collect()
}

/// Converts a statically-known literal value into its [`Literal`] variant, transferring owned buffers.
///
/// - Precondition: `T` is one of the concrete types `push_literal_token` (`lib.rs`) pushes:
///   the signed/unsigned integer widths, `f32`/`f64`, `bool`, `char`, `String`, `Vec<u8>`,
///   `CString`, or `()`.
fn to_literal<T: 'static>(value: T) -> Literal {
    // Taking an Option transfers even CString without constructing a replacement buffer.
    let mut value = Some(value);
    let any = &mut value as &mut dyn Any;
    macro_rules! map {
        ($($t:ty => $variant:path),+ $(,)?) => {
            $( if let Some(x) = any.downcast_mut::<Option<$t>>() {
                return $variant(x.take().expect("literal is transferred once"));
            } )+
        };
    }
    map! {
        i8 => Literal::I8, i16 => Literal::I16, i32 => Literal::I32, i64 => Literal::I64,
        i128 => Literal::I128, isize => Literal::Isize,
        u8 => Literal::U8, u16 => Literal::U16, u32 => Literal::U32, u64 => Literal::U64,
        u128 => Literal::U128, usize => Literal::Usize,
        f32 => Literal::F32, f64 => Literal::F64,
        bool => Literal::Bool, char => Literal::Char, String => Literal::Str,
        Vec<u8> => Literal::ByteStr, CString => Literal::CStr,
    }
    if any.is::<Option<()>>() {
        return Literal::Unit;
    }
    unreachable!("push_literal called with an unsupported literal type")
}

/// [`ParserContext`] implementation that builds a span-carrying [`Expr`] tree instead of
/// executing. Consults no [`OpLookup`], inspects no runtime types, and never fails on semantic
/// grounds — resolution and type/range checking are deferred to a later, separate
/// type-checking phase (see the module doc comment).
///
/// # Examples
///
/// ```rust
/// use cel_parser::{AstContext, ParserContext};
/// use proc_macro2::Span;
///
/// let mut ctx = AstContext::new_context();
/// ctx.push_literal(10i32, Span::call_site());
/// ```
#[derive(Debug, Default)]
pub struct AstContext {
    /// Finished sub-trees; a completed parse leaves exactly one.
    values: Vec<Expr>,
}

impl AstContext {
    /// Removes and returns the top node.
    ///
    /// - Precondition: at least one node is present.
    fn pop(&mut self) -> Expr {
        self.values
            .pop()
            .expect("operand present on AST value stack")
    }

    /// Removes and returns the top `n` nodes, in source order.
    ///
    /// - Precondition: at least `n` nodes are present.
    /// - Complexity: O(n) time and space for the returned nodes.
    fn pop_n(&mut self, n: usize) -> Vec<Expr> {
        let at = self.values.len() - n;
        self.values.split_off(at)
    }

    /// Consumes the context, returning the single parsed expression.
    ///
    /// - Precondition: parsing completed successfully (exactly one node remains).
    ///
    /// # Examples
    /// ```
    /// use cel_parser::{AstContext, ParserContext, Expr, Literal};
    /// let mut context = AstContext::new_context();
    /// context.push_literal(7i32, proc_macro2::Span::call_site());
    /// assert!(matches!(context.into_expr(), Expr::Literal { value: Literal::I32(7), .. }));
    /// ```
    pub fn into_expr(mut self) -> Expr {
        debug_assert_eq!(
            self.values.len(),
            1,
            "a successfully parsed expression leaves exactly one node"
        );
        self.pop()
    }
}

impl ParserContext for AstContext {
    /// Defers closure annotation resolution to semantic checking or compilation.
    fn resolves_closure_types() -> bool {
        false
    }

    /// Creates an empty syntax stack.
    fn new_context() -> Self {
        AstContext { values: Vec::new() }
    }

    /// Creates an independent empty syntax stack.
    fn new_fragment(&self) -> Self {
        AstContext { values: Vec::new() }
    }

    /// Transfers one supported literal into a leaf node without copying owned buffers.
    fn push_literal<T: 'static + Clone>(&mut self, value: T, span: Span) {
        self.values.push(Expr::Literal {
            value: to_literal(value),
            span: ExprSpan::point(span),
        });
    }

    /// Records an identifier, ordinary call, or operator with source-order operands.
    ///
    /// - Precondition: the stack contains `arity` operands, including a callee for `"()"`.
    /// - Complexity: O(a + b) time and space for a operands and b name bytes.
    fn apply_op(
        &mut self,
        _op_lookup: &OpLookup,
        name: &str,
        arity: usize,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        let span = ExprSpan { start, end };
        if arity == 0 {
            self.values.push(Expr::Ident {
                name: name.to_string(),
                span,
            });
        } else if name == "()" {
            let mut operands = self.pop_n(arity); // [callee, arg1, ...]
            let callee = operands.remove(0);
            self.values.push(Expr::Apply {
                callee: Box::new(callee),
                args: operands,
                span,
            });
        } else {
            let operands = self.pop_n(arity); // arity 1 = prefix, 2 = infix
            self.values.push(Expr::Op {
                name: name.to_string(),
                operands,
                span,
            });
        }
        Ok(())
    }

    /// Records member spelling and source-order operands without resolving their types.
    ///
    /// - Complexity: O(n) in the number of explicit arguments.
    fn apply_member(
        &mut self,
        _lookup: &OpLookup,
        name: &str,
        name_span: ExprSpan,
        explicit_args: Option<usize>,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        debug_assert!(self.values.len() > explicit_args.unwrap_or(0));
        let args = explicit_args.map(|count| self.pop_n(count));
        let receiver = self.pop();
        self.values.push(Expr::Member {
            receiver: Box::new(receiver),
            name: name.to_string(),
            name_span,
            args,
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Records source-order field names and values without resolving a constructor.
    ///
    /// - Complexity: O(f) in the number of fields.
    fn make_record(
        &mut self,
        _lookup: &OpLookup,
        name: &str,
        name_span: ExprSpan,
        fields: Vec<(String, ExprSpan)>,
        _ambient_start: usize,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        let values = self.pop_n(fields.len());
        let fields = fields
            .into_iter()
            .zip(values)
            .map(|((name, name_span), value)| RecordInit {
                name,
                name_span,
                value,
            })
            .collect();
        self.values.push(Expr::Struct {
            name: name.to_string(),
            name_span,
            fields,
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Records a lazy logical operation without replacing it with conditional syntax.
    ///
    /// - Precondition: `name` is `"&&"` or `"||"`; each side contains one expression.
    fn apply_logical(
        &mut self,
        name: &str,
        mut rhs: Self,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        let op = match name {
            "||" => LogicalOp::Or,
            "&&" => LogicalOp::And,
            other => unreachable!("apply_logical called with unsupported operator `{other}`"),
        };
        let lhs = self.pop();
        debug_assert_eq!(
            rhs.values.len(),
            1,
            "rhs fragment produces exactly one value"
        );
        let rhs_expr = rhs.pop();
        self.values.push(Expr::Logical {
            op,
            lhs: Box::new(lhs),
            rhs: Box::new(rhs_expr),
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Records one conditional, preserving an absent `else` rather than synthesizing syntax.
    ///
    /// - Precondition: the condition and each supplied branch contain one expression.
    fn join2(
        &mut self,
        mut then_fragment: Self,
        else_fragment: Option<Self>,
        start: Span,
        end: Span,
    ) -> anyhow::Result<()> {
        let cond = self.pop();
        debug_assert_eq!(
            then_fragment.values.len(),
            1,
            "then fragment produces exactly one value"
        );
        let then_branch = then_fragment.pop();
        let else_branch = else_fragment.map(|mut fragment| {
            debug_assert_eq!(
                fragment.values.len(),
                1,
                "else fragment produces exactly one value"
            );
            Box::new(fragment.pop())
        });
        self.values.push(Expr::If {
            cond: Box::new(cond),
            then_branch: Box::new(then_branch),
            else_branch,
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Collects source-order elements into a tuple, representing the empty tuple as unit.
    ///
    /// - Precondition: exactly `n` nodes follow `ambient_start`.
    /// - Complexity: O(n) time and space for n elements.
    fn make_tuple(
        &mut self,
        n: usize,
        ambient_start: usize,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        if n == 0 {
            self.values.push(Expr::Literal {
                value: Literal::Unit,
                span: ExprSpan { start, end },
            });
            return Ok(());
        }
        let elements = self.values.split_off(ambient_start);
        debug_assert_eq!(
            elements.len(),
            n,
            "make_tuple splits off exactly n elements"
        );
        self.values.push(Expr::Tuple {
            elements,
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Collects source-order elements into an unannotated array node.
    ///
    /// - Precondition: exactly `n` nodes follow `ambient_start`.
    /// - Complexity: O(n) time and space for n elements.
    fn make_array(
        &mut self,
        n: usize,
        ambient_start: usize,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        let elements = self.values.split_off(ambient_start);
        debug_assert_eq!(
            elements.len(),
            n,
            "make_array splits off exactly n elements"
        );
        self.values.push(Expr::Array {
            elements,
            type_annotation: None,
            annotation_span: None,
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Collects elements and retains unresolved annotation syntax and its source boundary.
    ///
    /// - Precondition: exactly `n` nodes follow `ambient_start`.
    /// - Complexity: O(n) time and space for n elements.
    fn make_annotated_array(
        &mut self,
        n: usize,
        ambient_start: usize,
        annotation: crate::parser_context::AnnotatedArray<'_>,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        let elements = self.values.split_off(ambient_start);
        debug_assert_eq!(
            elements.len(),
            n,
            "make_annotated_array splits off exactly n elements"
        );
        let (type_annotation, annotation_span) = annotation.into_parts();
        self.values.push(Expr::Array {
            elements,
            type_annotation,
            annotation_span,
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Reports no semantic tuple arity during syntax-only parsing.
    fn peek_tuple_arity(&self) -> Option<usize> {
        None
    }

    /// Records every representable tuple index without prematurely checking its base type.
    ///
    /// - Precondition: one base expression is present.
    fn tuple_index(&mut self, index: usize, start: Span, end: Span) -> crate::Result<()> {
        let base = self.pop();
        self.values.push(Expr::TupleIndex {
            base: Box::new(base),
            index,
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Returns the node offset used to delimit the current element list.
    fn current_stack_offset(&self) -> usize {
        self.values.len()
    }

    /// Records a cast without resolving its target type.
    ///
    /// - Precondition: one operand is present.
    /// - Complexity: O(b) time and space for b type-name bytes.
    fn apply_cast(
        &mut self,
        _op_lookup: &OpLookup,
        type_name: &str,
        start: Span,
        end: Span,
    ) -> crate::Result<()> {
        let expr = self.pop();
        self.values.push(Expr::Cast {
            expr: Box::new(expr),
            type_name: type_name.to_string(),
            span: ExprSpan { start, end },
        });
        Ok(())
    }

    /// Transfers parameter syntax and its sole body expression into a closure node.
    ///
    /// - Precondition: `body` contains exactly one expression.
    fn push_closure(
        &mut self,
        param_types: Vec<cel_runtime::ValueType>,
        params: Vec<ClosureParam>,
        body: Self,
        span: Span,
    ) -> crate::Result<()> {
        let _ = param_types;
        let body_expr = body.into_expr();
        let end = body_expr.span().end;
        self.values.push(Expr::Closure {
            params,
            body: Box::new(body_expr),
            span: ExprSpan { start: span, end },
        });
        Ok(())
    }
}

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

    /// Name validation reports the duplicate or reserved formal at its own source location.
    #[test]
    fn parameter_diagnostics_use_the_offending_formals_span() {
        let Expr::Closure { mut params, .. } = Parser::<AstContext>::new(OpLookup::new())
            .parse_str_ast("|x: i32, y: bool| x")
            .unwrap()
        else {
            panic!("closure")
        };
        assert!(closure_parameter_diagnostics(&params).is_empty());
        params[1].name = "x".to_owned();
        let errors = closure_parameter_diagnostics(&params);
        assert_eq!(errors.len(), 1);
        assert!(errors[0].message().contains("duplicate"));
        assert_eq!(errors[0].span().start().column, 9);
        params[1].name = "as".to_owned();
        assert!(
            closure_parameter_diagnostics(&params)[0]
                .message()
                .contains("reserved")
        );
    }

    /// Converting owned literals retains their existing allocations and contents.
    #[test]
    fn owned_literal_buffers_transfer_without_copying() {
        let text = String::from("owned");
        let pointer = text.as_ptr();
        let Literal::Str(text) = to_literal(text) else {
            panic!("string literal")
        };
        assert_eq!(text, "owned");
        assert_eq!(text.as_ptr(), pointer);
        let bytes = vec![1u8, 2, 3];
        let pointer = bytes.as_ptr();
        let Literal::ByteStr(bytes) = to_literal(bytes) else {
            panic!("byte string literal")
        };
        assert_eq!(bytes, [1, 2, 3]);
        assert_eq!(bytes.as_ptr(), pointer);
        let text = CString::new("owned").unwrap();
        let pointer = text.as_ptr();
        let Literal::CStr(text) = to_literal(text) else {
            panic!("C string literal")
        };
        assert_eq!(text.to_bytes(), b"owned");
        assert_eq!(text.as_ptr(), pointer);
    }

    /// Supplies a real range distinct from call-site and nested fixture spans.
    fn distinct_span() -> ExprSpan {
        let tokens: proc_macro2::TokenStream = "\n outer\n end".parse().unwrap();
        let mut tokens = tokens.into_iter();
        ExprSpan {
            start: tokens.next().unwrap().span(),
            end: tokens.next().unwrap().span(),
        }
    }
    use proc_macro2::Span;

    #[test]
    fn span_returns_the_range_stored_on_a_leaf_variant() {
        let target = distinct_span();
        let expr = Expr::Ident {
            name: "x".to_string(),
            span: target,
        };
        assert_eq!(
            crate::SourceSpan::from_proc_macro2_range(expr.span().start, expr.span().end),
            crate::SourceSpan::new(2, 1, 3, 4)
        );
    }

    #[test]
    fn span_returns_the_range_stored_on_a_composite_variant() {
        let target = distinct_span();
        let expr = Expr::If {
            cond: Box::new(Expr::Literal {
                value: Literal::Bool(true),
                span: ExprSpan::point(Span::call_site()),
            }),
            then_branch: Box::new(Expr::Literal {
                value: Literal::I32(1),
                span: ExprSpan::point(Span::call_site()),
            }),
            else_branch: Some(Box::new(Expr::Literal {
                value: Literal::I32(2),
                span: ExprSpan::point(Span::call_site()),
            })),
            span: target,
        };
        assert_eq!(
            crate::SourceSpan::from_proc_macro2_range(expr.span().start, expr.span().end),
            crate::SourceSpan::new(2, 1, 3, 4)
        );
    }

    #[test]
    fn closure_span_is_the_stored_span() {
        let target = distinct_span();
        let expr = Expr::Closure {
            params: Vec::new(),
            body: Box::new(Expr::Literal {
                value: Literal::I32(1),
                span: ExprSpan::point(Span::call_site()),
            }),
            span: target,
        };
        assert_eq!(
            crate::SourceSpan::from_proc_macro2_range(expr.span().start, expr.span().end),
            crate::SourceSpan::new(2, 1, 3, 4)
        );
    }

    #[test]
    fn literal_variants_are_distinguishable_and_comparable() {
        assert_eq!(Literal::I32(1), Literal::I32(1));
        assert_ne!(Literal::I32(1), Literal::I32(2));
        assert_ne!(Literal::I32(1), Literal::U8(1));
        assert_eq!(Literal::Unit, Literal::Unit);
    }

    #[test]
    fn logical_op_equality() {
        assert_eq!(LogicalOp::And, LogicalOp::And);
        assert_ne!(LogicalOp::And, LogicalOp::Or);
    }

    #[test]
    fn push_literal_dispatches_every_concrete_literal_type() {
        fn literal_of<T: 'static + Clone>(value: T) -> Literal {
            let mut ctx = AstContext::new_context();
            ctx.push_literal(value, Span::call_site());
            match ctx.into_expr() {
                Expr::Literal { value, .. } => value,
                other => panic!("expected Literal, got {other:?}"),
            }
        }
        assert_eq!(literal_of(1i8), Literal::I8(1));
        assert_eq!(literal_of(1i16), Literal::I16(1));
        assert_eq!(literal_of(1i32), Literal::I32(1));
        assert_eq!(literal_of(1i64), Literal::I64(1));
        assert_eq!(literal_of(1i128), Literal::I128(1));
        assert_eq!(literal_of(1isize), Literal::Isize(1));
        assert_eq!(literal_of(1u8), Literal::U8(1));
        assert_eq!(literal_of(1u16), Literal::U16(1));
        assert_eq!(literal_of(1u32), Literal::U32(1));
        assert_eq!(literal_of(1u64), Literal::U64(1));
        assert_eq!(literal_of(1u128), Literal::U128(1));
        assert_eq!(literal_of(1usize), Literal::Usize(1));
        assert_eq!(literal_of(1.0f32), Literal::F32(1.0));
        assert_eq!(literal_of(1.0f64), Literal::F64(1.0));
        assert_eq!(literal_of(true), Literal::Bool(true));
        assert_eq!(literal_of('a'), Literal::Char('a'));
        assert_eq!(literal_of("s".to_string()), Literal::Str("s".to_string()));
        assert_eq!(literal_of(vec![1u8, 2u8]), Literal::ByteStr(vec![1, 2]));
        assert_eq!(
            literal_of(CString::new("c").unwrap()),
            Literal::CStr(CString::new("c").unwrap())
        );
        assert_eq!(literal_of(()), Literal::Unit);
    }

    #[test]
    fn apply_op_with_arity_zero_records_an_ident_node() {
        let mut ctx = AstContext::new_context();
        let lookup = OpLookup::new();
        ctx.apply_op(&lookup, "x", 0, Span::call_site(), Span::call_site())
            .unwrap();
        assert!(matches!(ctx.into_expr(), Expr::Ident { name, .. } if name == "x"));
    }

    #[test]
    fn apply_op_with_the_call_operator_records_an_apply_node() {
        let mut ctx = AstContext::new_context();
        let lookup = OpLookup::new();
        ctx.apply_op(&lookup, "x", 0, Span::call_site(), Span::call_site())
            .unwrap(); // callee
        ctx.push_literal(1i32, Span::call_site()); // arg
        ctx.apply_op(&lookup, "()", 2, Span::call_site(), Span::call_site())
            .unwrap();
        match ctx.into_expr() {
            Expr::Apply { callee, args, .. } => {
                assert!(matches!(*callee, Expr::Ident { ref name, .. } if name == "x"));
                assert_eq!(args.len(), 1);
            }
            other => panic!("expected Apply, got {other:?}"),
        }
    }

    #[test]
    fn apply_op_with_arity_two_records_an_op_node() {
        let mut ctx = AstContext::new_context();
        let lookup = OpLookup::new();
        ctx.push_literal(1i32, Span::call_site());
        ctx.push_literal(2i32, Span::call_site());
        ctx.apply_op(&lookup, "+", 2, Span::call_site(), Span::call_site())
            .unwrap();
        match ctx.into_expr() {
            Expr::Op { name, operands, .. } => {
                assert_eq!(name, "+");
                assert_eq!(operands.len(), 2);
            }
            other => panic!("expected Op, got {other:?}"),
        }
    }

    #[test]
    fn apply_logical_records_a_logical_node() {
        let mut ctx = AstContext::new_context();
        ctx.push_literal(true, Span::call_site());
        let mut rhs = ctx.new_fragment();
        rhs.push_literal(false, Span::call_site());
        ctx.apply_logical("||", rhs, Span::call_site(), Span::call_site())
            .unwrap();
        match ctx.into_expr() {
            Expr::Logical { op, lhs, rhs, .. } => {
                assert_eq!(op, LogicalOp::Or);
                assert!(matches!(
                    *lhs,
                    Expr::Literal {
                        value: Literal::Bool(true),
                        ..
                    }
                ));
                assert!(matches!(
                    *rhs,
                    Expr::Literal {
                        value: Literal::Bool(false),
                        ..
                    }
                ));
            }
            other => panic!("expected Logical, got {other:?}"),
        }
    }

    #[test]
    fn join2_records_an_if_node() {
        let mut ctx = AstContext::new_context();
        ctx.push_literal(true, Span::call_site());
        let mut then_fragment = ctx.new_fragment();
        then_fragment.push_literal(1i32, Span::call_site());
        let mut else_fragment = ctx.new_fragment();
        else_fragment.push_literal(2i32, Span::call_site());
        ctx.join2(
            then_fragment,
            Some(else_fragment),
            Span::call_site(),
            Span::call_site(),
        )
        .unwrap();
        match ctx.into_expr() {
            Expr::If {
                cond,
                then_branch,
                else_branch,
                ..
            } => {
                assert!(matches!(
                    *cond,
                    Expr::Literal {
                        value: Literal::Bool(true),
                        ..
                    }
                ));
                assert!(matches!(
                    *then_branch,
                    Expr::Literal {
                        value: Literal::I32(1),
                        ..
                    }
                ));
                let else_branch = else_branch.expect("explicit else was given");
                assert!(matches!(
                    *else_branch,
                    Expr::Literal {
                        value: Literal::I32(2),
                        ..
                    }
                ));
            }
            other => panic!("expected If, got {other:?}"),
        }
    }

    #[test]
    fn join2_with_none_records_no_else_branch() {
        let mut ctx = AstContext::new_context();
        ctx.push_literal(true, Span::call_site());
        let mut then_fragment = ctx.new_fragment();
        then_fragment.push_literal(1i32, Span::call_site());
        ctx.join2(then_fragment, None, Span::call_site(), Span::call_site())
            .unwrap();
        match ctx.into_expr() {
            Expr::If { else_branch, .. } => assert!(else_branch.is_none()),
            other => panic!("expected If, got {other:?}"),
        }
    }

    #[test]
    fn make_tuple_and_tuple_index_roundtrip() {
        let mut ctx = AstContext::new_context();
        let ambient_start = ctx.current_stack_offset();
        ctx.push_literal(1i32, Span::call_site());
        ctx.push_literal(2i32, Span::call_site());
        ctx.make_tuple(2, ambient_start, Span::call_site(), Span::call_site())
            .unwrap();
        assert_eq!(ctx.peek_tuple_arity(), None);
        ctx.tuple_index(1, Span::call_site(), Span::call_site())
            .unwrap();
        match ctx.into_expr() {
            Expr::TupleIndex { base, index, .. } => {
                assert_eq!(index, 1);
                assert!(matches!(*base, Expr::Tuple { ref elements, .. } if elements.len() == 2));
            }
            other => panic!("expected TupleIndex, got {other:?}"),
        }
    }

    #[test]
    fn tuple_arity_is_unknown_during_syntax_only_parsing() {
        let mut ctx = AstContext::new_context();
        ctx.push_literal(5i32, Span::call_site());
        assert_eq!(ctx.peek_tuple_arity(), None);
    }

    #[test]
    fn additive_binds_looser_than_multiplicative() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("1 + 2 * 3").unwrap();
        let Expr::Op { name, operands, .. } = expr else {
            panic!("expected Op");
        };
        assert_eq!(name, "+");
        assert!(matches!(
            operands[0],
            Expr::Literal {
                value: Literal::I32(1),
                ..
            }
        ));
        let Expr::Op {
            name: inner_name,
            operands: mul_operands,
            ..
        } = &operands[1]
        else {
            panic!("expected nested Op");
        };
        assert_eq!(inner_name, "*");
        assert!(matches!(
            mul_operands[0],
            Expr::Literal {
                value: Literal::I32(2),
                ..
            }
        ));
        assert!(matches!(
            mul_operands[1],
            Expr::Literal {
                value: Literal::I32(3),
                ..
            }
        ));
    }

    #[test]
    fn unary_minus_and_not_are_recorded_as_arity_one_op_nodes() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("-1i32").unwrap();
        let Expr::Op { name, operands, .. } = expr else {
            panic!("expected Op");
        };
        assert_eq!(name, "-");
        assert_eq!(operands.len(), 1);

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("!true").unwrap();
        let Expr::Op { name, operands, .. } = expr else {
            panic!("expected Op");
        };
        assert_eq!(name, "!");
        assert_eq!(operands.len(), 1);
    }

    #[test]
    fn bare_identifier_is_an_ident_node() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("x").unwrap();
        assert!(matches!(expr, Expr::Ident { name, .. } if name == "x"));
    }

    #[test]
    fn call_with_no_args_and_with_args() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("f()").unwrap();
        let Expr::Apply { callee, args, .. } = expr else {
            panic!("expected Apply");
        };
        assert!(matches!(*callee, Expr::Ident { ref name, .. } if name == "f"));
        assert_eq!(args.len(), 0);

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("f(1i32, 2i32)").unwrap();
        let Expr::Apply { args, .. } = expr else {
            panic!("expected Apply");
        };
        assert_eq!(args.len(), 2);
    }

    #[test]
    fn chained_calls_nest_apply_nodes() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("f()()").unwrap();
        let Expr::Apply { callee, args, .. } = expr else {
            panic!("expected outer Apply");
        };
        assert_eq!(args.len(), 0);
        assert!(matches!(*callee, Expr::Apply { .. }));
    }

    #[test]
    fn unit_grouping_and_tuples() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        assert!(matches!(
            parser.parse_str_ast("()").unwrap(),
            Expr::Literal {
                value: Literal::Unit,
                ..
            }
        ));

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        // Grouping: (1i32 + 2i32) has no Tuple wrapper, just the inner Op.
        assert!(matches!(
            parser.parse_str_ast("(1i32 + 2i32)").unwrap(),
            Expr::Op { .. }
        ));

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("(1i32,)").unwrap();
        assert!(matches!(expr, Expr::Tuple { ref elements, .. } if elements.len() == 1));

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("(1i32, 2i32, 3i32)").unwrap();
        assert!(matches!(expr, Expr::Tuple { ref elements, .. } if elements.len() == 3));
    }

    #[test]
    fn tuple_index_single_and_chained() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("(1i32, 2i32).1").unwrap();
        let Expr::TupleIndex { base, index, .. } = expr else {
            panic!("expected TupleIndex");
        };
        assert_eq!(index, 1);
        assert!(matches!(*base, Expr::Tuple { ref elements, .. } if elements.len() == 2));

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        // Chained `.0.1` tokenizes as one float literal `0.1` split back into two indices.
        let expr = parser.parse_str_ast("((1i32, 2i32), 3i32).0.1").unwrap();
        let Expr::TupleIndex { base, index, .. } = expr else {
            panic!("expected outer TupleIndex");
        };
        assert_eq!(index, 1);
        assert!(matches!(*base, Expr::TupleIndex { index: 0, .. }));
    }

    #[test]
    fn tuple_index_on_a_call_result_still_builds_a_tree() {
        // Deferred validation: DynSegmentContext would reject an out-of-range index at parse
        // time, but AstContext can't know a call's return arity without type inference, so it
        // must still build a tree here rather than fail to parse.
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("f().5").unwrap();
        assert!(matches!(expr, Expr::TupleIndex { index: 5, .. }));
    }

    #[test]
    fn if_without_else_has_no_else_branch() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("if true { 1i32 }").unwrap();
        let Expr::If {
            cond,
            then_branch,
            else_branch,
            ..
        } = expr
        else {
            panic!("expected If");
        };
        assert!(matches!(
            *cond,
            Expr::Literal {
                value: Literal::Bool(true),
                ..
            }
        ));
        assert!(matches!(
            *then_branch,
            Expr::Literal {
                value: Literal::I32(1),
                ..
            }
        ));
        assert!(else_branch.is_none());
    }

    #[test]
    fn if_else_and_else_if_chain() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser
            .parse_str_ast("if true { 1i32 } else { 2i32 }")
            .unwrap();
        let Expr::If { else_branch, .. } = expr else {
            panic!("expected If");
        };
        assert!(matches!(
            else_branch.as_deref(),
            Some(Expr::Literal {
                value: Literal::I32(2),
                ..
            })
        ));

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser
            .parse_str_ast("if true { 1i32 } else if false { 2i32 } else { 3i32 }")
            .unwrap();
        let Expr::If { else_branch, .. } = expr else {
            panic!("expected outer If");
        };
        assert!(matches!(else_branch.as_deref(), Some(Expr::If { .. })));
    }

    #[test]
    fn logical_or_is_not_desugared_to_if() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("a || b").unwrap();
        let Expr::Logical { op, lhs, rhs, .. } = expr else {
            panic!("expected Logical");
        };
        assert_eq!(op, LogicalOp::Or);
        assert!(matches!(*lhs, Expr::Ident { ref name, .. } if name == "a"));
        assert!(matches!(*rhs, Expr::Ident { ref name, .. } if name == "b"));
    }

    #[test]
    fn logical_and_is_not_desugared_to_if() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("a && b").unwrap();
        let Expr::Logical { op, .. } = expr else {
            panic!("expected Logical");
        };
        assert_eq!(op, LogicalOp::And);
    }

    #[test]
    fn logical_mixes_with_comparison_at_the_right_precedence() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        // `&&` binds looser than `==`, so this is `(a == 1i32) && (b == 2i32)`.
        let expr = parser.parse_str_ast("a == 1i32 && b == 2i32").unwrap();
        let Expr::Logical { op, lhs, rhs, .. } = expr else {
            panic!("expected Logical");
        };
        assert_eq!(op, LogicalOp::And);
        assert!(matches!(*lhs, Expr::Op { ref name, .. } if name == "=="));
        assert!(matches!(*rhs, Expr::Op { ref name, .. } if name == "=="));
    }

    #[test]
    fn for_text_produces_a_span_whose_source_text_matches() {
        let span = ExprSpan::for_text("i64");
        assert_eq!(span.start.source_text().as_deref(), Some("i64"));
        assert_eq!(span.end.source_text().as_deref(), Some("i64"));
    }

    #[test]
    fn for_text_works_for_a_string_literal() {
        let span = ExprSpan::for_text("\"hello\"");
        assert_eq!(span.start.source_text().as_deref(), Some("\"hello\""));
    }

    #[test]
    fn make_array_pushes_one_array_node_holding_the_elements_in_source_order() {
        let mut ctx = AstContext::new_context();
        let ambient_start = ctx.current_stack_offset();
        ctx.push_literal(1i32, Span::call_site());
        ctx.push_literal(2i32, Span::call_site());
        ctx.make_array(2, ambient_start, Span::call_site(), Span::call_site())
            .unwrap();
        match ctx.into_expr() {
            Expr::Array { elements, .. } => {
                assert!(matches!(
                    elements[0],
                    Expr::Literal {
                        value: Literal::I32(1),
                        ..
                    }
                ));
                assert!(matches!(
                    elements[1],
                    Expr::Literal {
                        value: Literal::I32(2),
                        ..
                    }
                ));
            }
            other => panic!("expected Array, got {other:?}"),
        }
    }

    #[test]
    fn array_literal_records_elements_in_source_order_with_an_enclosing_span() {
        let source = "[0i32, 1i32, 2i32]";
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast(source).unwrap();
        let Expr::Array { elements, span, .. } = expr else {
            panic!("expected Array");
        };
        assert_eq!(elements.len(), 3);
        for (index, element) in elements.iter().enumerate() {
            let Expr::Literal { value, .. } = element else {
                panic!("expected a literal element");
            };
            assert_eq!(*value, Literal::I32(i32::try_from(index).unwrap()));
        }
        assert_eq!(span.start.source_text().as_deref(), Some(source));
        assert_eq!(span.end.source_text().as_deref(), Some(source));
    }

    #[test]
    fn nested_array_literal_nests_array_nodes() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("[[0i32], [1i32]]").unwrap();
        let Expr::Array { elements, .. } = expr else {
            panic!("expected outer Array");
        };
        assert_eq!(elements.len(), 2);
        for element in &elements {
            assert!(matches!(element, Expr::Array { elements, .. } if elements.len() == 1));
        }
    }

    #[test]
    fn typed_array_literal_still_builds_an_array_node() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("[0, 1]: [i32]").unwrap();
        let Expr::Array {
            elements,
            type_annotation,
            annotation_span,
            ..
        } = expr
        else {
            panic!("expected Array");
        };
        assert_eq!(elements.len(), 2);
        assert!(annotation_span.is_some());
        match type_annotation {
            Some(TypeExpr::Array { element, .. }) => {
                assert!(matches!(*element, TypeExpr::Named { ref name, .. } if name == "i32"));
            }
            other => panic!("expected an array type annotation, got {other:?}"),
        }
    }

    #[test]
    fn typed_empty_array_literal_builds_an_empty_array_node() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("[]: [i32]").unwrap();
        assert!(matches!(
            expr,
            Expr::Array {
                ref elements,
                type_annotation: Some(_),
                annotation_span: Some(_),
                ..
            } if elements.is_empty()
        ));
    }

    #[test]
    fn typed_array_literal_preserves_the_exact_annotation_span() {
        let source = "[1.0, 42.5]: [f64]";
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast(source).unwrap();
        let Expr::Array {
            type_annotation: Some(_),
            annotation_span: Some(annotation_span),
            ..
        } = expr
        else {
            panic!("expected Array");
        };
        let start = annotation_span.start.start();
        let end = annotation_span.end.end();
        assert_eq!(&source[start.column..end.column], ": [f64]");
    }

    #[test]
    fn array_literals_build_nodes_in_call_argument_and_tuple_positions() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("f([1i32], (2i32, [3i32]))").unwrap();
        let Expr::Apply { args, .. } = expr else {
            panic!("expected Apply");
        };
        assert!(matches!(args[0], Expr::Array { ref elements, .. } if elements.len() == 1));
        let Expr::Tuple { elements, .. } = &args[1] else {
            panic!("expected a tuple argument");
        };
        assert!(matches!(elements[1], Expr::Array { .. }));
    }

    #[test]
    fn array_literals_build_nodes_in_if_branch_and_closure_body_positions() {
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser
            .parse_str_ast("if true { [1i32] } else { [2i32] }")
            .unwrap();
        let Expr::If {
            then_branch,
            else_branch,
            ..
        } = expr
        else {
            panic!("expected If");
        };
        assert!(matches!(*then_branch, Expr::Array { .. }));
        assert!(matches!(else_branch.as_deref(), Some(Expr::Array { .. })));

        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("|x: i32| [x]").unwrap();
        let Expr::Closure { body, .. } = expr else {
            panic!("expected Closure");
        };
        assert!(matches!(*body, Expr::Array { .. }));
    }

    #[test]
    fn array_literal_with_a_tuple_element_still_builds_a_tree() {
        // Syntax-only parsing records tuple elements without resolving their shapes.
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let expr = parser.parse_str_ast("[(1i32, 2i32)]").unwrap();
        assert!(matches!(expr, Expr::Array { ref elements, .. } if elements.len() == 1));
    }

    #[test]
    fn ast_context_still_rejects_an_empty_array_literal() {
        // The empty-literal diagnostic is a grammar-level rejection (see #212), so it applies to
        // every `ParserContext`, not only the one that resolves runtime types.
        let mut parser = Parser::<AstContext>::new(OpLookup::new());
        let err = parser
            .parse_str_ast("[]")
            .expect_err("an empty array literal has no inferable element type");
        assert!(
            err.message().contains("empty array"),
            "got: {}",
            err.message()
        );
    }
}