gruel_parser/

chumsky_parser.rs

//! Chumsky-based parser for the Gruel programming language.
//!
//! This module provides a parser implementation using chumsky combinators
//! with Pratt parsing for expression precedence.

use crate::ast::{
    AnonFnExpr, AnonStructField, ArgMode, ArrayLitExpr, AssignStatement, AssignTarget,
    AssocFnCallExpr, Ast, BinaryExpr, BinaryOp, BlockExpr, BoolLit, BreakExpr, CallArg, CallExpr,
    CharLit, CheckedBlockExpr, ComptimeBlockExpr, ComptimeUnrollForExpr, ConstDecl, ContinueExpr,
    DeriveDecl, Directive, DirectiveArg, Directives, Doc, EnumDecl, EnumStructLitExpr, EnumVariant,
    Expr, FieldDecl, FieldExpr, FieldInit, FieldPattern, FloatLit, ForExpr, Function, Ident,
    IfExpr, IndexExpr, IntLit, InterfaceDecl, IntrinsicArg, IntrinsicCallExpr, Item, LetStatement,
    LoopExpr, MatchArm, MatchExpr, Method, MethodCallExpr, MethodSig, NegIntLit, Param, ParamMode,
    ParenExpr, PathExpr, PathPattern, Pattern, RangeExpr, ReturnExpr, SelfExpr, SelfParam,
    SelfReceiverKind, Statement, StringLit, StructDecl, StructLitExpr, TupleElemPattern, TupleExpr,
    TupleIndexExpr, TypeExpr, TypeLitExpr, UnaryExpr, UnaryOp, UnitLit, Visibility, WhileExpr,
};
use chumsky::input::{Input as ChumskyInput, MapExtra, Stream, ValueInput};
use chumsky::prelude::*;
use chumsky::recovery::via_parser;
use chumsky::recursive::Direct;
use gruel_builtins::Posture;
use gruel_lexer::TokenKind;
use gruel_util::span::LineIndex;
use gruel_util::{CompileError, CompileErrors, ErrorKind, MultiErrorResult, PreviewFeatures};
use gruel_util::{FileId, Span};
use lasso::{Spur, ThreadedRodeo};
use std::borrow::Cow;
use std::collections::HashMap;

use chumsky::extra::SimpleState;

/// Pre-interned symbols for primitive type names and special keywords.
/// These are interned once when the parser is created and reused for all parsing.
#[derive(Clone, Copy)]
pub struct PrimitiveTypeSpurs {
    pub i8: Spur,
    pub i16: Spur,
    pub i32: Spur,
    pub i64: Spur,
    pub isize: Spur,
    pub u8: Spur,
    pub u16: Spur,
    pub u32: Spur,
    pub u64: Spur,
    pub usize: Spur,
    pub f16: Spur,
    pub f32: Spur,
    pub f64: Spur,
    pub bool: Spur,
    /// Unicode scalar value type (ADR-0071)
    pub char: Spur,
    /// Self type keyword - used in methods to refer to the containing struct type
    pub self_type: Spur,
    /// `Ref` identifier (ADR-0076) — used by self-param parsing to
    /// recognise `self : Ref(Self)` without a separate keyword token.
    pub ref_name: Spur,
    /// `MutRef` identifier (ADR-0076) — likewise for `self : MutRef(Self)`.
    pub mut_ref_name: Spur,
    /// The identifier "derive" — accepted as a directive name so users can
    /// write `@derive(Foo)` even though `derive` is also a reserved keyword
    /// for top-level derive items (ADR-0058).
    pub derive_name: Spur,
    /// The identifier "mark" — used to detect `@mark(unchecked)` in a
    /// function/method directive list without a string compare.
    pub mark_name: Spur,
    /// The identifier "unchecked" — argument to `@mark(...)` recognised
    /// at parse time so the parsed `Function::is_unchecked` /
    /// `Method::is_unchecked` flag captures the directive form alongside
    /// the legacy `unchecked` keyword (ADR-0088).
    pub unchecked_name: Spur,
}

impl PrimitiveTypeSpurs {
    /// Create a new set of primitive type symbols by interning them.
    pub fn new(interner: &mut ThreadedRodeo) -> Self {
        Self {
            i8: interner.get_or_intern("i8"),
            i16: interner.get_or_intern("i16"),
            i32: interner.get_or_intern("i32"),
            i64: interner.get_or_intern("i64"),
            isize: interner.get_or_intern("isize"),
            u8: interner.get_or_intern("u8"),
            u16: interner.get_or_intern("u16"),
            u32: interner.get_or_intern("u32"),
            u64: interner.get_or_intern("u64"),
            usize: interner.get_or_intern("usize"),
            f16: interner.get_or_intern("f16"),
            f32: interner.get_or_intern("f32"),
            f64: interner.get_or_intern("f64"),
            bool: interner.get_or_intern("bool"),
            char: interner.get_or_intern("char"),
            self_type: interner.get_or_intern("Self"),
            ref_name: interner.get_or_intern("Ref"),
            mut_ref_name: interner.get_or_intern("MutRef"),
            derive_name: interner.get_or_intern("derive"),
            mark_name: interner.get_or_intern("mark"),
            unchecked_name: interner.get_or_intern("unchecked"),
        }
    }
}

/// ADR-0088: scan a directive list for `@mark(unchecked)`. Returns true
/// if any directive in the list is `@mark(...)` with `unchecked` as one
/// of its arguments. The lookup is by interned Spur, not string compare.
pub(crate) fn directives_have_mark_unchecked(
    directives: &Directives,
    mark_name: Spur,
    unchecked_name: Spur,
) -> bool {
    directives.iter().any(|d| {
        d.name.name == mark_name
            && d.args.iter().any(|a| match a {
                DirectiveArg::Ident(ident) => ident.name == unchecked_name,
                DirectiveArg::String(_) => false,
            })
    })
}

/// Parser state containing primitive type symbols and file ID.
///
/// This struct holds mutable state needed during parsing:
/// - Pre-interned primitive type symbols for efficient lookup
/// - The FileId for the current file being parsed (for multi-file compilation)
#[derive(Clone, Copy)]
pub struct ParserState {
    /// Pre-interned primitive type symbols.
    pub syms: PrimitiveTypeSpurs,
    /// The file ID for spans in this file.
    pub file_id: FileId,
}

impl ParserState {
    /// Create a new parser state with the given symbols and file ID.
    pub fn new(syms: PrimitiveTypeSpurs, file_id: FileId) -> Self {
        Self { syms, file_id }
    }
}

/// Type alias for parser extras that carries parser state.
/// This replaces the previous thread-local approach with compile-time safe state passing.
type ParserExtras<'src> = extra::Full<Rich<'src, TokenKind>, SimpleState<ParserState>, ()>;

/// Type-erased parser to keep symbol names short. Boxing at each function boundary
/// prevents monomorphized type chains from growing exponentially in length.
type GruelParser<'src, I, O> = Boxed<'src, 'src, I, O, ParserExtras<'src>>;

/// Convert a `usize` offset to `u32`, asserting it fits in debug builds.
///
/// # Panics
///
/// In debug builds, panics if `offset` exceeds `u32::MAX`.
/// This would only happen for source files larger than 4GB.
#[inline]
fn offset_to_u32(offset: usize) -> u32 {
    debug_assert!(
        offset <= u32::MAX as usize,
        "offset {} exceeds u32::MAX (source file too large)",
        offset
    );
    offset as u32
}

/// Convert chumsky SimpleSpan to gruel_util::Span with a specific file ID.
///
/// # Panics
///
/// In debug builds, panics if `span.start` or `span.end` exceeds `u32::MAX`.
/// This would only happen for source files larger than 4GB.
fn to_gruel_util_with_file(span: SimpleSpan, file_id: FileId) -> Span {
    Span::with_file(file_id, offset_to_u32(span.start), offset_to_u32(span.end))
}

/// Convert chumsky SimpleSpan to gruel_util::Span using the default file ID.
/// Only used for error conversion where we don't have access to the parser state.
fn to_gruel_util(span: SimpleSpan) -> Span {
    Span::new(offset_to_u32(span.start), offset_to_u32(span.end))
}

/// Extract a Span with file ID from the parser extra.
/// This is the primary way to create spans during parsing.
#[inline]
fn span_from_extra<'src, I>(e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>) -> Span
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let file_id = e.state().0.file_id;
    to_gruel_util_with_file(e.span(), file_id)
}

/// Parser that produces Ident from identifier tokens
fn ident_parser<'src, I>() -> GruelParser<'src, I, Ident>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    select! {
        TokenKind::Ident(name) = e => Ident {
            name,
            span: span_from_extra(e),
        },
    }
    .boxed()
}

/// Parser that produces Ident for a method name.
///
/// Kept as a separate function from `ident_parser` so callers can
/// document method-position semantics, even though after retiring the
/// `drop` keyword (it is now a regular identifier — `drop fn TypeName`
/// at item position is recognized via a state-based ident match) the
/// two are equivalent.
fn method_name_parser<'src, I>() -> GruelParser<'src, I, Ident>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    ident_parser().boxed()
}

/// Parser for primitive type keywords: i8, i16, i32, i64, u8, u16, u32, u64, bool
/// These are reserved keywords that cannot be used as identifiers.
fn primitive_type_parser<'src, I>() -> GruelParser<'src, I, TypeExpr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Access primitive type symbols from parser state via e.state().0
    // SimpleState<T> wraps T in a .0 field
    // Type annotation on closure parameter is needed to help Rust infer the Extra type
    let i8_parser =
        just(TokenKind::I8).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.i8,
                span: span_from_extra(e),
            })
        });
    let i16_parser =
        just(TokenKind::I16).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.i16,
                span: span_from_extra(e),
            })
        });
    let i32_parser =
        just(TokenKind::I32).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.i32,
                span: span_from_extra(e),
            })
        });
    let i64_parser =
        just(TokenKind::I64).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.i64,
                span: span_from_extra(e),
            })
        });
    let u8_parser =
        just(TokenKind::U8).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.u8,
                span: span_from_extra(e),
            })
        });
    let u16_parser =
        just(TokenKind::U16).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.u16,
                span: span_from_extra(e),
            })
        });
    let u32_parser =
        just(TokenKind::U32).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.u32,
                span: span_from_extra(e),
            })
        });
    let u64_parser =
        just(TokenKind::U64).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.u64,
                span: span_from_extra(e),
            })
        });
    let isize_parser =
        just(TokenKind::Isize).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.isize,
                span: span_from_extra(e),
            })
        });
    let usize_parser =
        just(TokenKind::Usize).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.usize,
                span: span_from_extra(e),
            })
        });
    let f16_parser =
        just(TokenKind::F16).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.f16,
                span: span_from_extra(e),
            })
        });
    let f32_parser =
        just(TokenKind::F32).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.f32,
                span: span_from_extra(e),
            })
        });
    let f64_parser =
        just(TokenKind::F64).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.f64,
                span: span_from_extra(e),
            })
        });
    let bool_parser =
        just(TokenKind::Bool).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.bool,
                span: span_from_extra(e),
            })
        });
    let char_parser =
        just(TokenKind::Char).map_with(|_, e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
            let syms = e.state().0.syms;
            TypeExpr::Named(Ident {
                name: syms.char,
                span: span_from_extra(e),
            })
        });

    choice((
        i8_parser.boxed(),
        i16_parser.boxed(),
        i32_parser.boxed(),
        i64_parser.boxed(),
        isize_parser.boxed(),
        u8_parser.boxed(),
        u16_parser.boxed(),
        u32_parser.boxed(),
        u64_parser.boxed(),
        usize_parser.boxed(),
        f16_parser.boxed(),
        f32_parser.boxed(),
        f64_parser.boxed(),
        bool_parser.boxed(),
        char_parser.boxed(),
    ))
    .boxed()
}

/// Parser for type expressions: primitive types (i32, bool, etc.), () for unit, ! for never, or [T; N] for arrays
fn type_parser<'src, I>() -> GruelParser<'src, I, TypeExpr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    recursive(
        move |ty: Recursive<Direct<'src, 'src, I, TypeExpr, ParserExtras<'src>>>| {
            // Unit type: ()
            let unit_type = just(TokenKind::LParen)
                .then(just(TokenKind::RParen))
                .map_with(|_, e| TypeExpr::Unit(span_from_extra(e)));

            // Never type: !
            let never_type =
                just(TokenKind::Bang).map_with(|_, e| TypeExpr::Never(span_from_extra(e)));

            // Array type: [T; N]
            let array_type = just(TokenKind::LBracket)
                .ignore_then(ty.clone())
                .then_ignore(just(TokenKind::Semi))
                .then(select! {
                    TokenKind::Int(n) => n,
                })
                .then_ignore(just(TokenKind::RBracket))
                .map_with(|(element, length), e| TypeExpr::Array {
                    element: Box::new(element),
                    length,
                    span: span_from_extra(e),
                });

            // Anonymous struct type: struct { field: Type, ... }
            // Used in comptime type construction
            let anon_struct_field: GruelParser<'src, I, AnonStructField> = ident_parser()
                .then_ignore(just(TokenKind::Colon))
                .then(ty.clone())
                .map_with(|(name, field_ty), e| AnonStructField {
                    doc: None,
                    name,
                    ty: field_ty,
                    span: span_from_extra(e),
                })
                .boxed();

            let anon_struct_fields: GruelParser<'src, I, Vec<AnonStructField>> = anon_struct_field
                .separated_by(just(TokenKind::Comma))
                .allow_trailing()
                .collect::<Vec<_>>()
                .boxed();

            let anon_struct_type = just(TokenKind::Struct)
                .ignore_then(just(TokenKind::LBrace))
                .ignore_then(anon_struct_fields)
                .then_ignore(just(TokenKind::RBrace))
                .map_with(|fields, e| TypeExpr::AnonymousStruct {
                    directives: Directives::new(),
                    posture: Posture::Affine,
                    fields,
                    methods: vec![],
                    span: span_from_extra(e),
                });

            // Parameterized type call (ADR-0057): `Name(arg1, arg2, ...)`
            // in type position. Resolves at sema time by evaluating the
            // call as a comptime expression returning `type`.
            let type_call = ident_parser()
                .then(
                    ty.clone()
                        .separated_by(just(TokenKind::Comma))
                        .allow_trailing()
                        .at_least(1)
                        .collect::<Vec<_>>()
                        .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)),
                )
                .map_with(|(callee, args), e| TypeExpr::TypeCall {
                    callee,
                    args,
                    span: span_from_extra(e),
                });

            // Named type: user-defined types like MyStruct
            let named_type = ident_parser().map(TypeExpr::Named);

            // Self type: Self keyword used in methods to refer to the containing struct
            let self_type = just(TokenKind::SelfType).map_with(|_, e| {
                let span = span_from_extra(e);
                TypeExpr::Named(Ident {
                    name: e.state().syms.self_type,
                    span,
                })
            });

            // Tuple type: (T,) for 1-tuples, (T, U) or (T, U,) for 2+-tuples.
            // Must be tried after unit_type (which matches `()`) but before named_type.
            // A 1-tuple requires a trailing comma to distinguish it from parenthesised
            // types (not currently supported). We parse: LParen <ty> Comma (<ty>,)* RParen.
            let tuple_type = just(TokenKind::LParen)
                .ignore_then(ty.clone())
                .then_ignore(just(TokenKind::Comma))
                .then(
                    ty.clone()
                        .separated_by(just(TokenKind::Comma))
                        .allow_trailing()
                        .collect::<Vec<_>>(),
                )
                .then_ignore(just(TokenKind::RParen))
                .map_with(|(first, rest), e| {
                    let mut elems = Vec::with_capacity(1 + rest.len());
                    elems.push(first);
                    elems.extend(rest);
                    TypeExpr::Tuple {
                        elems,
                        span: span_from_extra(e),
                    }
                });

            choice((
                unit_type.boxed(),
                never_type.boxed(),
                array_type.boxed(),
                anon_struct_type.boxed(),
                primitive_type_parser().boxed(),
                self_type.boxed(),
                tuple_type.boxed(),
                // type_call must come before named_type — they share the
                // ident prefix, but type_call requires the trailing
                // `(...)` whereas named_type matches a bare ident.
                type_call.boxed(),
                named_type.boxed(),
            ))
            .boxed()
        },
    )
    .boxed()
}

/// Parser for parameter mode: comptime. The legacy `inout` / `borrow`
/// keyword modes were retired by ADR-0076 Phase 6 — the new sole form
/// is `name: Ref(T)` / `name: MutRef(T)`.
fn param_mode_parser<'src, I>() -> GruelParser<'src, I, ParamMode>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    just(TokenKind::Comptime).to(ParamMode::Comptime).boxed()
}

/// Parser for function parameters: [comptime] [inout|borrow] name: type
fn param_parser<'src, I>() -> GruelParser<'src, I, Param>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    just(TokenKind::Comptime)
        .or_not()
        .then(param_mode_parser().or_not())
        .then(ident_parser())
        .then_ignore(just(TokenKind::Colon))
        .then(type_parser())
        .map_with(|(((is_comptime, mode), name), ty), e| Param {
            is_comptime: is_comptime.is_some(),
            mode: mode.unwrap_or(ParamMode::Normal),
            name,
            ty,
            span: span_from_extra(e),
        })
        .boxed()
}

/// Parser for struct field declarations: [pub] name: type
fn field_decl_parser<'src, I>() -> GruelParser<'src, I, FieldDecl>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // ADR-0073: optional `pub` prefix.
    let visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });

    visibility
        .then(ident_parser())
        .then_ignore(just(TokenKind::Colon))
        .then(type_parser())
        .map_with(|((visibility, name), ty), e| FieldDecl {
            doc: None,
            visibility,
            name,
            ty,
            span: span_from_extra(e),
        })
        .boxed()
}

/// Parser for comma-separated struct field declarations
fn field_decls_parser<'src, I>() -> GruelParser<'src, I, Vec<FieldDecl>>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    field_decl_parser()
        .separated_by(just(TokenKind::Comma))
        .allow_trailing()
        .collect::<Vec<_>>()
        .boxed()
}

/// Parser for comma-separated parameters
fn params_parser<'src, I>() -> GruelParser<'src, I, Vec<Param>>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    param_parser()
        .separated_by(just(TokenKind::Comma))
        .collect::<Vec<_>>()
        .boxed()
}

/// Parser for a single directive: @name or @name(arg1, arg2, ...)
///
/// `name` accepts both bare identifiers and the `derive` reserved keyword
/// (ADR-0058) so that `@derive(Foo)` works even though `derive` is also a
/// keyword for top-level derive items.
fn directive_parser<'src, I>() -> GruelParser<'src, I, Directive>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let directive_name = choice((
        ident_parser().boxed(),
        select! {
            TokenKind::Derive = e => {
                let state: &mut SimpleState<ParserState> = e.state();
                Ident {
                    name: state.0.syms.derive_name,
                    span: span_from_extra(e),
                }
            },
        }
        .boxed(),
    ))
    .boxed();

    // ADR-0083: `@mark(...)` directive args. After Phase 4 retired
    // `TokenKind::Linear`, both `copy` and `linear` are regular
    // identifiers and fall through to `ident_parser`. ADR-0088
    // Phase 6 retired `TokenKind::Unchecked` similarly.
    let directive_arg = choice((
        select! {
            TokenKind::String(s) = e => DirectiveArg::String(StringLit {
                value: s,
                span: span_from_extra(e),
            }),
        }
        .boxed(),
        ident_parser().map(DirectiveArg::Ident).boxed(),
    ))
    .boxed();

    just(TokenKind::At)
        .ignore_then(directive_name)
        .then(
            directive_arg
                .separated_by(just(TokenKind::Comma))
                .allow_trailing()
                .collect::<Vec<_>>()
                .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen))
                .or_not(),
        )
        .map_with(|(name, args), e| Directive {
            name,
            args: args.unwrap_or_default(),
            span: span_from_extra(e),
        })
        .boxed()
}

/// Parser for zero or more directives
fn directives_parser<'src, I>() -> GruelParser<'src, I, Directives>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Chumsky's collect() requires its Container trait, which SmallVec doesn't implement.
    // So we collect to Vec first, then convert. The overhead is minimal since most
    // items have 0-1 directives (Vec is cheap for empty/small collections).
    directive_parser()
        .repeated()
        .collect::<Vec<_>>()
        .map(|v| v.into_iter().collect())
        .boxed()
}

/// Parser for a single call argument. The legacy `inout` / `borrow`
/// keyword arg modes were retired by ADR-0076 Phase 6 — the new sole
/// form is `&expr` / `&mut expr`.
fn call_arg_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, CallArg>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    chumsky::primitive::empty()
        .map(|_| None::<ArgMode>)
        .then(expr)
        .map_with(|(mode, expr), e| CallArg {
            mode: mode.unwrap_or(ArgMode::Normal),
            expr,
            span: span_from_extra(e),
        })
        .boxed()
}

/// Parser for comma-separated call arguments with optional inout
fn call_args_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, Vec<CallArg>>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    call_arg_parser(expr)
        .separated_by(just(TokenKind::Comma))
        .collect::<Vec<_>>()
        .boxed()
}

/// Parser for comma-separated expression arguments (for contexts that don't support inout)
fn args_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, Vec<Expr>>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    expr.separated_by(just(TokenKind::Comma))
        .collect::<Vec<_>>()
        .boxed()
}

/// Parser for struct field initializers: name: expr
fn field_init_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, FieldInit>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Field init with explicit value: `name: expr`
    let explicit = ident_parser()
        .then_ignore(just(TokenKind::Colon))
        .then(expr)
        .map_with(|(name, value), e| FieldInit {
            name,
            value: Box::new(value),
            span: span_from_extra(e),
        });

    // Field init shorthand: `name` means `name: name`
    let shorthand = ident_parser().map_with(|name, e| FieldInit {
        value: Box::new(Expr::Ident(name)),
        name,
        span: span_from_extra(e),
    });

    choice((explicit, shorthand)).boxed()
}

/// Parser for comma-separated field initializers
fn field_inits_parser<'src, I>(
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, Vec<FieldInit>>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    field_init_parser(expr)
        .separated_by(just(TokenKind::Comma))
        .allow_trailing()
        .collect::<Vec<_>>()
        .boxed()
}

/// Helper to create binary expression
fn make_binary(left: Expr, op: BinaryOp, right: Expr) -> Expr {
    let span = Span::new(left.span().start, right.span().end);
    Expr::Binary(BinaryExpr {
        left: Box::new(left),
        op,
        right: Box::new(right),
        span,
    })
}

/// Helper to create unary expression
fn make_unary(op: UnaryOp, operand: Expr, op_span: SimpleSpan) -> Expr {
    let span = Span::new(offset_to_u32(op_span.start), operand.span().end);
    Expr::Unary(UnaryExpr {
        op,
        operand: Box::new(operand),
        span,
    })
}

/// Expression parser using manual precedence climbing.
///
/// Operator precedence (tightest binding first):
///   unary prefix: -, !, ~
///   multiplicative: *, /, %
///   additive: +, -
///   shift: <<, >>
///   comparison: ==, !=, <, >, <=, >=
///   bitwise AND: &
///   bitwise XOR: ^
///   bitwise OR: |
///   logical AND: &&
///   logical OR: ||  (loosest binding)
///
/// Each level is immediately `.boxed()` to keep the Rc'd type short and avoid
/// the huge drop-glue symbols that Chumsky's Pratt parser would generate (the
/// Pratt operator-tuple type embeds `I` dozens of times).
fn expr_parser<'src, I>() -> GruelParser<'src, I, Expr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    recursive(
        |expr: Recursive<Direct<'src, 'src, I, Expr, ParserExtras<'src>>>| {
            // Atom parser – primary expressions (highest precedence).
            let atom: GruelParser<I, Expr> = atom_parser(expr.clone().boxed());

            // Unary prefix operators: -, !, ~  (right-associative; stack and apply inside-out)
            let unary: GruelParser<I, Expr> = {
                let prefix_op: GruelParser<I, (UnaryOp, SimpleSpan)> = choice((
                    just(TokenKind::Minus)
                        .map_with(|_, e| (UnaryOp::Neg, e.span()))
                        .boxed(),
                    just(TokenKind::Bang)
                        .map_with(|_, e| (UnaryOp::Not, e.span()))
                        .boxed(),
                    just(TokenKind::Tilde)
                        .map_with(|_, e| (UnaryOp::BitNot, e.span()))
                        .boxed(),
                    // ADR-0062: `&mut x` constructs a `MutRef(T)` (must come
                    // before the bare `&` so we don't fall through to `Ref`).
                    just(TokenKind::Amp)
                        .then(just(TokenKind::Mut))
                        .map_with(|_, e| (UnaryOp::MutRef, e.span()))
                        .boxed(),
                    // ADR-0062: `&x` constructs a `Ref(T)`.
                    just(TokenKind::Amp)
                        .map_with(|_, e| (UnaryOp::Ref, e.span()))
                        .boxed(),
                ))
                .boxed();
                prefix_op
                    .repeated()
                    .collect::<Vec<_>>()
                    .then(atom.clone())
                    .map(|(mut ops, mut rhs)| {
                        // Apply operators from innermost (rightmost) outward.
                        ops.reverse();
                        for (op, span) in ops {
                            rhs = make_unary(op, rhs, span);
                        }
                        rhs
                    })
                    .boxed()
            };

            // Helper macro: build one left-associative binary level.
            // Each call boxes the result, keeping the drop-glue type short.
            macro_rules! left_binary {
                ($prev:expr, $op_parser:expr) => {{
                    let prev: GruelParser<I, Expr> = $prev;
                    let op: GruelParser<I, BinaryOp> = $op_parser;
                    prev.clone()
                        .foldl(op.then(prev).repeated(), |l, (op, r)| make_binary(l, op, r))
                        .boxed()
                }};
            }

            // Multiplicative: *, /, %
            let multiplicative: GruelParser<I, Expr> = left_binary!(
                unary,
                choice((
                    just(TokenKind::Star).to(BinaryOp::Mul).boxed(),
                    just(TokenKind::Slash).to(BinaryOp::Div).boxed(),
                    just(TokenKind::Percent).to(BinaryOp::Mod).boxed(),
                ))
                .boxed()
            );

            // Additive: +, -
            let additive: GruelParser<I, Expr> = left_binary!(
                multiplicative,
                choice((
                    just(TokenKind::Plus).to(BinaryOp::Add).boxed(),
                    just(TokenKind::Minus).to(BinaryOp::Sub).boxed(),
                ))
                .boxed()
            );

            // Shift: <<, >>
            let shift: GruelParser<I, Expr> = left_binary!(
                additive,
                choice((
                    just(TokenKind::LtLt).to(BinaryOp::Shl).boxed(),
                    just(TokenKind::GtGt).to(BinaryOp::Shr).boxed(),
                ))
                .boxed()
            );

            // Comparison: ==, !=, <, >, <=, >=
            let comparison: GruelParser<I, Expr> = left_binary!(
                shift,
                choice((
                    just(TokenKind::EqEq).to(BinaryOp::Eq).boxed(),
                    just(TokenKind::BangEq).to(BinaryOp::Ne).boxed(),
                    just(TokenKind::Lt).to(BinaryOp::Lt).boxed(),
                    just(TokenKind::Gt).to(BinaryOp::Gt).boxed(),
                    just(TokenKind::LtEq).to(BinaryOp::Le).boxed(),
                    just(TokenKind::GtEq).to(BinaryOp::Ge).boxed(),
                ))
                .boxed()
            );

            // Bitwise AND: &
            let bitwise_and: GruelParser<I, Expr> = left_binary!(
                comparison,
                just(TokenKind::Amp).to(BinaryOp::BitAnd).boxed()
            );

            // Bitwise XOR: ^
            let bitwise_xor: GruelParser<I, Expr> = left_binary!(
                bitwise_and,
                just(TokenKind::Caret).to(BinaryOp::BitXor).boxed()
            );

            // Bitwise OR: |
            let bitwise_or: GruelParser<I, Expr> = left_binary!(
                bitwise_xor,
                just(TokenKind::Pipe).to(BinaryOp::BitOr).boxed()
            );

            // Logical AND: &&
            let logical_and: GruelParser<I, Expr> = left_binary!(
                bitwise_or,
                just(TokenKind::AmpAmp).to(BinaryOp::And).boxed()
            );

            // Logical OR: || (lowest binary precedence)
            let logical_or: GruelParser<I, Expr> = left_binary!(
                logical_and,
                just(TokenKind::PipePipe).to(BinaryOp::Or).boxed()
            );

            logical_or
        },
    )
    .boxed()
}

/// Parser for patterns in match arms
fn pattern_parser<'src, I>() -> GruelParser<'src, I, Pattern>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    recursive(
        |pat: Recursive<Direct<'src, 'src, _, Pattern, ParserExtras<'src>>>| {
            // Wildcard pattern: _
            let wildcard =
                just(TokenKind::Underscore).map_with(|_, e| Pattern::Wildcard(span_from_extra(e)));

            // Integer literal pattern (positive or zero)
            let int_pat = select! {
                TokenKind::Int(n) = e => Pattern::Int(IntLit {
                    value: n,
                    span: span_from_extra(e),
                }),
            };

            // Negative integer literal pattern: - followed by integer
            let neg_int_pat = just(TokenKind::Minus)
                .then(select! { TokenKind::Int(n) => n })
                .map_with(|(_, n), e| {
                    Pattern::NegInt(NegIntLit {
                        value: n,
                        span: span_from_extra(e),
                    })
                });

            // Boolean literal patterns
            let bool_true = select! {
                TokenKind::True = e => Pattern::Bool(BoolLit {
                    value: true,
                    span: span_from_extra(e),
                }),
            };

            let bool_false = select! {
                TokenKind::False = e => Pattern::Bool(BoolLit {
                    value: false,
                    span: span_from_extra(e),
                }),
            };

            // A rest pattern `..`: two adjacent Dot tokens (the lexer has no DotDot).
            // `..` is only legal inside a tuple/struct/variant sequence. ADR-0049 Phase 6.
            let rest_token = just(TokenKind::Dot)
                .then(just(TokenKind::Dot))
                .map_with(|_, e| span_from_extra(e));

            // A leaf binding in a pattern sub-position: `_`, `x`, or `mut x`. These can
            // still appear anywhere a full sub-pattern is legal; full sub-patterns go
            // through `pat` (the recursive reference).
            let leaf_binding = choice((
                just(TokenKind::Underscore).map_with(|_, e| Pattern::Wildcard(span_from_extra(e))),
                just(TokenKind::Mut)
                    .ignore_then(ident_parser())
                    .map_with(|name, e| Pattern::Ident {
                        is_mut: true,
                        name,
                        span: span_from_extra(e),
                    }),
                ident_parser().map_with(|name, e| Pattern::Ident {
                    is_mut: false,
                    name,
                    span: span_from_extra(e),
                }),
            ));

            // Sub-pattern: any full pattern OR a leaf binding (as a shortcut). In match
            // contexts we need `mut x` at the sub-pattern position, which the recursive
            // `pat` doesn't emit (only full patterns do).
            //
            // Order: try the recursive pattern first (for nested Enum::V / Struct { .. } /
            // (.., ..) shapes), then fall back to the leaf binding for bare idents,
            // wildcards, and `mut x`. A bare ident matches both as a Pattern::Ident inside
            // `pat` and as a leaf binding — either path yields the same AST.
            let sub_pattern = choice((pat.clone(), leaf_binding.clone())).boxed();

            // One element in a tuple / variant-tuple sequence: either `..` or a sub-pattern.
            let tuple_elem = choice((
                rest_token.map(TupleElemPattern::Rest),
                sub_pattern.clone().map(TupleElemPattern::Pattern),
            ))
            .boxed();

            // `(e1, e2, ...)` tuple-like sequence body.
            let tuple_suffix = tuple_elem
                .clone()
                .separated_by(just(TokenKind::Comma))
                .allow_trailing()
                .collect::<Vec<_>>()
                .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen));

            // Named field in a struct / struct-variant pattern: `field`, `field: sub`,
            // `mut field`, `mut field: sub`, or the rest sentinel `..`.
            let field_rest = rest_token.map_with(|span, _e| FieldPattern {
                field_name: None,
                sub: None,
                is_mut: false,
                span,
            });
            let field_explicit = just(TokenKind::Mut)
                .or_not()
                .then(ident_parser())
                .then_ignore(just(TokenKind::Colon))
                .then(sub_pattern.clone())
                .map_with(|((is_mut, field_name), sub), e| FieldPattern {
                    field_name: Some(field_name),
                    sub: Some(sub),
                    is_mut: is_mut.is_some(),
                    span: span_from_extra(e),
                });
            let field_shorthand =
                just(TokenKind::Mut)
                    .or_not()
                    .then(ident_parser())
                    .map_with(|(is_mut, name), e| FieldPattern {
                        field_name: Some(name),
                        sub: None,
                        is_mut: is_mut.is_some(),
                        span: span_from_extra(e),
                    });
            let field_pat = choice((field_rest, field_explicit, field_shorthand)).boxed();

            let struct_suffix = field_pat
                .clone()
                .separated_by(just(TokenKind::Comma))
                .allow_trailing()
                .collect::<Vec<_>>()
                .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace));

            // Enum for the suffix on an enum variant pattern: tuple, struct, or none.
            #[derive(Debug, Clone)]
            enum PatternSuffix {
                Tuple(Vec<TupleElemPattern>),
                Struct(Vec<FieldPattern>),
            }

            let pattern_suffix = choice((
                tuple_suffix.clone().map(PatternSuffix::Tuple),
                struct_suffix.clone().map(PatternSuffix::Struct),
            ));

            // Self path pattern: Self::Variant, Self::Variant(sub, ...), or Self::Variant { field: sub, ... }
            let self_path_pat = just(TokenKind::SelfType)
                .ignore_then(just(TokenKind::ColonColon))
                .ignore_then(ident_parser())
                .then(pattern_suffix.clone().or_not())
                .map_with(|(variant, suffix_opt), e| {
                    let span = span_from_extra(e);
                    let type_name = Ident {
                        name: e.state().syms.self_type,
                        span,
                    };
                    match suffix_opt {
                        Some(PatternSuffix::Tuple(fields)) => Pattern::DataVariant {
                            base: None,
                            type_name,
                            variant,
                            fields,
                            span,
                        },
                        Some(PatternSuffix::Struct(fields)) => Pattern::StructVariant {
                            base: None,
                            type_name,
                            variant,
                            fields,
                            span,
                        },
                        None => Pattern::Path(PathPattern {
                            base: None,
                            type_name,
                            variant,
                            span,
                        }),
                    }
                });

            // IDENT (followed by `{`, `::`, or nothing): either a struct destructure,
            // a unit/data/struct variant, or a bare ident binding.
            //
            // `IDENT { ... }` → Pattern::Struct
            // `IDENT::IDENT[(...)]` / `IDENT::IDENT{ ... }` → Pattern::{Path, DataVariant, StructVariant}
            let struct_destructure =
                ident_parser()
                    .then(struct_suffix.clone())
                    .map_with(|(type_name, fields), e| Pattern::Struct {
                        type_name,
                        fields,
                        span: span_from_extra(e),
                    });

            let simple_path_pat = ident_parser()
                .then_ignore(just(TokenKind::ColonColon))
                .then(ident_parser())
                .then(pattern_suffix.clone().or_not())
                .map_with(|((type_name, variant), suffix_opt), e| match suffix_opt {
                    Some(PatternSuffix::Tuple(fields)) => Pattern::DataVariant {
                        base: None,
                        type_name,
                        variant,
                        fields,
                        span: span_from_extra(e),
                    },
                    Some(PatternSuffix::Struct(fields)) => Pattern::StructVariant {
                        base: None,
                        type_name,
                        variant,
                        fields,
                        span: span_from_extra(e),
                    },
                    None => Pattern::Path(PathPattern {
                        base: None,
                        type_name,
                        variant,
                        span: span_from_extra(e),
                    }),
                });

            // Qualified path pattern: module.Enum::Variant or module.sub.Enum::Variant
            let qualified_path_pat = ident_parser()
                .then(
                    just(TokenKind::Dot)
                        .ignore_then(ident_parser())
                        .repeated()
                        .at_least(1)
                        .collect::<Vec<_>>(),
                )
                .then_ignore(just(TokenKind::ColonColon))
                .then(ident_parser())
                .then(pattern_suffix.or_not())
                .map_with(|(((first, mut rest), variant), suffix_opt), e| {
                    let type_name = rest.pop().expect("at_least(1) guarantees non-empty");

                    let base_expr = if rest.is_empty() {
                        Expr::Ident(first)
                    } else {
                        let mut base = Expr::Ident(first);
                        for field in rest {
                            let span = base.span().extend_to(field.span.end);
                            base = Expr::Field(FieldExpr {
                                base: Box::new(base),
                                field,
                                span,
                            });
                        }
                        base
                    };

                    match suffix_opt {
                        Some(PatternSuffix::Tuple(fields)) => Pattern::DataVariant {
                            base: Some(Box::new(base_expr)),
                            type_name,
                            variant,
                            fields,
                            span: span_from_extra(e),
                        },
                        Some(PatternSuffix::Struct(fields)) => Pattern::StructVariant {
                            base: Some(Box::new(base_expr)),
                            type_name,
                            variant,
                            fields,
                            span: span_from_extra(e),
                        },
                        None => Pattern::Path(PathPattern {
                            base: Some(Box::new(base_expr)),
                            type_name,
                            variant,
                            span: span_from_extra(e),
                        }),
                    }
                });

            // Tuple pattern (match context or nested position): `(p1, p2, ...)` with at
            // least one comma, or `(p,)` for a 1-tuple. `(p)` remains a parenthesised
            // pattern — not supported here (redundant: just write `p`).
            let tuple_pat = just(TokenKind::LParen)
                .ignore_then(tuple_elem.clone())
                .then_ignore(just(TokenKind::Comma))
                .then(
                    tuple_elem
                        .clone()
                        .separated_by(just(TokenKind::Comma))
                        .allow_trailing()
                        .collect::<Vec<_>>(),
                )
                .then_ignore(just(TokenKind::RParen))
                .map_with(|(first, rest), e| {
                    let mut elems = Vec::with_capacity(1 + rest.len());
                    elems.push(first);
                    elems.extend(rest);
                    Pattern::Tuple {
                        elems,
                        span: span_from_extra(e),
                    }
                });

            // Plain ident / mut-ident leaf as a top-level pattern (bare binding).
            let ident_leaf =
                just(TokenKind::Mut)
                    .or_not()
                    .then(ident_parser())
                    .map_with(|(is_mut, name), e| Pattern::Ident {
                        is_mut: is_mut.is_some(),
                        name,
                        span: span_from_extra(e),
                    });

            choice((
                wildcard.boxed(),
                neg_int_pat.boxed(),
                int_pat.boxed(),
                bool_true.boxed(),
                bool_false.boxed(),
                tuple_pat.boxed(),
                // Try qualified path first (has more structure), then Self path, then
                // simple path, then struct destructure, then bare ident. Struct destructure
                // and simple path both start with IDENT; `IDENT::` disambiguates. Struct
                // destructure requires `IDENT {`, a combination that doesn't conflict with
                // the bare ident parser which is tried last.
                qualified_path_pat.boxed(),
                self_path_pat.boxed(),
                simple_path_pat.boxed(),
                struct_destructure.boxed(),
                ident_leaf.boxed(),
            ))
            .boxed()
        },
    )
    .boxed()
}

/// Parser for a single match arm: pattern => expr  OR
/// `comptime_unroll for ident in expr { body }` (ADR-0079 Phase 3),
/// which the compiler expands at sema time into one regular arm
/// per element of the iterable.
fn match_arm_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, MatchArm>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let regular_arm = pattern_parser()
        .then_ignore(just(TokenKind::FatArrow))
        .then(expr.clone())
        .map_with(|(pattern, body), e| MatchArm {
            pattern,
            body: Box::new(body),
            span: span_from_extra(e),
        });

    let unroll_arm = just(TokenKind::ComptimeUnroll)
        .ignore_then(just(TokenKind::For))
        .ignore_then(ident_parser())
        .then_ignore(just(TokenKind::In))
        .then(expr.clone())
        .then(maybe_unit_block_parser(expr))
        .map_with(|((binding, iterable), body), e| {
            let span = span_from_extra(e);
            MatchArm {
                pattern: Pattern::ComptimeUnrollArm {
                    binding,
                    iterable: Box::new(iterable),
                    span,
                },
                body: Box::new(Expr::Block(body)),
                span,
            }
        });

    choice((unroll_arm, regular_arm)).boxed()
}

/// Parser for literal expressions: integers, strings, booleans, and unit
fn literal_parser<'src, I>() -> GruelParser<'src, I, Expr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Integer literal
    let int_lit = select! {
        TokenKind::Int(n) = e => Expr::Int(IntLit {
            value: n,
            span: span_from_extra(e),
        }),
    };

    // Floating-point literal
    let float_lit = select! {
        TokenKind::Float(bits) = e => Expr::Float(FloatLit {
            bits,
            span: span_from_extra(e),
        }),
    };

    // String literal
    let string_lit = select! {
        TokenKind::String(s) = e => Expr::String(StringLit {
            value: s,
            span: span_from_extra(e),
        }),
    };

    // Char literal (ADR-0071)
    let char_lit = select! {
        TokenKind::CharLit(c) = e => Expr::Char(CharLit {
            value: c,
            span: span_from_extra(e),
        }),
    };

    // Boolean literals
    let bool_true = select! {
        TokenKind::True = e => Expr::Bool(BoolLit {
            value: true,
            span: span_from_extra(e),
        }),
    };

    let bool_false = select! {
        TokenKind::False = e => Expr::Bool(BoolLit {
            value: false,
            span: span_from_extra(e),
        }),
    };

    // Unit literal: ()
    let unit_lit = just(TokenKind::LParen)
        .then(just(TokenKind::RParen))
        .map_with(|_, e| {
            Expr::Unit(UnitLit {
                span: span_from_extra(e),
            })
        });

    choice((
        int_lit.boxed(),
        float_lit.boxed(),
        string_lit.boxed(),
        char_lit.boxed(),
        bool_true.boxed(),
        bool_false.boxed(),
        unit_lit.boxed(),
    ))
    .boxed()
}

/// Parser for control flow expressions: break, continue, return, if, while, loop, match
fn control_flow_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, Expr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Break
    let break_expr = select! {
        TokenKind::Break = e => Expr::Break(BreakExpr { span: span_from_extra(e) }),
    };

    // Continue
    let continue_expr = select! {
        TokenKind::Continue = e => Expr::Continue(ContinueExpr { span: span_from_extra(e) }),
    };

    // Return expression: return <expr>? (expression is optional for unit-returning functions)
    let return_expr = just(TokenKind::Return)
        .ignore_then(expr.clone().or_not())
        .map_with(|value, e| {
            Expr::Return(ReturnExpr {
                value: value.map(Box::new),
                span: span_from_extra(e),
            })
        });

    // If expression - defined with recursive reference to allow `else if` chains.
    // ADR-0079 follow-up: an optional leading `comptime` keyword marks the
    // branch as a comptime-evaluated dispatch (see `IfExpr::is_comptime`).
    let if_expr: GruelParser<'src, I, Expr> = recursive(
        |if_expr_rec: Recursive<Direct<'src, 'src, I, Expr, ParserExtras<'src>>>| {
            just(TokenKind::Comptime)
                .or_not()
                .then_ignore(just(TokenKind::If))
                .then(expr.clone())
                .then(maybe_unit_block_parser(expr.clone()))
                .then(
                    just(TokenKind::Else)
                        .ignore_then(choice((
                            // else if: wrap the nested if in a synthetic block
                            if_expr_rec
                                .map_with(|nested_if, e| {
                                    let span = span_from_extra(e);
                                    BlockExpr {
                                        statements: Vec::new(),
                                        expr: Box::new(nested_if),
                                        span,
                                    }
                                })
                                .boxed(),
                            // else { ... }: parse a regular block
                            maybe_unit_block_parser(expr.clone()),
                        )))
                        .or_not(),
                )
                .map_with(|(((comptime_kw, cond), then_block), else_block), e| {
                    Expr::If(IfExpr {
                        cond: Box::new(cond),
                        then_block,
                        else_block,
                        span: span_from_extra(e),
                        is_comptime: comptime_kw.is_some(),
                    })
                })
                .boxed()
        },
    )
    .boxed();

    // While expression
    let while_expr: GruelParser<'src, I, Expr> = just(TokenKind::While)
        .ignore_then(expr.clone())
        .then(maybe_unit_block_parser(expr.clone()))
        .map_with(|(cond, body), e| {
            Expr::While(WhileExpr {
                cond: Box::new(cond),
                body,
                span: span_from_extra(e),
            })
        })
        .boxed();

    // For-in expression: for [mut] ident in expr { body }
    let for_expr: GruelParser<'src, I, Expr> = just(TokenKind::For)
        .ignore_then(just(TokenKind::Mut).or_not())
        .then(ident_parser())
        .then_ignore(just(TokenKind::In))
        .then(expr.clone())
        .then(maybe_unit_block_parser(expr.clone()))
        .map_with(|(((is_mut, binding), iterable), body), e| {
            Expr::For(ForExpr {
                binding,
                is_mut: is_mut.is_some(),
                iterable: Box::new(iterable),
                body,
                span: span_from_extra(e),
            })
        })
        .boxed();

    // Loop expression (infinite loop)
    let loop_expr: GruelParser<'src, I, Expr> = just(TokenKind::Loop)
        .ignore_then(maybe_unit_block_parser(expr.clone()))
        .map_with(|body, e| {
            Expr::Loop(LoopExpr {
                body,
                span: span_from_extra(e),
            })
        })
        .boxed();

    // Match expression: match scrutinee { pattern => expr, ... }
    let match_expr: GruelParser<'src, I, Expr> = just(TokenKind::Match)
        .ignore_then(expr.clone())
        .then(
            match_arm_parser(expr.clone())
                .separated_by(just(TokenKind::Comma))
                .allow_trailing()
                .collect::<Vec<_>>()
                .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
        )
        .map_with(|(scrutinee, arms), e| {
            Expr::Match(MatchExpr {
                scrutinee: Box::new(scrutinee),
                arms,
                span: span_from_extra(e),
            })
        })
        .boxed();

    // Comptime unroll for expression: comptime_unroll for ident in expr { body }
    let comptime_unroll_for_expr: GruelParser<'src, I, Expr> = just(TokenKind::ComptimeUnroll)
        .ignore_then(just(TokenKind::For))
        .ignore_then(ident_parser())
        .then_ignore(just(TokenKind::In))
        .then(expr.clone())
        .then(maybe_unit_block_parser(expr.clone()))
        .map_with(|((binding, iterable), body), e| {
            Expr::ComptimeUnrollFor(ComptimeUnrollForExpr {
                binding,
                iterable: Box::new(iterable),
                body,
                span: span_from_extra(e),
            })
        })
        .boxed();

    choice((
        break_expr.boxed(),
        continue_expr.boxed(),
        return_expr.boxed(),
        if_expr,
        while_expr,
        for_expr,
        comptime_unroll_for_expr,
        loop_expr,
        match_expr,
    ))
    .boxed()
}

/// What can follow an identifier: call args, struct fields, path (::variant), path call (::fn()), or nothing
#[derive(Clone)]
enum IdentSuffix {
    Call(Vec<CallArg>),
    StructLit(Vec<FieldInit>),
    Path(Ident),                          // ::Variant (for enum variants)
    PathCall(Ident, Vec<CallArg>),        // ::function() (for associated functions)
    PathStructLit(Ident, Vec<FieldInit>), // ::Variant { field: value } (for enum struct variants)
    /// ADR-0063: `(type_args)::function(call_args)` — a type-call followed by a path call.
    TypeCallPathCall(Vec<Expr>, Ident, Vec<CallArg>),
    None,
}

/// Parser for identifier-based expressions: identifiers, function calls, struct literals, and paths
fn call_and_access_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, Expr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    ident_parser()
        .then(
            choice((
                // ADR-0063: type-call path call `Name(type_args)::method(args)`.
                // Tried before plain `(args)` so it has a chance to match the
                // `::method(args)` tail; chumsky backtracks if that tail
                // isn't there.
                {
                    let type_args = expr
                        .clone()
                        .separated_by(just(TokenKind::Comma))
                        .allow_trailing()
                        .at_least(1)
                        .collect::<Vec<_>>()
                        .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen));
                    type_args
                        .then_ignore(just(TokenKind::ColonColon))
                        .then(ident_parser())
                        .then(
                            call_args_parser(expr.clone())
                                .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)),
                        )
                        .map(|((type_args, func), args)| {
                            IdentSuffix::TypeCallPathCall(type_args, func, args)
                        })
                        .boxed()
                },
                // Function call: (args)
                call_args_parser(expr.clone())
                    .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen))
                    .map(IdentSuffix::Call)
                    .boxed(),
                // Struct literal: { field: value, ... } or { field, ... } (shorthand)
                // Lookahead: require `{ }` or `{ ident :` or `{ ident ,`
                // to disambiguate from blocks like `if cond { expr }`
                just(TokenKind::LBrace)
                    .then(
                        choice((
                            just(TokenKind::RBrace).ignored(),
                            select! { TokenKind::Ident(_) => () }
                                .then_ignore(just(TokenKind::Colon))
                                .ignored(),
                            select! { TokenKind::Ident(_) => () }
                                .then_ignore(just(TokenKind::Comma))
                                .ignored(),
                        ))
                        .rewind(),
                    )
                    .rewind()
                    .ignore_then(
                        field_inits_parser(expr.clone())
                            .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
                    )
                    .map(IdentSuffix::StructLit)
                    .boxed(),
                // Associated function call: ::function(args)
                just(TokenKind::ColonColon)
                    .ignore_then(ident_parser())
                    .then(
                        call_args_parser(expr.clone())
                            .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)),
                    )
                    .map(|(func, args)| IdentSuffix::PathCall(func, args))
                    .boxed(),
                // Enum struct variant literal: ::Variant { field: value, ... }
                just(TokenKind::ColonColon)
                    .ignore_then(ident_parser())
                    .then(
                        field_inits_parser(expr.clone())
                            .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
                    )
                    .map(|(variant, fields)| IdentSuffix::PathStructLit(variant, fields))
                    .boxed(),
                // Path: ::Variant (for enum variants)
                just(TokenKind::ColonColon)
                    .ignore_then(ident_parser())
                    .map(IdentSuffix::Path)
                    .boxed(),
            ))
            .or_not()
            .map(|opt| opt.unwrap_or(IdentSuffix::None)),
        )
        .map_with(|(name, suffix), e| match suffix {
            IdentSuffix::Call(args) => Expr::Call(CallExpr {
                name,
                args,
                span: span_from_extra(e),
            }),
            IdentSuffix::StructLit(fields) => Expr::StructLit(StructLitExpr {
                base: None, // No module prefix for simple `StructName { ... }`
                name,
                fields,
                span: span_from_extra(e),
            }),
            IdentSuffix::PathCall(function, args) => Expr::AssocFnCall(AssocFnCallExpr {
                base: None, // No module prefix for simple `Type::function()`
                type_name: name,
                type_args: Vec::new(),
                function,
                args,
                span: span_from_extra(e),
            }),
            IdentSuffix::TypeCallPathCall(type_args, function, args) => {
                Expr::AssocFnCall(AssocFnCallExpr {
                    base: None,
                    type_name: name,
                    type_args,
                    function,
                    args,
                    span: span_from_extra(e),
                })
            }
            IdentSuffix::PathStructLit(variant, fields) => Expr::EnumStructLit(EnumStructLitExpr {
                base: None,
                type_name: name,
                variant,
                fields,
                span: span_from_extra(e),
            }),
            IdentSuffix::Path(variant) => Expr::Path(PathExpr {
                base: None, // No module prefix for simple `Enum::Variant`
                type_name: name,
                variant,
                span: span_from_extra(e),
            }),
            IdentSuffix::None => Expr::Ident(name),
        })
        .boxed()
}

/// Suffix for field access (.field), method call (.method(args)), indexing ([expr]),
/// qualified struct literals (.Type { ... }), and qualified paths (.Enum::Variant)
#[derive(Clone)]
enum Suffix {
    /// Simple field access: .field
    Field(Ident),
    /// Tuple field access: .0, .1, ... (ADR-0048).
    /// The u32 is the index; the Span is the position of the integer literal.
    TupleField(u32, Span),
    /// Method call with method name, arguments, and closing paren position
    MethodCall(Ident, Vec<CallArg>, u32),
    /// Index expression with the inner expression and closing bracket position
    Index(Expr, u32),
    /// Qualified struct literal: .StructName { fields }
    /// NOTE: Not yet wired up due to grammar ambiguity with field access + block
    QualifiedStructLit(Ident, Vec<FieldInit>, u32),
    /// Qualified path (enum variant): .EnumName::Variant
    QualifiedPath(Ident, Ident, u32),
    /// Qualified associated function call: .TypeName::function(args)
    QualifiedAssocFnCall(Ident, Ident, Vec<CallArg>, u32),
    /// Qualified enum struct variant literal: .EnumName::Variant { field: value }
    QualifiedEnumStructLit(Ident, Ident, Vec<FieldInit>, u32),
}

/// Wraps a primary expression parser with field access, method call, and indexing suffixes
fn with_suffix_parser<'src, I>(
    primary: impl Parser<'src, I, Expr, ParserExtras<'src>> + Clone + 'src,
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, Expr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Method call: .ident(args)
    let method_call_suffix = just(TokenKind::Dot)
        .ignore_then(ident_parser())
        .then(
            call_args_parser(expr.clone())
                .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)),
        )
        .map_with(|(method, args), e| {
            Suffix::MethodCall(method, args, offset_to_u32(e.span().end))
        });

    // Qualified struct literal: .StructName { field: value, ... }
    // We need to distinguish between:
    //   - `module.Point { x: 1 }` - qualified struct literal
    //   - `obj.field { 1 }` - field access followed by a block expression
    //
    // The key difference is that struct literals have `{ ident: value, ... }` while
    // block expressions have `{ expr }`. We use a lookahead to require that `{` is
    // followed by `}` (empty struct) or `ident :` (non-empty struct) to confirm it's
    // a struct literal, not field access followed by a block.
    //
    // Lookahead check: succeeds (without consuming) if `{ }` or `{ ident : `
    let struct_lit_lookahead = just(TokenKind::LBrace)
        .then(
            choice((
                // Empty struct: { }
                just(TokenKind::RBrace).ignored(),
                // Non-empty struct: { ident : ...
                select! { TokenKind::Ident(_) => () }
                    .then_ignore(just(TokenKind::Colon))
                    .ignored(),
            ))
            // We're just checking the pattern exists, not consuming
            .rewind(),
        )
        .rewind();

    // NOTE: Box the lookahead itself to prevent its complex nested type from
    // accumulating in qualified_struct_lit_suffix before that parser is boxed.
    let struct_lit_lookahead: GruelParser<'src, I, _> = struct_lit_lookahead.boxed();

    // NOTE: .boxed() is required here to shorten the monomorphized type name.
    // The lookahead creates deeply nested generics that exceed macOS linker limits.
    // We split into a boxed head (name + lookahead) and then chain the body.
    let struct_lit_name: GruelParser<'src, I, Ident> = just(TokenKind::Dot)
        .ignore_then(ident_parser())
        .then_ignore(struct_lit_lookahead)
        .boxed();
    let qualified_struct_lit_suffix = struct_lit_name
        .then(
            field_inits_parser(expr.clone())
                .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
        )
        .map_with(|(name, fields), e| {
            Suffix::QualifiedStructLit(name, fields, offset_to_u32(e.span().end))
        })
        .boxed();

    // NOTE: .boxed() on the shared head prevents type accumulation in both
    // qualified_assoc_fn_suffix and qualified_path_suffix.
    let type_and_member: GruelParser<'src, I, (Ident, Ident)> = just(TokenKind::Dot)
        .ignore_then(ident_parser())
        .then_ignore(just(TokenKind::ColonColon))
        .then(ident_parser())
        .boxed();

    // Qualified associated function call: .TypeName::function(args)
    let qualified_assoc_fn_suffix = type_and_member
        .clone()
        .then(
            call_args_parser(expr.clone())
                .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)),
        )
        .map_with(|((type_name, function), args), e| {
            Suffix::QualifiedAssocFnCall(type_name, function, args, offset_to_u32(e.span().end))
        });

    // Qualified enum struct variant literal: .EnumName::Variant { field: value, ... }
    let qualified_enum_struct_lit_suffix = type_and_member
        .clone()
        .then(
            field_inits_parser(expr.clone())
                .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
        )
        .map_with(|((type_name, variant), fields), e| {
            Suffix::QualifiedEnumStructLit(type_name, variant, fields, offset_to_u32(e.span().end))
        });

    // Qualified path (enum variant): .EnumName::Variant
    // We capture the end position from the variant ident before the negative lookahead
    let qualified_path_suffix = type_and_member
        .map(|(type_name, variant): (Ident, Ident)| {
            let end = variant.span.end;
            (type_name, variant, end)
        })
        .then_ignore(none_of([TokenKind::LParen, TokenKind::LBrace]).rewind())
        .map(|(type_name, variant, end)| Suffix::QualifiedPath(type_name, variant, end));

    // Field access: .ident (but NOT followed by '(', '::', or struct literal pattern)
    // The qualified_struct_lit_suffix is tried first and uses lookahead, so field_suffix
    // only matches when we're certain it's field access, not a qualified struct literal.
    let field_suffix = just(TokenKind::Dot)
        .ignore_then(ident_parser())
        .then_ignore(none_of([TokenKind::LParen, TokenKind::ColonColon]).rewind())
        .map(Suffix::Field);

    // Tuple field access: .N where N is a non-negative integer literal (ADR-0048).
    //
    // Note: the lexer tokenises `0.1` / `1e10` as a single `Float` token, so
    // `t.0.1` and `t.1e10` fail to parse as nested tuple access. Users must
    // write `(t.0).1` for nested access. Float re-splitting in field position
    // is deferred to a future ADR.
    //
    // Indices larger than u32::MAX are clamped to u32::MAX; tuples cannot have
    // more than u32::MAX elements, so sema will report this as out-of-bounds.
    let tuple_field_suffix = just(TokenKind::Dot)
        .ignore_then(select! {
            TokenKind::Int(n) = e => (n, span_from_extra(e)),
        })
        .map(|(n, span)| {
            let idx = if n > u32::MAX as u64 {
                u32::MAX
            } else {
                n as u32
            };
            Suffix::TupleField(idx, span)
        });

    // ADR-0064: range subscripts. Inside `[ … ]`, accept either a regular
    // expression (existing array indexing) or a range form: `..`, `..hi`,
    // `lo..`, `lo..hi`. The parser produces `Expr::Range(_)` for the range
    // forms; sema enforces that ranges only appear under `&` / `&mut`.
    //
    // The lexer has no `DotDot` token — `..` is two adjacent `.` tokens
    // (same convention as the rest-pattern parser).
    let dot_dot = just(TokenKind::Dot).then(just(TokenKind::Dot));

    let range_or_expr = choice((
        // `..` or `..hi` — leading `..` makes this unambiguous.
        dot_dot
            .ignore_then(expr.clone().or_not())
            .map_with(|hi, e| {
                Expr::Range(RangeExpr {
                    lo: None,
                    hi: hi.map(Box::new),
                    span: span_from_extra(e),
                })
            }),
        // `expr` optionally followed by `..` and optionally another expr.
        // No `..` => plain index expression.
        expr.clone()
            .then(dot_dot.ignore_then(expr.clone().or_not()).or_not())
            .map_with(|(lhs, suffix), e| match suffix {
                Some(hi) => Expr::Range(RangeExpr {
                    lo: Some(Box::new(lhs)),
                    hi: hi.map(Box::new),
                    span: span_from_extra(e),
                }),
                None => lhs,
            }),
    ));

    let index_suffix = range_or_expr
        .delimited_by(just(TokenKind::LBracket), just(TokenKind::RBracket))
        .map_with(|index, e| Suffix::Index(index, offset_to_u32(e.span().end)));

    // Order matters: more specific patterns must come before less specific ones
    // - qualified_assoc_fn_suffix before qualified_path_suffix (both have ::)
    // - method_call_suffix before field_suffix (both start with .ident)
    // - qualified_struct_lit_suffix before field_suffix (uses lookahead for { ident: } pattern)
    // - qualified_path_suffix before field_suffix (both start with .ident)
    //
    // NOTE: .boxed() is required here to shorten the monomorphized type name.
    // Without it, macOS's ld64 linker fails with "symbol name too long" because
    // the 6-way choice creates extremely long generic type names.
    primary
        .foldl(
            choice((
                method_call_suffix.boxed(),
                qualified_assoc_fn_suffix.boxed(),
                qualified_enum_struct_lit_suffix.boxed(),
                qualified_struct_lit_suffix,
                qualified_path_suffix.boxed(),
                field_suffix.boxed(),
                tuple_field_suffix.boxed(),
                index_suffix.boxed(),
            ))
            .boxed()
            .repeated(),
            |base, suffix| match suffix {
                Suffix::Field(field) => {
                    // Extend the base span to include the field, preserving file_id
                    let span = base.span().extend_to(field.span.end);
                    Expr::Field(FieldExpr {
                        base: Box::new(base),
                        field,
                        span,
                    })
                }
                Suffix::TupleField(index, index_span) => {
                    let span = base.span().extend_to(index_span.end);
                    Expr::TupleIndex(TupleIndexExpr {
                        base: Box::new(base),
                        index,
                        span,
                        index_span,
                    })
                }
                Suffix::MethodCall(method, args, end) => {
                    // Extend the base span to the end of the call, preserving file_id
                    let span = base.span().extend_to(end);
                    Expr::MethodCall(MethodCallExpr {
                        receiver: Box::new(base),
                        method,
                        args,
                        span,
                    })
                }
                Suffix::Index(index, end) => {
                    // Extend the base span to the end of the index, preserving file_id
                    let span = base.span().extend_to(end);
                    Expr::Index(IndexExpr {
                        base: Box::new(base),
                        index: Box::new(index),
                        span,
                    })
                }
                Suffix::QualifiedStructLit(name, fields, end) => {
                    // module.StructName { ... } → StructLitExpr with base
                    let span = base.span().extend_to(end);
                    Expr::StructLit(StructLitExpr {
                        base: Some(Box::new(base)),
                        name,
                        fields,
                        span,
                    })
                }
                Suffix::QualifiedPath(type_name, variant, end) => {
                    // module.EnumName::Variant → PathExpr with base
                    let span = base.span().extend_to(end);
                    Expr::Path(PathExpr {
                        base: Some(Box::new(base)),
                        type_name,
                        variant,
                        span,
                    })
                }
                Suffix::QualifiedEnumStructLit(type_name, variant, fields, end) => {
                    // module.EnumName::Variant { ... } → EnumStructLitExpr with base
                    let span = base.span().extend_to(end);
                    Expr::EnumStructLit(EnumStructLitExpr {
                        base: Some(Box::new(base)),
                        type_name,
                        variant,
                        fields,
                        span,
                    })
                }
                Suffix::QualifiedAssocFnCall(type_name, function, args, end) => {
                    // module.TypeName::function(args) → AssocFnCallExpr with base
                    let span = base.span().extend_to(end);
                    Expr::AssocFnCall(AssocFnCallExpr {
                        base: Some(Box::new(base)),
                        type_name,
                        type_args: Vec::new(),
                        function,
                        args,
                        span,
                    })
                }
            },
        )
        .boxed()
}

/// Atom parser - primary expressions (literals, identifiers, parens, blocks, control flow)
fn atom_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, Expr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Self expression (in method bodies)
    let self_expr = select! {
        TokenKind::SelfValue = e => Expr::SelfExpr(SelfExpr { span: span_from_extra(e) }),
    };

    // Parenthesized expression or tuple literal.
    //
    // `(e)`         -> ParenExpr
    // `(e,)`        -> TupleExpr with one element
    // `(e, f, ...)` -> TupleExpr with 2+ elements
    // `()` is handled separately by `unit_lit` (see literal_parser).
    //
    // Implementation: parse `LParen expr`, then optionally `Comma expr_list`,
    // then `RParen`. If the comma is absent we have a paren; if it's present
    // we have a tuple (possibly 1-arity if no more elements follow).
    let paren_or_tuple = just(TokenKind::LParen)
        .ignore_then(expr.clone())
        .then(
            just(TokenKind::Comma)
                .ignore_then(
                    expr.clone()
                        .separated_by(just(TokenKind::Comma))
                        .allow_trailing()
                        .collect::<Vec<_>>(),
                )
                .or_not(),
        )
        .then_ignore(just(TokenKind::RParen))
        .map_with(|(first, rest), e| match rest {
            None => Expr::Paren(ParenExpr {
                inner: Box::new(first),
                span: span_from_extra(e),
            }),
            Some(rest) => {
                let mut elems = Vec::with_capacity(1 + rest.len());
                elems.push(first);
                elems.extend(rest);
                Expr::Tuple(TupleExpr {
                    elems,
                    span: span_from_extra(e),
                })
            }
        });
    let paren_expr = paren_or_tuple;

    // Block expression
    let block_expr = block_parser(expr.clone());

    // Comptime block expression: comptime { expr }
    let comptime_expr = just(TokenKind::Comptime)
        .ignore_then(block_parser(expr.clone()))
        .map_with(|inner_expr, e| {
            Expr::Comptime(ComptimeBlockExpr {
                expr: Box::new(inner_expr),
                span: span_from_extra(e),
            })
        });

    // Checked block expression: checked { expr }
    // Unchecked operations are only allowed inside checked blocks
    let checked_expr = just(TokenKind::Checked)
        .ignore_then(block_parser(expr.clone()))
        .map_with(|inner_expr, e| {
            Expr::Checked(CheckedBlockExpr {
                expr: Box::new(inner_expr),
                span: span_from_extra(e),
            })
        });

    // Intrinsic argument: can be either a type or an expression
    // We parse as type only for unambiguous type syntax (primitives, (), !, [T;N])
    // Bare identifiers are parsed as expressions since they could be variables
    let unambiguous_type = {
        // Unit type: ()
        let unit_type = just(TokenKind::LParen)
            .then(just(TokenKind::RParen))
            .map_with(|_, e| IntrinsicArg::Type(TypeExpr::Unit(span_from_extra(e))));

        // Never type: !
        let never_type = just(TokenKind::Bang)
            .map_with(|_, e| IntrinsicArg::Type(TypeExpr::Never(span_from_extra(e))));

        // Array type: [T; N]
        let array_type = just(TokenKind::LBracket)
            .ignore_then(type_parser())
            .then_ignore(just(TokenKind::Semi))
            .then(select! {
                TokenKind::Int(n) => n,
            })
            .then_ignore(just(TokenKind::RBracket))
            .map_with(|(element, length), e| {
                IntrinsicArg::Type(TypeExpr::Array {
                    element: Box::new(element),
                    length,
                    span: span_from_extra(e),
                })
            });

        // Primitive type keywords (these can't be variable names)
        let primitive_type = primitive_type_parser().map(IntrinsicArg::Type);

        // ADR-0079: `Self` as a type argument (e.g.
        // `@type_info(Self)` inside a `derive` body). The bare
        // keyword can't appear as a value, so it's unambiguous in
        // this slot.
        let self_type_arg = just(TokenKind::SelfType).map_with(|_, e| {
            let span = span_from_extra(e);
            IntrinsicArg::Type(TypeExpr::Named(Ident {
                name: e.state().syms.self_type,
                span,
            }))
        });

        choice((
            unit_type.boxed(),
            never_type.boxed(),
            array_type.boxed(),
            primitive_type.boxed(),
            self_type_arg.boxed(),
        ))
        .boxed()
    };

    // Try unambiguous type syntax first, then fall back to expression.
    // Boxed so the SeparatedBy type is short when used in intrinsic_call args.
    let intrinsic_arg: GruelParser<I, IntrinsicArg> = choice((
        unambiguous_type,
        expr.clone().map(IntrinsicArg::Expr).boxed(),
    ))
    .boxed();

    // Shared intrinsic args parser (boxed to keep downstream types short).
    let intrinsic_args: GruelParser<I, Vec<IntrinsicArg>> = intrinsic_arg
        .separated_by(just(TokenKind::Comma))
        .allow_trailing()
        .collect::<Vec<_>>()
        .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen))
        .boxed();

    // Intrinsic call: @name(args)
    let intrinsic_call: GruelParser<I, Expr> = just(TokenKind::At)
        .ignore_then(ident_parser())
        .then(intrinsic_args.clone())
        .map_with(|(name, args), e| {
            Expr::IntrinsicCall(IntrinsicCallExpr {
                name,
                args,
                span: span_from_extra(e),
            })
        })
        .boxed();

    // @import(args) - lexer tokenizes @import as a single token with interned "import" Spur
    let import_call: GruelParser<I, Expr> = select! {
        TokenKind::AtImport(import_spur) = e => (import_spur, span_from_extra(e)),
    }
    .then(intrinsic_args)
    .map_with(|((import_spur, import_span), args), e| {
        Expr::IntrinsicCall(IntrinsicCallExpr {
            name: Ident {
                name: import_spur,
                span: import_span,
            },
            args,
            span: span_from_extra(e),
        })
    })
    .boxed();

    // Combined intrinsic parser: try @import first, then general @name pattern
    let any_intrinsic_call: GruelParser<I, Expr> = choice((import_call, intrinsic_call)).boxed();

    // Array literal: [expr, expr, ...]
    let array_lit = args_parser(expr.clone())
        .delimited_by(just(TokenKind::LBracket), just(TokenKind::RBracket))
        .map_with(|elements, e| {
            Expr::ArrayLit(ArrayLitExpr {
                elements,
                span: span_from_extra(e),
            })
        });

    // ADR-0071: associated-function call on the `char` primitive:
    //   `char::name(args)` — produces an `AssocFnCall` with type_name = "char".
    // This must be tried before `type_lit_expr` because `type_lit_expr`
    // consumes a bare `char` token and the `::name(...)` tail wouldn't fit.
    let char_assoc_fn_call = just(TokenKind::Char)
        .ignore_then(just(TokenKind::ColonColon))
        .ignore_then(ident_parser())
        .then(
            call_args_parser(expr.clone())
                .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)),
        )
        .map_with(
            |(function, args), e: &mut MapExtra<'src, '_, I, ParserExtras<'src>>| {
                let syms = e.state().0.syms;
                let span = span_from_extra(e);
                Expr::AssocFnCall(AssocFnCallExpr {
                    base: None,
                    type_name: Ident {
                        name: syms.char,
                        span,
                    },
                    type_args: Vec::new(),
                    function,
                    args,
                    span,
                })
            },
        );

    // Type literal expression: i32, bool, etc. used as values
    // This enables generic function calls like identity(i32, 42)
    let type_lit_expr = primitive_type_parser().map_with(|type_expr, e| {
        Expr::TypeLit(TypeLitExpr {
            type_expr,
            span: span_from_extra(e),
        })
    });

    // `Self` used as a value — e.g. `helper(Self, T)` passing the
    // current struct's type as a comptime argument. The more specific
    // `Self { ... }` (struct literal), `Self::Variant(...)`
    // (associated function / enum variant), and `Self { ... }` enum
    // struct literal forms are parsed earlier in the choice and bind
    // first; bare `Self` here falls through to a plain type-literal
    // expression.
    let self_as_value_expr = just(TokenKind::SelfType).map_with(|_, e| {
        let span = span_from_extra(e);
        Expr::TypeLit(TypeLitExpr {
            type_expr: TypeExpr::Named(Ident {
                name: e.state().syms.self_type,
                span,
            }),
            span,
        })
    });

    // Anonymous struct type as expression: struct { field: Type, ... fn method(...) { ... } ... }
    // This enables comptime type construction like:
    //   fn Pair(comptime T: type) -> type { struct { first: T, second: T } }
    // With methods (Zig-style):
    //   fn Vec(comptime T: type) -> type { struct { ptr: u64, fn push(self, item: T) { ... } } }
    let anon_struct_field: GruelParser<'src, I, AnonStructField> = ident_parser()
        .then_ignore(just(TokenKind::Colon))
        .then(type_parser())
        .map_with(|(name, field_ty), e| AnonStructField {
            doc: None,
            name,
            ty: field_ty,
            span: span_from_extra(e),
        })
        .boxed();

    let anon_struct_fields: GruelParser<'src, I, Vec<AnonStructField>> = anon_struct_field
        .separated_by(just(TokenKind::Comma))
        .allow_trailing()
        .collect::<Vec<_>>()
        .boxed();

    // Parse method for anonymous struct using inline method parsing
    // Methods inside anonymous structs follow the same syntax as impl block methods
    let anon_struct_method = anon_struct_method_parser(expr.clone());

    // ADR-0083 Phase 4: posture is now declared exclusively via the
    // `@mark(...)` directive. The `posture` field on the AST nodes survives
    // only as the directive-derived storage; sema populates it from the
    // directive list at registration time. No posture keyword is parsed
    // here.
    let anon_struct_header: GruelParser<'src, I, (Directives, Vec<AnonStructField>, Vec<Method>)> =
        directives_parser()
            .then_ignore(just(TokenKind::Struct))
            .then_ignore(just(TokenKind::LBrace))
            .then(anon_struct_fields)
            .then(
                // Then parse methods (not comma-separated, each ends with })
                anon_struct_method.repeated().collect::<Vec<_>>(),
            )
            .map(|((directives, fields), methods)| (directives, fields, methods))
            .boxed();

    let anon_struct_type_expr = anon_struct_header
        .then_ignore(just(TokenKind::RBrace))
        .map_with(|(directives, fields, methods), e| {
            let span = span_from_extra(e);
            Expr::TypeLit(TypeLitExpr {
                type_expr: TypeExpr::AnonymousStruct {
                    directives,
                    posture: Posture::Affine,
                    fields,
                    methods,
                    span,
                },
                span,
            })
        });

    // Anonymous function expression (ADR-0055): fn(params) -> ret { body }
    //
    // Reuses the named-function production verbatim, minus the identifier. At
    // expression position `fn` is unambiguous — it is never otherwise an
    // expression starter — so this does not conflict with anything.
    let anon_fn_expr: GruelParser<'src, I, Expr> = just(TokenKind::Fn)
        .ignore_then(params_parser().delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)))
        .then(just(TokenKind::Arrow).ignore_then(type_parser()).or_not())
        .then(block_parser(expr.clone()))
        .map_with(|((params, return_type), body), e| {
            let body_block = match body {
                Expr::Block(b) => b,
                _ => unreachable!("block_parser always returns Expr::Block"),
            };
            Expr::AnonFn(AnonFnExpr {
                params,
                return_type,
                body: body_block,
                span: span_from_extra(e),
            })
        })
        .boxed();

    // Anonymous enum type as expression: enum { Variant, Variant(T), ... fn method(...) { ... } ... }
    // This enables comptime type construction like:
    //   fn Option(comptime T: type) -> type { enum { Some(T), None } }
    let anon_enum_method = anon_struct_method_parser(expr.clone());

    // ADR-0083 Phase 4: same posture-keyword retirement for anonymous
    // enum literals — directive list only.
    let anon_enum_type_expr = directives_parser()
        .then_ignore(just(TokenKind::Enum))
        .then_ignore(just(TokenKind::LBrace))
        .then(enum_variants_parser())
        .then(
            // Then parse methods (not comma-separated, each ends with })
            anon_enum_method.repeated().collect::<Vec<_>>(),
        )
        .then_ignore(just(TokenKind::RBrace))
        .map_with(|((directives, variants), methods), e| {
            let span = span_from_extra(e);
            Expr::TypeLit(TypeLitExpr {
                type_expr: TypeExpr::AnonymousEnum {
                    directives,
                    posture: Posture::Affine,
                    variants,
                    methods,
                    span,
                },
                span,
            })
        });

    // Anonymous interface type as expression (ADR-0057):
    //   interface { fn name(self [, params]) [-> RetType]; ... }
    // Used inside `fn ... -> type` bodies to build parameterized
    // interfaces.
    let anon_interface_type_expr = just(TokenKind::Interface)
        .ignore_then(just(TokenKind::LBrace))
        .ignore_then(interface_method_sig_parser().repeated().collect::<Vec<_>>())
        .then_ignore(just(TokenKind::RBrace))
        .map_with(|methods, e| {
            let span = span_from_extra(e);
            Expr::TypeLit(TypeLitExpr {
                type_expr: TypeExpr::AnonymousInterface { methods, span },
                span,
            })
        });

    // Self type expression: Self { field: value } (struct literal with Self as type)
    // This enables constructing instances of anonymous struct types from methods
    let self_type_expr = just(TokenKind::SelfType)
        .ignore_then(
            field_inits_parser(expr.clone())
                .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
        )
        .map_with(|fields, e| {
            let span = span_from_extra(e);
            Expr::StructLit(StructLitExpr {
                base: None,
                name: Ident {
                    name: e.state().syms.self_type,
                    span,
                },
                fields,
                span,
            })
        });

    // Self::Variant(args) — associated function call on Self (for anonymous enum variant construction)
    let self_assoc_fn_call = just(TokenKind::SelfType)
        .ignore_then(just(TokenKind::ColonColon))
        .ignore_then(ident_parser())
        .then(
            call_args_parser(expr.clone())
                .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)),
        )
        .map_with(|(function, args), e| {
            let span = span_from_extra(e);
            Expr::AssocFnCall(AssocFnCallExpr {
                base: None,
                type_name: Ident {
                    name: e.state().syms.self_type,
                    span,
                },
                type_args: Vec::new(),
                function,
                args,
                span,
            })
        });

    // Self::Variant { field: value, ... } — struct variant construction on Self
    let self_enum_struct_lit = just(TokenKind::SelfType)
        .ignore_then(just(TokenKind::ColonColon))
        .ignore_then(ident_parser())
        .then(
            field_inits_parser(expr.clone())
                .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
        )
        .map_with(|(variant, fields), e| {
            let span = span_from_extra(e);
            Expr::EnumStructLit(EnumStructLitExpr {
                base: None,
                type_name: Ident {
                    name: e.state().syms.self_type,
                    span,
                },
                variant,
                fields,
                span,
            })
        });

    // Self::Variant — unit variant on Self (for anonymous enum variant construction)
    let self_enum_variant = just(TokenKind::SelfType)
        .ignore_then(just(TokenKind::ColonColon))
        .ignore_then(ident_parser())
        .then_ignore(none_of([TokenKind::LParen, TokenKind::LBrace]).rewind())
        .map_with(|variant, e| {
            let span = span_from_extra(e);
            Expr::Path(PathExpr {
                base: None,
                type_name: Ident {
                    name: e.state().syms.self_type,
                    span,
                },
                variant,
                span,
            })
        });

    // Primary expression (before field access and indexing)
    // Note: literal_parser() includes unit_lit which must come before paren_expr
    // so () is parsed as unit, not empty parens
    // Note: self_expr must come before call_and_access_parser since self is a keyword
    // Note: self_type_expr must come before call_and_access_parser since Self is a keyword
    // Note: comptime_expr and checked_expr must come before block_expr since they start with keywords
    // Note: type_lit_expr must come before call_and_access_parser since type names are keywords
    // Note: anon_struct_type_expr / anon_enum_type_expr must come before
    // any_intrinsic_call: ADR-0083's `@mark(...)` is a directive that
    // appears in the directive list of an anonymous type literal, but the
    // parser otherwise parses `@name(args)` as an intrinsic call. Trying the
    // anon-type form first lets `directives_parser()` consume the leading
    // `@mark(copy)`, then the trailing `struct` / `enum` keyword
    // disambiguates from a plain intrinsic call.
    //
    // NOTE: Split into sub-groups to keep Choice<tuple> symbol length < 4K.
    // 13 elements of Boxed<I,Expr,E> in one tuple would produce ~7K symbols on macOS.
    let primary_a: GruelParser<'src, I, Expr> = choice((
        literal_parser(),
        control_flow_parser(expr.clone()),
        self_expr.boxed(),
        self_assoc_fn_call.boxed(),
        self_enum_struct_lit.boxed(),
        self_enum_variant.boxed(),
        self_type_expr.boxed(),
        anon_struct_type_expr.boxed(),
        anon_enum_type_expr.boxed(),
        any_intrinsic_call.boxed(),
    ))
    .boxed();
    let primary_b: GruelParser<'src, I, Expr> = choice((
        array_lit.boxed(),
        anon_interface_type_expr.boxed(),
        anon_fn_expr,
        // ADR-0071: must come before type_lit_expr (which consumes the `char` token alone).
        char_assoc_fn_call.boxed(),
        type_lit_expr.boxed(),
        // Bare `Self` as a value — the more-specific Self forms above
        // (`self_type_expr` for `Self { ... }`, `self_assoc_fn_call`
        // for `Self::method(...)`, etc.) are tried first; this falls
        // through to it for `Self` followed by `,`, `)`, `;` etc.
        self_as_value_expr.boxed(),
        call_and_access_parser(expr.clone()),
        paren_expr.boxed(),
    ))
    .boxed();
    let primary_c: GruelParser<'src, I, Expr> = choice((
        comptime_expr.boxed(),
        checked_expr.boxed(),
        block_expr.boxed(),
    ))
    .boxed();
    let primary: GruelParser<'src, I, Expr> = choice((primary_a, primary_b, primary_c)).boxed();

    // Wrap primary expressions with field access, method call, and indexing suffixes
    with_suffix_parser(primary, expr)
}

/// A block item is either a statement or an expression (potentially the final one)
#[derive(Debug, Clone)]
enum BlockItem {
    Statement(Statement),
    Expr(Expr),
}

/// What token follows an expression in a block (used to determine its role)
#[derive(Debug, Clone, Copy)]
enum ExprFollower {
    /// Semicolon follows - expression is a statement
    Semi,
    /// Right brace follows (not consumed) - expression is the final/return value
    RBrace,
    /// Some other token follows - only valid for control flow expressions
    Other,
    /// End of input - only valid for control flow expressions
    End,
}

/// Parser for a let binding pattern (ADR-0049): delegates to the generic
/// `pattern_parser()`. Refutability is enforced by sema (Phase 3).
/// Nested pattern shapes are accepted unconditionally after Phase 8
/// stabilization.
fn let_pattern_parser<'src, I>() -> GruelParser<'src, I, Pattern>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    pattern_parser()
}

/// Parser for let statements: [@directive]* let [mut] pattern [: type] = expr;
fn let_statement_parser<'src, I>(
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, Statement>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Box after 2 thens to keep accumulated type short.
    let let_head: GruelParser<I, (Directives, bool, Pattern)> = directives_parser()
        .then(just(TokenKind::Let).ignore_then(just(TokenKind::Mut).or_not().map(|m| m.is_some())))
        .then(let_pattern_parser())
        .map(|((d, m), p)| (d, m, p))
        .boxed();

    let let_tail: GruelParser<I, (Option<TypeExpr>, Expr)> = just(TokenKind::Colon)
        .ignore_then(type_parser())
        .or_not()
        .then(just(TokenKind::Eq).ignore_then(expr))
        .then_ignore(just(TokenKind::Semi))
        .boxed();

    let_head
        .then(let_tail)
        .map_with(|((directives, is_mut, pattern), (ty, init)), e| {
            Statement::Let(LetStatement {
                directives,
                is_mut,
                pattern,
                ty,
                init: Box::new(init),
                span: span_from_extra(e),
            })
        })
        .boxed()
}

/// Suffix for assignment targets: either .field or [index]
#[derive(Clone)]
enum AssignSuffix {
    Field(Ident),
    Index(Expr),
}

/// Parser for assignment target: variable, field access, or index access
/// Parses: name or name.field or name[idx] or name.field[idx].field...
fn assign_target_parser<'src, I>(
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, AssignTarget>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let field_suffix = just(TokenKind::Dot)
        .ignore_then(ident_parser())
        .map(AssignSuffix::Field);

    let index_suffix = expr
        .delimited_by(just(TokenKind::LBracket), just(TokenKind::RBracket))
        .map(AssignSuffix::Index);

    // Assignment base: a regular identifier OR `self` (so a method body can
    // write through `&mut self`, e.g. `self.value = ...`). Plain `self =
    // expr;` is rejected later in sema since `self` is not a place that can
    // be rebound.
    let self_base = just(TokenKind::SelfValue)
        .map_with(|_, e| {
            Expr::SelfExpr(SelfExpr {
                span: span_from_extra(e),
            })
        })
        .boxed();
    let ident_base = ident_parser().map(Expr::Ident).boxed();
    let assign_base = choice((self_base, ident_base)).boxed();

    assign_base
        .then(
            choice((field_suffix.boxed(), index_suffix.boxed()))
                .repeated()
                .collect::<Vec<_>>(),
        )
        .try_map(|(base_expr_init, suffixes), span| {
            if suffixes.is_empty() {
                // Simple variable target: only `name = ...` is legal.
                // `self = ...` is not — `self` is a parameter binding that
                // can't be rebound. Reject at parse time.
                return match base_expr_init {
                    Expr::Ident(ident) => Ok(AssignTarget::Var(ident)),
                    _ => Err(chumsky::error::Rich::custom(
                        span,
                        "cannot assign to `self`",
                    )),
                };
            }
            // Chain of field/index accesses: x.a[0].b...
            // Build up the expression from left to right, consuming suffixes by value.
            let mut base_expr = base_expr_init;
            let mut suffixes_iter = suffixes.into_iter().peekable();
            while let Some(suffix) = suffixes_iter.next() {
                let is_last = suffixes_iter.peek().is_none();
                if is_last {
                    return Ok(match suffix {
                        AssignSuffix::Field(field) => {
                            let span = Span::new(base_expr.span().start, field.span.end);
                            AssignTarget::Field(FieldExpr {
                                base: Box::new(base_expr),
                                field,
                                span,
                            })
                        }
                        AssignSuffix::Index(index) => {
                            let span = Span::new(base_expr.span().start, index.span().end);
                            AssignTarget::Index(IndexExpr {
                                base: Box::new(base_expr),
                                index: Box::new(index),
                                span,
                            })
                        }
                    });
                }
                // Build intermediate expressions
                match suffix {
                    AssignSuffix::Field(field) => {
                        let span = Span::new(base_expr.span().start, field.span.end);
                        base_expr = Expr::Field(FieldExpr {
                            base: Box::new(base_expr),
                            field,
                            span,
                        });
                    }
                    AssignSuffix::Index(index) => {
                        let span = Span::new(base_expr.span().start, index.span().end);
                        base_expr = Expr::Index(IndexExpr {
                            base: Box::new(base_expr),
                            index: Box::new(index),
                            span,
                        });
                    }
                }
            }
            unreachable!("suffixes was non-empty so the loop must have returned")
        })
        .boxed()
}

/// Parser for assignment statements: target = expr;
/// Supports variable (x = 5), field (point.x = 5), and index (arr[0] = 5) assignment
fn assign_statement_parser<'src, I>(
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, Statement>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    assign_target_parser(expr.clone())
        .then_ignore(just(TokenKind::Eq))
        .then(expr)
        .then_ignore(just(TokenKind::Semi))
        .map_with(|(target, value), e| {
            Statement::Assign(AssignStatement {
                target,
                value: Box::new(value),
                span: span_from_extra(e),
            })
        })
        .boxed()
}

/// Returns true if the expression is a control flow construct or block that can appear
/// as a statement without a trailing semicolon.
///
/// This includes:
/// - Control flow: if, while, match, loop, break, continue, return
/// - Block expressions: { ... }
///
/// Block expressions are included because they are syntactically similar to control flow:
/// they are compound statements that naturally terminate without a semicolon.
fn is_control_flow_expr(e: &Expr) -> bool {
    matches!(
        e,
        Expr::If(_)
            | Expr::Match(_)
            | Expr::While(_)
            | Expr::For(_)
            | Expr::ComptimeUnrollFor(_)
            | Expr::Loop(_)
            | Expr::Break(_)
            | Expr::Continue(_)
            | Expr::Return(_)
            | Expr::Block(_)
    )
}

/// Returns true if the expression diverges (has the Never type).
/// These expressions can be promoted to the final expression of a block
/// since Never coerces to any type.
fn is_diverging_expr(e: &Expr) -> bool {
    matches!(
        e,
        Expr::Break(_) | Expr::Continue(_) | Expr::Return(_) | Expr::Loop(_)
    )
}

/// Parses a single item within a block.
///
/// # Block Item Grammar
///
/// A block contains zero or more items. Each item is one of:
/// - **Let statement**: `let x = expr;` (always requires semicolon)
/// - **Assignment statement**: `target = expr;` (always requires semicolon)
/// - **Expression statement**: `expr;` (requires semicolon for most expressions)
/// - **Control flow statement**: `if/while/match/loop/break/continue/return ...`
///   (no semicolon needed when mid-block)
/// - **Final expression**: `expr` at the very end of a block (no semicolon, becomes
///   the block's return value)
///
/// # Parsing Strategy: Lookahead with `rewind()`
///
/// The challenge is distinguishing between:
/// 1. `{ foo; bar }` - `foo;` is a statement, `bar` is the final expression
/// 2. `{ if c { 1 } else { 2 } x }` - the `if` is a statement, `x` is final
/// 3. `{ if c { 1 } else { 2 } }` - the `if` IS the final expression
///
/// We use `rewind()` as a non-consuming lookahead to peek at what follows:
///
/// - `none_of([RBrace, Semi]).rewind()`: Succeeds if the NEXT token is neither
///   `}` nor `;`. The `.rewind()` means we check without consuming the token.
///   This identifies control flow in the middle of a block.
///
/// - `just(RBrace).rewind()`: Succeeds if the NEXT token is `}`. This identifies
///   the final expression of a block.
///
/// # Why `try_map()` for Control Flow?
///
/// After parsing an expression followed by a non-`}` non-`;` token, we need to
/// validate it's actually a control flow expression. If it's something like `x`
/// followed by `y`, that's a syntax error (missing semicolon). We use `try_map()`
/// to:
/// 1. Accept the parse if it's a control flow expression (valid without semicolon)
/// 2. Reject it otherwise, allowing chumsky to backtrack and try other branches
///
/// # Parse Order Matters
///
/// The `choice()` tries parsers in order. We must try:
/// 1. `let_stmt` first (starts with `let` keyword)
/// 2. `assign_stmt` second (identifier followed by `.`/`[` chain then `=`)
/// 3. `expr_with_semi` (any expression followed by `;`)
/// 4. `control_flow_stmt` (control flow NOT followed by `}` - mid-block)
/// 5. `final_expr` (any expression followed by `}` - end of block)
///
/// The assignment parser is tried before general expressions because `x = 5;`
/// could otherwise be misparsed as expression `x` followed by unexpected `=`.
fn block_item_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, BlockItem>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Let statement: `let x: T = expr;`
    // Always requires a trailing semicolon.
    let let_stmt = let_statement_parser(expr.clone()).map(BlockItem::Statement);

    // Assignment statement: `target = expr;`
    // Target can be: variable (`x`), field (`a.b.c`), or index (`a[i]`).
    // Always requires a trailing semicolon.
    let assign_stmt = assign_statement_parser(expr.clone()).map(BlockItem::Statement);

    // Expression-based item: parse expression ONCE, then decide based on what follows.
    // This avoids O(2^n) complexity from repeatedly re-parsing expressions with backtracking.
    //
    // After parsing an expression, we check the next token:
    // - `;` → expression statement (value discarded)
    // - `}` → final expression (block's return value)
    // - other → mid-block control flow (only valid for if/while/match/loop/break/continue/return)
    let expr_item = expr
        .then(
            choice((
                just(TokenKind::Semi).to(ExprFollower::Semi).boxed(),
                just(TokenKind::RBrace)
                    .rewind()
                    .to(ExprFollower::RBrace)
                    .boxed(),
                any().rewind().to(ExprFollower::Other).boxed(),
            ))
            .or(end().to(ExprFollower::End)),
        )
        .try_map(|(e, follower), span| match follower {
            ExprFollower::Semi => {
                // Expression followed by semicolon: `expr;`
                Ok(BlockItem::Statement(Statement::Expr(e)))
            }
            ExprFollower::RBrace => {
                // Final expression: `{ ... expr }`
                Ok(BlockItem::Expr(e))
            }
            ExprFollower::Other | ExprFollower::End => {
                // Mid-block control flow (no semicolon, not at end)
                // Only control flow expressions are valid here
                if is_control_flow_expr(&e) {
                    Ok(BlockItem::Statement(Statement::Expr(e)))
                } else {
                    Err(Rich::custom(span, "expected semicolon after expression"))
                }
            }
        });

    // Try parsers in order. Earlier parsers take precedence.
    // This order ensures:
    // - Keywords (`let`) are matched before being parsed as identifiers
    // - Assignments (`x = 5;`) are matched before `x` is parsed as an expression
    choice((let_stmt.boxed(), assign_stmt.boxed(), expr_item.boxed())).boxed()
}

/// Process block items into statements and final expression
fn process_block_items(items: Vec<BlockItem>, block_span: Span) -> (Vec<Statement>, Expr) {
    let mut statements = Vec::new();
    let mut final_expr = None;

    for item in items {
        match item {
            BlockItem::Statement(stmt) => {
                // Had a non-semicolon expr before, but now we have more items
                // This shouldn't happen with correct grammar, but handle gracefully
                if let Some(e) = final_expr.take() {
                    statements.push(Statement::Expr(e));
                }
                statements.push(stmt);
            }
            BlockItem::Expr(e) => {
                if let Some(prev) = final_expr.take() {
                    // Had a non-semicolon expr before this one - that's invalid
                    // but we'll treat the previous as a statement for error recovery
                    statements.push(Statement::Expr(prev));
                }
                final_expr = Some(e);
            }
        }
    }

    let expr = final_expr.unwrap_or_else(|| {
        // No explicit final expression. Check if the last statement is a diverging
        // expression (break, continue, return) - if so, promote it to the final
        // expression since it has type Never which coerces to any type.
        if let Some(Statement::Expr(e)) = statements.last()
            && is_diverging_expr(e)
        {
            // Safe to unwrap: we just checked last() is Some(Statement::Expr(_))
            let Statement::Expr(e) = statements.pop().unwrap() else {
                unreachable!()
            };
            return e;
        }
        // Fallback: use a unit expression (block produces unit type)
        Expr::Unit(UnitLit {
            span: Span::new(block_span.end, block_span.end),
        })
    });

    (statements, expr)
}

/// Parser for blocks that may end without a final expression (for if/while bodies)
fn maybe_unit_block_parser<'src, I>(
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, BlockExpr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    block_item_parser(expr)
        .repeated()
        .collect::<Vec<_>>()
        .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace))
        .map_with(|items, e| {
            let span = span_from_extra(e);
            let (statements, final_expr) = process_block_items(items, span);
            BlockExpr {
                statements,
                expr: Box::new(final_expr),
                span,
            }
        })
        .boxed()
}

/// Parser for blocks that require a final expression: { statements... expr }
fn block_parser<'src, I>(expr: GruelParser<'src, I, Expr>) -> GruelParser<'src, I, Expr>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    block_item_parser(expr)
        .repeated()
        .collect::<Vec<_>>()
        .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace))
        .map_with(|items, e| {
            let span = span_from_extra(e);
            let (statements, final_expr) = process_block_items(items, span);
            Expr::Block(BlockExpr {
                statements,
                expr: Box::new(final_expr),
                span,
            })
        })
        .boxed()
}

/// Parser for function definitions: [@directive]* [pub] fn name(params) -> Type { body }
///
/// ADR-0088 Phase 6 retired the `unchecked` hard keyword in favour
/// of the `@mark(unchecked)` directive.
fn function_parser<'src, I>() -> GruelParser<'src, I, Function>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let expr = expr_parser();

    // Parse optional visibility (pub keyword)
    let visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });

    let fn_head: GruelParser<I, (Directives, Visibility)> =
        directives_parser().then(visibility).boxed();

    let fn_sig: GruelParser<I, (Ident, Vec<Param>)> = just(TokenKind::Fn)
        .ignore_then(ident_parser())
        .then(params_parser().delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)))
        .boxed();

    fn_head
        .then(fn_sig)
        .then(just(TokenKind::Arrow).ignore_then(type_parser()).or_not())
        .then(block_parser(expr))
        .map_with(
            |((((directives, visibility), (name, params)), return_type), body), e| {
                let syms = e.state().0.syms;
                let is_unchecked = directives_have_mark_unchecked(
                    &directives,
                    syms.mark_name,
                    syms.unchecked_name,
                );
                Function {
                    doc: None,
                    directives,
                    visibility,
                    is_unchecked,
                    name,
                    params,
                    return_type,
                    body,
                    span: span_from_extra(e),
                }
            },
        )
        .boxed()
}

/// Parser for struct definitions with inline methods:
/// [@directive]* [pub] struct Name { field: Type, ... fn method(self) { ... } }
///
/// Posture (`copy`/`linear`/`affine`) is declared via `@mark(...)` in the
/// leading directive list (ADR-0083 Phase 4); there is no head keyword.
///
/// Fields come first (comma-separated), then methods (no separators needed).
fn struct_parser<'src, I>() -> GruelParser<'src, I, StructDecl>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Parse optional visibility (pub keyword)
    let visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });

    // ADR-0083 Phase 4: posture is declared via `@mark(...)` only;
    // the head no longer accepts the keyword form.
    let struct_head: GruelParser<I, (Directives, Visibility, Ident)> = directives_parser()
        .then(visibility)
        .then(just(TokenKind::Struct).ignore_then(ident_parser()))
        .map(|((d, v), name)| (d, v, name))
        .boxed();

    // Box the struct body so DelimitedBy wraps a short Boxed type.
    let struct_body: GruelParser<I, (Vec<FieldDecl>, Vec<Method>)> = field_decls_parser()
        .then(method_parser().repeated().collect::<Vec<_>>())
        .boxed();

    struct_head
        .then(struct_body.delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)))
        .map_with(
            |((directives, visibility, name), (fields, methods)), e| StructDecl {
                doc: None,
                directives,
                visibility,
                posture: Posture::Affine,
                name,
                fields,
                methods,
                span: span_from_extra(e),
            },
        )
        .boxed()
}

/// Parser for enum variant: unit, tuple `(Type, ...)`, or struct `{ field: Type, ... }`
fn enum_variant_parser<'src, I>() -> GruelParser<'src, I, EnumVariant>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    use crate::ast::{EnumVariantField, EnumVariantKind};

    // Tuple-style fields: (Type, Type, ...)
    let tuple_fields = type_parser()
        .separated_by(just(TokenKind::Comma))
        .allow_trailing()
        .collect::<Vec<_>>()
        .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen));

    // Struct-style fields: { [pub] name: Type, ... }  (ADR-0073)
    let variant_field_visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });
    let struct_field = variant_field_visibility
        .then(ident_parser())
        .then_ignore(just(TokenKind::Colon))
        .then(type_parser())
        .map_with(|((visibility, name), ty), e| EnumVariantField {
            doc: None,
            visibility,
            name,
            ty,
            span: span_from_extra(e),
        });
    let struct_fields = struct_field
        .separated_by(just(TokenKind::Comma))
        .allow_trailing()
        .collect::<Vec<_>>()
        .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace));

    // Combine: name + optional (tuple | struct) fields
    let variant_kind = choice((
        tuple_fields.map(EnumVariantKind::Tuple),
        struct_fields.map(EnumVariantKind::Struct),
    ))
    .or_not()
    .map(|opt| opt.unwrap_or(EnumVariantKind::Unit));

    ident_parser()
        .then(variant_kind)
        .map_with(|(name, kind), e| EnumVariant {
            doc: None,
            name,
            kind,
            span: span_from_extra(e),
        })
        .boxed()
}

/// Parser for comma-separated enum variants
fn enum_variants_parser<'src, I>() -> GruelParser<'src, I, Vec<EnumVariant>>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    enum_variant_parser()
        .separated_by(just(TokenKind::Comma))
        .allow_trailing()
        .collect::<Vec<_>>()
        .boxed()
}

/// Parser for enum definitions: [@directive]* [pub] enum Name { Variant1, Variant2, ... fn method(self) { ... } }
///
/// Posture (`copy`/`linear`/`affine`) is declared via `@mark(...)` in the
/// leading directive list (ADR-0083 Phase 4); there is no head keyword.
///
/// Variants come first (comma-separated), then methods (no separators needed),
/// mirroring the struct body shape.
fn enum_parser<'src, I>() -> GruelParser<'src, I, EnumDecl>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Parse optional visibility (pub keyword)
    let visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });

    // ADR-0083 Phase 4: posture is declared via `@mark(...)` only.
    let enum_body: GruelParser<I, (Vec<EnumVariant>, Vec<Method>)> = enum_variants_parser()
        .then(method_parser().repeated().collect::<Vec<_>>())
        .boxed();

    directives_parser()
        .then(visibility)
        .then(just(TokenKind::Enum).ignore_then(ident_parser()))
        .then(enum_body.delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)))
        .map_with(
            |(((directives, visibility), name), (variants, methods)), e| EnumDecl {
                doc: None,
                directives,
                visibility,
                posture: Posture::Affine,
                name,
                variants,
                methods,
                span: span_from_extra(e),
            },
        )
        .boxed()
}

/// Parser for method definitions: [@directive]* fn name(self, params) -> Type { body }
/// Methods differ from functions in that they can have `self` as the first parameter.
fn method_parser<'src, I>() -> GruelParser<'src, I, Method>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let expr = expr_parser();
    method_parser_with_expr(expr)
}

/// Parser for method definitions inside anonymous structs.
/// Takes an expression parser as a parameter to avoid creating a new one.
fn anon_struct_method_parser<'src, I>(
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, Method>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    method_parser_with_expr(expr)
}

/// Shared implementation for method parsing.
/// Takes an expression parser to allow reuse from different contexts.
fn method_parser_with_expr<'src, I>(
    expr: GruelParser<'src, I, Expr>,
) -> GruelParser<'src, I, Method>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Parse optional self parameter — `self`, `inout self`, or `borrow self`.
    let self_param = self_param_parser();

    // Parse self followed by optional regular params
    let self_then_params = self_param
        .then(
            just(TokenKind::Comma)
                .ignore_then(params_parser())
                .or_not()
                .map(|opt| opt.unwrap_or_default()),
        )
        .map(|(self_param, params)| (Some(self_param), params));

    // Parse just regular params (no self) - this is an associated function
    let just_params = params_parser().map(|params| (None, params));

    // Box params_with_optional_self so DelimitedBy wraps a short type.
    let params_with_optional_self: GruelParser<I, (Option<SelfParam>, Vec<Param>)> =
        choice((self_then_params.boxed(), just_params.boxed())).boxed();

    // Box the method head early to keep subsequent type accumulation short.
    // Uses method_name_parser so that `fn __drop(self)` parses as a method named "__drop"
    // (ADR-0053 destructor syntax).
    //
    // ADR-0073: optional `pub` prefix sits between any directives and `fn`.
    let method_visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });
    let method_head: GruelParser<I, (Directives, Visibility, Ident)> = directives_parser()
        .then(method_visibility)
        .then(just(TokenKind::Fn).ignore_then(method_name_parser()))
        .map(|((directives, visibility), name)| (directives, visibility, name))
        .boxed();

    let method_params: GruelParser<I, (Option<SelfParam>, Vec<Param>)> = params_with_optional_self
        .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen))
        .boxed();

    let method_return: GruelParser<I, Option<TypeExpr>> = just(TokenKind::Arrow)
        .ignore_then(type_parser())
        .or_not()
        .boxed();

    method_head
        .then(method_params)
        .then(method_return)
        .then(block_parser(expr))
        .map_with(
            |((((directives, visibility, name), (receiver, params)), return_type), body), e| {
                let syms = e.state().0.syms;
                let is_unchecked = directives_have_mark_unchecked(
                    &directives,
                    syms.mark_name,
                    syms.unchecked_name,
                );
                Method {
                    doc: None,
                    directives,
                    visibility,
                    is_unchecked,
                    name,
                    receiver,
                    params,
                    return_type,
                    body,
                    span: span_from_extra(e),
                }
            },
        )
        .boxed()
}

/// Parser for const declarations: [pub] const name [: Type] = expr;
///
/// Used for module re-exports:
/// ```gruel
/// pub const strings = @import("utils/strings.gruel");
/// pub const helper = @import("utils/internal.gruel").helper;
/// ```
fn const_parser<'src, I>() -> GruelParser<'src, I, ConstDecl>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let expr = expr_parser();

    // Parse optional visibility (pub keyword)
    let visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });

    // Box after 2 thens to keep accumulated type short.
    let const_head: GruelParser<I, (Directives, Visibility, Ident)> = directives_parser()
        .then(visibility)
        .then(just(TokenKind::Const).ignore_then(ident_parser()))
        .map(|((d, v), n)| (d, v, n))
        .boxed();

    let const_tail: GruelParser<I, (Option<TypeExpr>, Expr)> = just(TokenKind::Colon)
        .ignore_then(type_parser())
        .or_not()
        .then(just(TokenKind::Eq).ignore_then(expr))
        .then_ignore(just(TokenKind::Semi))
        .boxed();

    const_head
        .then(const_tail)
        .map_with(
            |((directives, visibility, name), (ty, init)), e| ConstDecl {
                doc: None,
                directives,
                visibility,
                name,
                ty,
                init: Box::new(init),
                span: span_from_extra(e),
            },
        )
        .boxed()
}

/// Shared parser for method receivers (ADR-0076 sole form).
/// Used by methods, interface method signatures, and `drop fn`.
///
/// Accepts:
///   `self`                  → ByValue (annotation elided)
///   `self : Self`           → ByValue
///   `self : Ref ( Self )`   → Ref (shared borrow receiver)
///   `self : MutRef ( Self )` → MutRef (exclusive mutable borrow receiver)
fn self_param_parser<'src, I>() -> GruelParser<'src, I, SelfParam>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let typed_byvalue = just(TokenKind::SelfValue)
        .then_ignore(just(TokenKind::Colon))
        .then_ignore(just(TokenKind::SelfType))
        .map_with(|_, e| SelfParam {
            kind: SelfReceiverKind::ByValue,
            span: span_from_extra(e),
        })
        .boxed();

    // `self : Ref ( Self )` and `self : MutRef ( Self )` need to inspect
    // the identifier text since the lexer doesn't tokenize `Ref`/`MutRef`
    // distinctly. Match `TokenKind::Ident(spur)` and resolve the spur.
    let ref_or_mut_ref = any().try_map_with(
        |t: TokenKind, e: &mut chumsky::input::MapExtra<I, ParserExtras<'src>>| match t {
            TokenKind::Ident(s) => {
                let syms = &e.state().syms;
                if s == syms.ref_name {
                    Ok(SelfReceiverKind::Ref)
                } else if s == syms.mut_ref_name {
                    Ok(SelfReceiverKind::MutRef)
                } else {
                    Err(chumsky::error::Rich::custom(
                        e.span(),
                        "expected identifier `Ref` or `MutRef`",
                    ))
                }
            }
            _ => Err(chumsky::error::Rich::custom(
                e.span(),
                "expected identifier `Ref` or `MutRef`",
            )),
        },
    );

    let typed_ref = just(TokenKind::SelfValue)
        .then_ignore(just(TokenKind::Colon))
        .ignore_then(ref_or_mut_ref)
        .then_ignore(just(TokenKind::LParen))
        .then_ignore(just(TokenKind::SelfType))
        .then_ignore(just(TokenKind::RParen))
        .map_with(|kind, e| SelfParam {
            kind,
            span: span_from_extra(e),
        })
        .boxed();

    // Bare `self` (no annotation) is ByValue.
    let bare_self = just(TokenKind::SelfValue)
        .map_with(|_, e| SelfParam {
            kind: SelfReceiverKind::ByValue,
            span: span_from_extra(e),
        })
        .boxed();

    choice((typed_ref, typed_byvalue, bare_self)).boxed()
}

/// Parser for top-level items (functions, structs, enums, drop fns, and consts)
/// Parser for interface method signatures: `[directives]* fn name([recv] self [, params]) [-> Type];`
///
/// `recv` is one of `inout` / `borrow`, or omitted for a by-value receiver.
/// ADR-0088: signatures accept `@mark(unchecked)` in the directive list.
fn interface_method_sig_parser<'src, I>() -> GruelParser<'src, I, MethodSig>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let self_param = self_param_parser();

    let extra_params = just(TokenKind::Comma)
        .ignore_then(params_parser())
        .or_not()
        .map(|opt| opt.unwrap_or_default());

    let receiver_and_params: GruelParser<I, (SelfParam, Vec<Param>)> = self_param
        .then(extra_params)
        .delimited_by(just(TokenKind::LParen), just(TokenKind::RParen))
        .boxed();

    directives_parser()
        .then_ignore(just(TokenKind::Fn))
        .then(method_name_parser())
        .then(receiver_and_params)
        .then(just(TokenKind::Arrow).ignore_then(type_parser()).or_not())
        .then_ignore(just(TokenKind::Semi))
        .map_with(
            |(((directives, name), (receiver, params)), return_type), e| {
                let syms = e.state().0.syms;
                let is_unchecked = directives_have_mark_unchecked(
                    &directives,
                    syms.mark_name,
                    syms.unchecked_name,
                );
                MethodSig {
                    doc: None,
                    directives,
                    is_unchecked,
                    name,
                    receiver,
                    params,
                    return_type,
                    span: span_from_extra(e),
                }
            },
        )
        .boxed()
}

/// Parser for interface declarations (ADR-0056):
///
/// ```text
/// [pub] interface Name {
///     fn method(self [, params]) [-> RetType];
///     ...
/// }
/// ```
fn interface_parser<'src, I>() -> GruelParser<'src, I, InterfaceDecl>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let visibility = just(TokenKind::Pub).or_not().map(|opt| {
        if opt.is_some() {
            Visibility::Public
        } else {
            Visibility::Private
        }
    });

    let body = interface_method_sig_parser()
        .repeated()
        .collect::<Vec<_>>()
        .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace))
        .boxed();

    directives_parser()
        .then(visibility)
        .then(just(TokenKind::Interface).ignore_then(ident_parser()))
        .then(body)
        .map_with(
            |(((directives, visibility), name), methods), e| InterfaceDecl {
                doc: None,
                directives,
                visibility,
                name,
                methods,
                span: span_from_extra(e),
            },
        )
        .boxed()
}

/// Parser for derive declarations (ADR-0058):
///
/// ```text
/// derive Name {
///     fn method(self [, params]) [-> RetType] { body }
///     ...
/// }
/// ```
fn derive_parser<'src, I>() -> GruelParser<'src, I, DeriveDecl>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let body = method_parser()
        .repeated()
        .collect::<Vec<_>>()
        .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace))
        .boxed();

    just(TokenKind::Derive)
        .ignore_then(ident_parser())
        .then(body)
        .map_with(|(name, methods), e| DeriveDecl {
            doc: None,
            name,
            methods,
            span: span_from_extra(e),
        })
        .boxed()
}

/// Parser for a single body-less fn declaration inside a `link_extern`
/// block (ADR-0085).
///
/// Shape: `[@directive]* fn name(params) [-> type] ;`
///
/// Bodies are forbidden here; sema rejects any fn with a body inside a
/// `link_extern` block. `pub` / `unchecked` are also rejected — the
/// extern scope establishes both.
fn extern_fn_parser<'src, I>() -> GruelParser<'src, I, crate::ast::ExternFn>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    directives_parser()
        .then(just(TokenKind::Fn).ignore_then(ident_parser()))
        .then(params_parser().delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)))
        .then(just(TokenKind::Arrow).ignore_then(type_parser()).or_not())
        .then_ignore(just(TokenKind::Semi))
        .map_with(
            |(((directives, name), params), return_type), e| crate::ast::ExternFn {
                doc: None,
                directives,
                name,
                params,
                return_type,
                span: span_from_extra(e),
            },
        )
        .boxed()
}

/// Parser for a `link_extern("libname") { … }` or
/// `static_link_extern("libname") { … }` block (ADR-0085 + ADR-0086).
fn link_extern_parser<'src, I>() -> GruelParser<'src, I, crate::ast::LinkExternBlock>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    let library = select! {
        TokenKind::String(s) = e => StringLit {
            value: s,
            span: span_from_extra(e),
        },
    }
    .boxed();

    let mode_keyword = choice((
        just(TokenKind::LinkExtern).to(crate::ast::LinkMode::Dynamic),
        just(TokenKind::StaticLinkExtern).to(crate::ast::LinkMode::Static),
    ))
    .boxed();

    mode_keyword
        .then(library.delimited_by(just(TokenKind::LParen), just(TokenKind::RParen)))
        .then(
            extern_fn_parser()
                .repeated()
                .collect::<Vec<_>>()
                .delimited_by(just(TokenKind::LBrace), just(TokenKind::RBrace)),
        )
        .map_with(
            |((link_mode, library), items), e| crate::ast::LinkExternBlock {
                doc: None,
                library,
                items,
                link_mode,
                span: span_from_extra(e),
            },
        )
        .boxed()
}

fn item_parser<'src, I>() -> GruelParser<'src, I, Item>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    choice((
        function_parser().map(Item::Function).boxed(),
        struct_parser().map(Item::Struct).boxed(),
        enum_parser().map(Item::Enum).boxed(),
        interface_parser().map(Item::Interface).boxed(),
        derive_parser().map(Item::Derive).boxed(),
        const_parser().map(Item::Const).boxed(),
        link_extern_parser().map(Item::LinkExtern).boxed(),
    ))
    .boxed()
}

/// Parser that matches tokens that can start an item (for recovery).
/// This is a "lookahead" - it peeks but doesn't consume.
fn item_start<'src, I>() -> GruelParser<'src, I, ()>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // NOTE: Split into sub-groups to keep Choice<tuple> symbol length < 4K.
    // 9 elements of Boxed<I,(),E> in one tuple wrapped in Rewind would produce ~5K symbols on macOS.
    let item_start_a: GruelParser<'src, I, ()> = choice((
        just(TokenKind::Fn).ignored().boxed(),
        just(TokenKind::Struct).ignored().boxed(),
        just(TokenKind::Enum).ignored().boxed(),
        just(TokenKind::Interface).ignored().boxed(),
        just(TokenKind::Derive).ignored().boxed(),
        just(TokenKind::Const).ignored().boxed(),
        just(TokenKind::LinkExtern).ignored().boxed(),
    ))
    .boxed();
    let item_start_b: GruelParser<'src, I, ()> = choice((
        just(TokenKind::Pub).ignored().boxed(),
        just(TokenKind::At).ignored().boxed(), // For @directives
    ))
    .boxed();
    choice((item_start_a, item_start_b))
        .rewind() // Peek without consuming
        .boxed()
}

/// Recovery parser that skips tokens until finding an item start.
/// Consumes at least one token to guarantee progress, then skips until
/// we find a token that could start an item.
fn error_recovery<'src, I>() -> GruelParser<'src, I, Item>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    // Skip at least one token to make progress, capturing the span
    any()
        .map_with(|_, extra| extra.span())
        // Then skip any more tokens that don't start an item
        .then(
            any()
                .and_is(item_start().not())
                .repeated()
                .collect::<Vec<_>>(),
        )
        .map(|(start_span, _): (SimpleSpan, Vec<TokenKind>)| {
            // Convert SimpleSpan to Span
            Item::Error(to_gruel_util(start_span))
        })
        .boxed()
}

/// Parser for top-level items with error recovery.
/// When an item fails to parse, we skip tokens until we find the start of
/// another item, emit an Error node, and continue parsing.
fn item_with_recovery<'src, I>() -> GruelParser<'src, I, Item>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    item_parser()
        .recover_with(via_parser(error_recovery()))
        .boxed()
}

/// Main parser that produces an AST
fn ast_parser<'src, I>() -> GruelParser<'src, I, Ast>
where
    I: ValueInput<'src, Token = TokenKind, Span = SimpleSpan>,
{
    item_with_recovery()
        .repeated()
        .collect::<Vec<_>>()
        .then_ignore(end())
        .map(|items| Ast {
            module_doc: None,
            items,
        })
        .boxed()
}

/// Format a RichPattern for display in error messages.
fn format_pattern(pattern: &chumsky::error::RichPattern<'_, TokenKind>) -> String {
    use chumsky::error::RichPattern;
    match pattern {
        RichPattern::Token(tok) => tok.name().to_string(),
        RichPattern::Label(label) => label.to_string(),
        RichPattern::Identifier(ident) => format!("'{}'", ident),
        RichPattern::Any => "any token".to_string(),
        RichPattern::SomethingElse => "something else".to_string(),
        RichPattern::EndOfInput => "end of input".to_string(),
    }
}

/// Convert chumsky Rich error to CompileError, preserving rich context.
fn convert_error(err: Rich<'_, TokenKind>) -> CompileError {
    let span = to_gruel_util(*err.span());

    // Build the base error from the reason
    let mut error = match err.reason() {
        chumsky::error::RichReason::ExpectedFound { expected, found } => {
            let expected_str: Cow<'static, str> = if expected.is_empty() {
                Cow::Borrowed("something")
            } else {
                Cow::Owned(
                    expected
                        .iter()
                        .take(3) // Limit to first 3 for readability
                        .map(format_pattern)
                        .collect::<Vec<_>>()
                        .join(" or "),
                )
            };

            let found_str: Cow<'static, str> = match found.as_ref() {
                Some(t) => Cow::Owned(t.name().to_string()),
                None => Cow::Borrowed("end of file"),
            };

            CompileError::new(
                ErrorKind::UnexpectedToken {
                    expected: expected_str,
                    found: found_str,
                },
                span,
            )
        }
        chumsky::error::RichReason::Custom(msg) => {
            // Preserve the custom error message directly
            CompileError::new(ErrorKind::ParseError(msg.clone()), span)
        }
    };

    // Add labelled contexts as secondary labels
    for (pattern, ctx_span) in err.contexts() {
        let label_msg = format!("while parsing {}", format_pattern(pattern));
        let label_span = to_gruel_util(*ctx_span);
        error = error.with_label(label_msg, label_span);
    }

    error
}

/// Chumsky-based parser that converts tokens into an AST.
pub struct ChumskyParser {
    tokens: Vec<(TokenKind, SimpleSpan)>,
    /// ADR-0089: the original token stream (including `LineDoc`s) used to
    /// derive doc blocks when the `docs` preview feature is enabled.
    raw_tokens: Vec<gruel_lexer::Token>,
    source_len: usize,
    interner: ThreadedRodeo,
    /// File ID for spans in this file.
    file_id: FileId,
    /// Preview features enabled for this parse (ADR-0005, ADR-0049).
    ///
    /// The parser always accepts the full grammar (including preview syntax); a
    /// post-parse validation pass emits errors if preview-only syntax is used
    /// without the corresponding flag.
    preview_features: PreviewFeatures,
    /// ADR-0089: source text of the file being parsed. Required to compute
    /// line numbers for doc-block grouping when `docs` preview is enabled.
    source: Option<String>,
}

impl ChumskyParser {
    /// Create a new parser from tokens and an interner produced by the lexer.
    pub fn new(tokens: Vec<gruel_lexer::Token>, interner: ThreadedRodeo) -> Self {
        let source_len = tokens.last().map(|t| t.span.end as usize).unwrap_or(0);
        // Extract file_id from the first token (all tokens in a file have the same file_id)
        let file_id = tokens
            .first()
            .map(|t| t.span.file_id)
            .unwrap_or(FileId::DEFAULT);

        let raw_tokens = tokens.clone();
        let spanned_tokens: Vec<(TokenKind, SimpleSpan)> = tokens
            .into_iter()
            .filter(|t| t.kind != TokenKind::Eof) // Remove EOF, chumsky handles end differently
            // ADR-0089: drop `LineDoc` tokens before chumsky sees them.
            // The Phase 2 post-pass uses `raw_tokens` to recover them.
            .filter(|t| !matches!(t.kind, TokenKind::LineDoc(_)))
            .map(|t| {
                (
                    t.kind,
                    SimpleSpan::new(t.span.start as usize, t.span.end as usize),
                )
            })
            .collect();
        Self {
            tokens: spanned_tokens,
            raw_tokens,
            source_len,
            interner,
            file_id,
            preview_features: PreviewFeatures::default(),
            source: None,
        }
    }

    /// Set the preview features enabled for this parse. Required to use any
    /// syntax gated behind a `--preview` flag (ADR-0005).
    pub fn with_preview_features(mut self, features: PreviewFeatures) -> Self {
        self.preview_features = features;
        self
    }

    /// ADR-0089: attach the source text. Required to derive doc blocks
    /// when the `docs` preview feature is enabled. Without it, `LineDoc`
    /// tokens are silently dropped (same as the Phase 1 behavior).
    pub fn with_source(mut self, source: impl Into<String>) -> Self {
        self.source = Some(source.into());
        self
    }

    /// Parse the tokens into an AST, returning the AST and the interner.
    ///
    /// Returns all parse errors if parsing fails, not just the first one.
    pub fn parse(mut self) -> MultiErrorResult<(Ast, ThreadedRodeo)> {
        // Pre-intern primitive type symbols and create parser state with file ID
        let syms = PrimitiveTypeSpurs::new(&mut self.interner);
        let parser_state = ParserState::new(syms, self.file_id);
        let mut state = SimpleState(parser_state);

        // Create a stream from the token iterator
        let token_iter = self.tokens.iter().cloned();
        let stream = Stream::from_iter(token_iter);

        // Map the stream to split (Token, Span) tuples
        let eoi: SimpleSpan = (self.source_len..self.source_len).into();
        let mapped = stream.map(eoi, |(tok, span)| (tok, span));

        let mut ast = ast_parser()
            .parse_with_state(mapped, &mut state)
            .into_result()
            .map_err(|errs| {
                let errors: Vec<CompileError> = errs.into_iter().map(convert_error).collect();
                CompileErrors::from(errors)
            })?;

        // Post-parse AST validation: refutability in let-bindings
        // (unconditional per ADR-0049 §2). The nested-patterns preview
        // gate was removed at stabilization (Phase 8).
        let mut errors = Vec::new();
        let validator = AstValidator;
        validator.walk_ast(&ast, &mut errors);
        if !errors.is_empty() {
            return Err(CompileErrors::from(errors));
        }

        // ADR-0089 (stable): always attach docs when source is provided.
        // Call sites that pre-date this and don't pass `with_source()`
        // simply have no docs on their AST (same as the Phase 1 drop).
        if let Some(ref source) = self.source {
            let mut doc_errors = Vec::new();
            attach_docs(
                &mut ast,
                &self.raw_tokens,
                source,
                self.file_id,
                &self.interner,
                &mut doc_errors,
            );
            if !doc_errors.is_empty() {
                return Err(CompileErrors::from(doc_errors));
            }
        }

        Ok((ast, self.interner))
    }
}

/// ADR-0089: a contiguous run of `///` lines forming a single doc block.
#[derive(Debug, Clone)]
struct DocBlock {
    /// Joined body text (`\n`-separated, with `///` and one leading space
    /// stripped per line).
    body: String,
    /// Source span covering the block.
    span: Span,
    /// 1-based start line.
    start_line: usize,
    /// 1-based end line (inclusive).
    end_line: usize,
}

/// ADR-0089: group consecutive `LineDoc` tokens into doc blocks.
///
/// A doc block is a run of `///` lines on adjacent source lines (no blank
/// line, no non-doc token between). Two LineDoc tokens belong to the same
/// block iff their line numbers differ by exactly one.
fn collect_doc_blocks(
    raw_tokens: &[gruel_lexer::Token],
    line_index: &LineIndex,
    interner: &ThreadedRodeo,
) -> Vec<DocBlock> {
    let mut blocks: Vec<DocBlock> = Vec::new();
    let mut current_lines: Vec<&str> = Vec::new();
    let mut current_span: Option<Span> = None;
    let mut current_start_line: usize = 0;
    let mut current_end_line: usize = 0;
    let mut last_was_doc = false;

    for tok in raw_tokens {
        match tok.kind {
            TokenKind::LineDoc(spur) => {
                let line = line_index.span_line_number(tok.span);
                let body = interner.resolve(&spur);
                if last_was_doc && line == current_end_line + 1 {
                    current_lines.push(body);
                    current_end_line = line;
                    current_span = current_span.map(|s| Span::cover(s, tok.span));
                } else {
                    if let (Some(span), false) = (current_span, current_lines.is_empty()) {
                        blocks.push(DocBlock {
                            body: current_lines.join("\n"),
                            span,
                            start_line: current_start_line,
                            end_line: current_end_line,
                        });
                    }
                    current_lines = vec![body];
                    current_span = Some(tok.span);
                    current_start_line = line;
                    current_end_line = line;
                }
                last_was_doc = true;
            }
            TokenKind::Eof => {}
            _ => {
                if let (Some(span), false) = (current_span, current_lines.is_empty()) {
                    blocks.push(DocBlock {
                        body: current_lines.join("\n"),
                        span,
                        start_line: current_start_line,
                        end_line: current_end_line,
                    });
                    current_lines = Vec::new();
                    current_span = None;
                }
                last_was_doc = false;
            }
        }
    }
    if let (Some(span), false) = (current_span, current_lines.is_empty()) {
        blocks.push(DocBlock {
            body: current_lines.join("\n"),
            span,
            start_line: current_start_line,
            end_line: current_end_line,
        });
    }
    blocks
}

/// ADR-0089: apply the attachment rule and populate `Ast.module_doc` plus
/// each item's `doc` field. Emits parse errors for any doc block that
/// neither qualifies as the module candidate nor is glued to an item.
fn attach_docs(
    ast: &mut Ast,
    raw_tokens: &[gruel_lexer::Token],
    source: &str,
    file_id: FileId,
    interner: &ThreadedRodeo,
    errors: &mut Vec<CompileError>,
) {
    let line_index = LineIndex::new(source);
    let blocks = collect_doc_blocks(raw_tokens, &line_index, interner);
    if blocks.is_empty() {
        return;
    }

    // Compute, for each non-LineDoc token: its start line. The "first
    // non-doc token line" tells us whether a doc block has an item above
    // it (file-level rule).
    let first_non_doc_line: Option<usize> = raw_tokens
        .iter()
        .find(|t| !matches!(t.kind, TokenKind::LineDoc(_) | TokenKind::Eof))
        .map(|t| line_index.span_line_number(t.span));

    // Build a lookup: byte offset → 1-based line for every non-doc, non-EOF
    // token. Used to recognise when a doc block is glued to a follower.
    let mut token_line_by_start: HashMap<u32, usize> = HashMap::new();
    for tok in raw_tokens {
        if matches!(tok.kind, TokenKind::LineDoc(_) | TokenKind::Eof) {
            continue;
        }
        token_line_by_start.insert(tok.span.start, line_index.span_line_number(tok.span));
    }

    // Walk blocks in order. For each block, decide attachment.
    // - Module candidate: first block in file AND no non-doc token appears
    //   on a line strictly before the block's start_line.
    // - Glued: there exists a non-doc token whose start line == end_line + 1.
    let mut module_doc_assigned = false;
    // For glued blocks: map item start byte offset → Doc.
    let mut item_docs: HashMap<u32, Doc> = HashMap::new();

    for (idx, block) in blocks.iter().enumerate() {
        let is_first_block = idx == 0;
        let no_item_above = match first_non_doc_line {
            None => true,
            Some(line) => line >= block.start_line,
        };
        let qualifies_as_module = is_first_block && no_item_above;

        // Find the next non-doc token after this block (the immediately
        // following item-candidate).
        let next_non_doc = raw_tokens.iter().find(|t| {
            !matches!(t.kind, TokenKind::LineDoc(_) | TokenKind::Eof)
                && t.span.start > block.span.end
        });
        let glued = next_non_doc
            .map(|t| line_index.span_line_number(t.span) == block.end_line + 1)
            .unwrap_or(false);

        let doc = Doc {
            body: block.body.clone(),
            span: with_file(block.span, file_id),
        };

        if qualifies_as_module && !glued {
            // Module candidate with a blank-line separator → module doc.
            if !module_doc_assigned {
                ast.module_doc = Some(doc);
                module_doc_assigned = true;
            }
            continue;
        }

        if glued {
            // Attach to the immediately following item by its start position.
            // The post-walk over the AST will pick it up.
            let target = next_non_doc.expect("glued implies next token exists");
            item_docs.insert(target.span.start, doc);
            continue;
        }

        // Not glued, not module candidate → parse error.
        let span_in_file = with_file(block.span, file_id);
        errors.push(CompileError::new(
            ErrorKind::ParseError(
                "doc comment must be immediately followed by an item".to_string(),
            ),
            span_in_file,
        ));
    }

    // Distribute item_docs onto matching AST items.
    if !item_docs.is_empty() {
        distribute_docs_to_items(ast, &mut item_docs);
    }
}

/// Helper: set a `Span`'s file id when constructing a new span from one
/// that already carries the right id (no-op in practice).
fn with_file(span: Span, file_id: FileId) -> Span {
    Span::with_file(file_id, span.start, span.end)
}

/// ADR-0089: walk the AST and attach docs to items based on byte-offset
/// matching against `item_docs`. Visits every doc-bearing position:
/// top-level items plus nested method, field, and variant declarations.
fn distribute_docs_to_items(ast: &mut Ast, item_docs: &mut HashMap<u32, Doc>) {
    for item in &mut ast.items {
        match item {
            Item::Function(f) => {
                attach_if_match(&mut f.doc, item_docs, f.span.start);
            }
            Item::Struct(s) => {
                attach_if_match(&mut s.doc, item_docs, s.span.start);
                for field in &mut s.fields {
                    attach_if_match(&mut field.doc, item_docs, field.span.start);
                }
                for method in &mut s.methods {
                    attach_if_match(&mut method.doc, item_docs, method.span.start);
                }
            }
            Item::Enum(e) => {
                attach_if_match(&mut e.doc, item_docs, e.span.start);
                for variant in &mut e.variants {
                    attach_if_match(&mut variant.doc, item_docs, variant.span.start);
                    if let crate::ast::EnumVariantKind::Struct(fields) = &mut variant.kind {
                        for field in fields {
                            attach_if_match(&mut field.doc, item_docs, field.span.start);
                        }
                    }
                }
                for method in &mut e.methods {
                    attach_if_match(&mut method.doc, item_docs, method.span.start);
                }
            }
            Item::Interface(i) => {
                attach_if_match(&mut i.doc, item_docs, i.span.start);
                for sig in &mut i.methods {
                    attach_if_match(&mut sig.doc, item_docs, sig.span.start);
                }
            }
            Item::Derive(d) => {
                attach_if_match(&mut d.doc, item_docs, d.span.start);
                for method in &mut d.methods {
                    attach_if_match(&mut method.doc, item_docs, method.span.start);
                }
            }
            Item::Const(c) => {
                attach_if_match(&mut c.doc, item_docs, c.span.start);
            }
            Item::LinkExtern(b) => {
                attach_if_match(&mut b.doc, item_docs, b.span.start);
                for fn_decl in &mut b.items {
                    attach_if_match(&mut fn_decl.doc, item_docs, fn_decl.span.start);
                }
            }
            Item::Error(_) => {}
        }
    }
}

fn attach_if_match(slot: &mut Option<Doc>, item_docs: &mut HashMap<u32, Doc>, key: u32) {
    if let Some(doc) = item_docs.remove(&key) {
        *slot = Some(doc);
    }
}

/// Post-parse AST validator for patterns (ADR-0049): rejects refutable
/// patterns in `let` bindings. Formerly also gated nested syntax behind
/// the `nested_patterns` preview feature — that gate was removed when
/// ADR-0049 stabilized (Phase 8).
struct AstValidator;

impl AstValidator {
    fn walk_ast(&self, ast: &Ast, errors: &mut Vec<CompileError>) {
        for item in &ast.items {
            validate_item(item, errors, self);
        }
    }
}

/// Classify whether a pattern is refutable. Refutable = matches only some
/// values of its inferred type; irrefutable = matches every value.
fn is_refutable(pat: &Pattern) -> bool {
    match pat {
        Pattern::Wildcard(_) => false,
        Pattern::Ident { .. } => false,
        Pattern::Int(_) | Pattern::NegInt(_) | Pattern::Bool(_) => true,
        Pattern::Path(_) => true,
        // A variant pattern can't be irrefutable without type info (we'd need
        // to know whether it's a single-variant enum). Conservatively refutable.
        Pattern::DataVariant { .. } | Pattern::StructVariant { .. } => true,
        Pattern::Struct { fields, .. } => fields.iter().any(|f| {
            // `..` and shorthand bindings are irrefutable by themselves.
            f.sub.as_ref().is_some_and(is_refutable)
        }),
        Pattern::Tuple { elems, .. } => elems.iter().any(|e| match e {
            TupleElemPattern::Pattern(p) => is_refutable(p),
            TupleElemPattern::Rest(_) => false,
        }),
        // ADR-0079 Phase 3: an unroll-arm template's expanded pattern
        // is variant-shaped, hence refutable.
        Pattern::ComptimeUnrollArm { .. } => true,
    }
}

fn validate_item(item: &Item, errors: &mut Vec<CompileError>, v: &AstValidator) {
    match item {
        Item::Function(f) => validate_expr(&f.body, errors, v),
        Item::Struct(s) => {
            for m in &s.methods {
                validate_expr(&m.body, errors, v);
            }
        }
        Item::Enum(e) => {
            for m in &e.methods {
                validate_expr(&m.body, errors, v);
            }
        }
        Item::Const(c) => validate_expr(&c.init, errors, v),
        Item::Interface(_) => {}
        Item::Derive(d) => {
            for m in &d.methods {
                validate_expr(&m.body, errors, v);
            }
        }
        Item::LinkExtern(_) => {
            // Body-less extern declarations have no expressions to validate.
        }
        Item::Error(_) => {}
    }
}

fn validate_block(block: &crate::ast::BlockExpr, errors: &mut Vec<CompileError>, v: &AstValidator) {
    use crate::ast::AssignTarget;
    for stmt in &block.statements {
        match stmt {
            Statement::Let(l) => {
                validate_let_pattern(&l.pattern, errors, v);
                validate_expr(&l.init, errors, v);
            }
            Statement::Assign(a) => {
                validate_expr(&a.value, errors, v);
                match &a.target {
                    AssignTarget::Var(_) => {}
                    AssignTarget::Field(f) => validate_expr(&f.base, errors, v),
                    AssignTarget::Index(i) => {
                        validate_expr(&i.base, errors, v);
                        validate_expr(&i.index, errors, v);
                    }
                }
            }
            Statement::Expr(e) => validate_expr(e, errors, v),
        }
    }
    validate_expr(&block.expr, errors, v);
}

fn validate_expr(expr: &Expr, errors: &mut Vec<CompileError>, v: &AstValidator) {
    use crate::ast::IntrinsicArg;
    match expr {
        Expr::Block(b) => validate_block(b, errors, v),
        Expr::Match(m) => {
            validate_expr(&m.scrutinee, errors, v);
            for arm in &m.arms {
                validate_match_pattern(&arm.pattern, errors, v);
                validate_expr(&arm.body, errors, v);
            }
        }
        Expr::If(i) => {
            validate_expr(&i.cond, errors, v);
            validate_block(&i.then_block, errors, v);
            if let Some(e) = &i.else_block {
                validate_block(e, errors, v);
            }
        }
        Expr::While(w) => {
            validate_expr(&w.cond, errors, v);
            validate_block(&w.body, errors, v);
        }
        Expr::For(f) => {
            validate_expr(&f.iterable, errors, v);
            validate_block(&f.body, errors, v);
        }
        Expr::Loop(l) => validate_block(&l.body, errors, v),
        Expr::Binary(b) => {
            validate_expr(&b.left, errors, v);
            validate_expr(&b.right, errors, v);
        }
        Expr::Unary(u) => validate_expr(&u.operand, errors, v),
        Expr::Call(c) => {
            for arg in &c.args {
                validate_expr(&arg.expr, errors, v);
            }
        }
        Expr::IntrinsicCall(i) => {
            for arg in &i.args {
                if let IntrinsicArg::Expr(e) = arg {
                    validate_expr(e, errors, v);
                }
            }
        }
        Expr::MethodCall(m) => {
            validate_expr(&m.receiver, errors, v);
            for arg in &m.args {
                validate_expr(&arg.expr, errors, v);
            }
        }
        Expr::AssocFnCall(a) => {
            for arg in &a.args {
                validate_expr(&arg.expr, errors, v);
            }
        }
        Expr::Field(f) => validate_expr(&f.base, errors, v),
        Expr::TupleIndex(t) => validate_expr(&t.base, errors, v),
        Expr::Index(i) => {
            validate_expr(&i.base, errors, v);
            validate_expr(&i.index, errors, v);
        }
        Expr::Return(r) => {
            if let Some(val) = &r.value {
                validate_expr(val, errors, v);
            }
        }
        Expr::Paren(p) => validate_expr(&p.inner, errors, v),
        Expr::StructLit(s) => {
            for f in &s.fields {
                validate_expr(&f.value, errors, v);
            }
        }
        Expr::EnumStructLit(s) => {
            for f in &s.fields {
                validate_expr(&f.value, errors, v);
            }
        }
        Expr::ArrayLit(a) => {
            for e in &a.elements {
                validate_expr(e, errors, v);
            }
        }
        Expr::Tuple(t) => {
            for e in &t.elems {
                validate_expr(e, errors, v);
            }
        }
        Expr::Comptime(c) => validate_expr(&c.expr, errors, v),
        Expr::AnonFn(a) => validate_block(&a.body, errors, v),
        Expr::Range(r) => {
            if let Some(lo) = &r.lo {
                validate_expr(lo, errors, v);
            }
            if let Some(hi) = &r.hi {
                validate_expr(hi, errors, v);
            }
        }
        Expr::ComptimeUnrollFor(_) | Expr::Checked(_) => {}
        Expr::TypeLit(_)
        | Expr::Int(_)
        | Expr::Float(_)
        | Expr::String(_)
        | Expr::Char(_)
        | Expr::Bool(_)
        | Expr::Unit(_)
        | Expr::Ident(_)
        | Expr::Path(_)
        | Expr::SelfExpr(_)
        | Expr::Break(_)
        | Expr::Continue(_)
        | Expr::Error(_) => {}
    }
}

/// Validate a pattern in a let-binding position.
///
/// 1. If the pattern is refutable, emit a `RefutablePatternInLet` error at the
///    refutable sub-pattern's span. This rule applies unconditionally — it's
///    a property of the let context, not a preview-gated feature.
/// 2. If the preview feature is off, emit preview-required errors for nested
///    sub-patterns and `..` rest shapes.
fn validate_let_pattern(pat: &Pattern, errors: &mut Vec<CompileError>, _v: &AstValidator) {
    if is_refutable(pat) {
        errors.push(CompileError::new(
            ErrorKind::RefutablePatternInLet,
            refutable_focus_span(pat),
        ));
    }
}

/// Validate a pattern in a match-arm position. Formerly preview-gated;
/// now a no-op since ADR-0049 is stabilized.
fn validate_match_pattern(_pat: &Pattern, _errors: &mut Vec<CompileError>, _v: &AstValidator) {}

/// Pick the most informative span for a refutability error: the innermost
/// refutable sub-pattern when we can find one, otherwise the pattern's own span.
fn refutable_focus_span(pat: &Pattern) -> Span {
    match pat {
        Pattern::Int(l) => l.span,
        Pattern::NegInt(l) => l.span,
        Pattern::Bool(l) => l.span,
        Pattern::Path(p) => p.span,
        Pattern::DataVariant { span, .. } | Pattern::StructVariant { span, .. } => *span,
        Pattern::Struct { fields, .. } => fields
            .iter()
            .filter_map(|f| f.sub.as_ref())
            .find(|sub| is_refutable(sub))
            .map(refutable_focus_span)
            .unwrap_or(pat.span()),
        Pattern::Tuple { elems, .. } => elems
            .iter()
            .filter_map(|e| match e {
                TupleElemPattern::Pattern(p) if is_refutable(p) => Some(p),
                _ => None,
            })
            .next()
            .map(refutable_focus_span)
            .unwrap_or(pat.span()),
        Pattern::Wildcard(_) | Pattern::Ident { .. } => pat.span(),
        Pattern::ComptimeUnrollArm { span, .. } => *span,
    }
}

// The former `check_let_pattern_preview`, `check_flat_field_pattern`,
// `check_flat_tuple_elem`, `check_match_pattern_preview`, and
// `preview_required_err` helpers were removed when ADR-0049 stabilized
// (Phase 8). Nested patterns are now always accepted by the parser;
// refutability in `let` remains enforced by `validate_let_pattern`.

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

    /// Result type for parsing that includes both the AST and interner.
    /// Provides convenient access to both the parsed AST and symbol resolution.
    #[derive(Debug)]
    struct ParseResult {
        ast: Ast,
        interner: ThreadedRodeo,
    }

    impl ParseResult {
        /// Get the string for a symbol.
        fn get(&self, sym: Spur) -> &str {
            self.interner.resolve(&sym)
        }
    }

    /// Result type for expression parsing that includes both the expr and interner.
    #[derive(Debug)]
    struct ExprResult {
        expr: Expr,
        interner: ThreadedRodeo,
    }

    impl ExprResult {
        /// Get the string for a symbol.
        fn get(&self, sym: Spur) -> &str {
            self.interner.resolve(&sym)
        }
    }

    fn parse(source: &str) -> MultiErrorResult<ParseResult> {
        let lexer = Lexer::new(source);
        let (tokens, interner) = lexer.tokenize().map_err(CompileErrors::from)?;
        let parser = ChumskyParser::new(tokens, interner);
        let (ast, interner) = parser.parse()?;
        Ok(ParseResult { ast, interner })
    }

    fn parse_expr(source: &str) -> MultiErrorResult<ExprResult> {
        let result = parse(&format!("fn main() -> i32 {{ {} }}", source))?;
        let interner = result.interner;
        let expr = match result.ast.items.into_iter().next().unwrap() {
            Item::Function(f) => match f.body {
                Expr::Block(block) => *block.expr,
                other => other,
            },
            Item::Struct(_) => panic!("parse_expr helper should only be used with functions"),
            Item::Enum(_) => panic!("parse_expr helper should only be used with functions"),
            Item::Interface(_) => panic!("parse_expr helper should only be used with functions"),
            Item::Derive(_) => panic!("parse_expr helper should only be used with functions"),
            Item::Const(_) => panic!("parse_expr helper should only be used with functions"),
            Item::LinkExtern(_) => {
                panic!("parse_expr helper should only be used with functions")
            }
            Item::Error(_) => panic!("parse_expr helper should only be used with functions"),
        };
        Ok(ExprResult { expr, interner })
    }

    #[test]
    fn test_chumsky_parse_main() {
        let result = parse("fn main() -> i32 { 42 }").unwrap();

        assert_eq!(result.ast.items.len(), 1);
        match &result.ast.items[0] {
            Item::Function(f) => {
                assert_eq!(result.get(f.name.name), "main");
                match f.return_type.as_ref().unwrap() {
                    TypeExpr::Named(ident) => assert_eq!(result.get(ident.name), "i32"),
                    _ => panic!("expected Named type"),
                }
                match &f.body {
                    Expr::Block(block) => match block.expr.as_ref() {
                        Expr::Int(lit) => assert_eq!(lit.value, 42),
                        _ => panic!("expected Int"),
                    },
                    _ => panic!("expected Block"),
                }
            }
            Item::Struct(_) => panic!("expected Function"),
            Item::Enum(_) => panic!("expected Function"),
            Item::Interface(_) => panic!("expected Function"),
            Item::Derive(_) => panic!("expected Function"),
            Item::Const(_) => panic!("expected Function"),
            Item::LinkExtern(_) => panic!("expected Function"),
            Item::Error(_) => panic!("expected Function"),
        }
    }

    #[test]
    fn test_chumsky_parse_addition() {
        let result = parse_expr("1 + 2").unwrap();
        match result.expr {
            Expr::Binary(bin) => {
                assert!(matches!(bin.op, BinaryOp::Add));
                match (*bin.left, *bin.right) {
                    (Expr::Int(l), Expr::Int(r)) => {
                        assert_eq!(l.value, 1);
                        assert_eq!(r.value, 2);
                    }
                    _ => panic!("expected Int operands"),
                }
            }
            _ => panic!("expected Binary"),
        }
    }

    #[test]
    fn test_chumsky_parse_precedence() {
        // 1 + 2 * 3 should parse as 1 + (2 * 3)
        let result = parse_expr("1 + 2 * 3").unwrap();
        match result.expr {
            Expr::Binary(bin) => {
                assert!(matches!(bin.op, BinaryOp::Add));
                match *bin.left {
                    Expr::Int(l) => assert_eq!(l.value, 1),
                    _ => panic!("expected Int"),
                }
                match *bin.right {
                    Expr::Binary(inner) => {
                        assert!(matches!(inner.op, BinaryOp::Mul));
                    }
                    _ => panic!("expected Binary"),
                }
            }
            _ => panic!("expected Binary"),
        }
    }

    #[test]
    fn test_chumsky_parse_let_binding() {
        let result = parse("fn main() -> i32 { let x = 42; x }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => {
                    assert_eq!(block.statements.len(), 1);
                    match &block.statements[0] {
                        Statement::Let(let_stmt) => {
                            assert!(!let_stmt.is_mut);
                            match &let_stmt.pattern {
                                Pattern::Ident { name, .. } => {
                                    assert_eq!(result.get(name.name), "x")
                                }
                                other => panic!("expected Ident, got {:?}", other),
                            }
                        }
                        _ => panic!("expected Let"),
                    }
                }
                _ => panic!("expected Block"),
            },
            Item::Struct(_) => panic!("expected Function"),
            Item::Enum(_) => panic!("expected Function"),
            Item::Interface(_) => panic!("expected Function"),
            Item::Derive(_) => panic!("expected Function"),
            Item::Const(_) => panic!("expected Function"),
            Item::LinkExtern(_) => panic!("expected Function"),
            Item::Error(_) => panic!("expected Function"),
        }
    }

    #[test]
    fn test_while_simple() {
        // Simplest while case
        let result = parse("fn main() -> i32 { while true { } 0 }").unwrap();
        assert_eq!(result.ast.items.len(), 1);
    }

    #[test]
    fn test_while_with_statement() {
        // While with assignment
        let result = parse("fn main() -> i32 { while true { x = 1; } 0 }").unwrap();
        assert_eq!(result.ast.items.len(), 1);
    }

    #[test]
    fn test_function_calls() {
        let result =
            parse("fn add(a: i32, b: i32) -> i32 { a + b } fn main() -> i32 { add(1, 2) }")
                .unwrap();
        assert_eq!(result.ast.items.len(), 2);
    }

    #[test]
    fn test_if_else() {
        let result = parse("fn main() -> i32 { if true { 1 } else { 0 } }").unwrap();
        assert_eq!(result.ast.items.len(), 1);
    }

    #[test]
    fn test_nested_control_flow() {
        let result =
            parse("fn main() -> i32 { let mut x = 0; while x < 10 { x = x + 1; } x }").unwrap();
        assert_eq!(result.ast.items.len(), 1);
    }

    // ==================== Struct Method Parsing Tests ====================

    #[test]
    fn test_struct_with_single_method() {
        let result = parse("struct Point { x: i32, fn get_x(self) -> i32 { self.x } }").unwrap();
        assert_eq!(result.ast.items.len(), 1);
        match &result.ast.items[0] {
            Item::Struct(struct_decl) => {
                assert_eq!(result.get(struct_decl.name.name), "Point");
                assert_eq!(struct_decl.methods.len(), 1);
                let method = &struct_decl.methods[0];
                assert_eq!(result.get(method.name.name), "get_x");
                assert!(method.receiver.is_some()); // has self
                assert!(method.params.is_empty()); // no additional params
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_struct_method_with_params() {
        let result =
            parse("struct Point { x: i32, fn add(self, n: i32) -> i32 { self.x + n } }").unwrap();
        assert_eq!(result.ast.items.len(), 1);
        match &result.ast.items[0] {
            Item::Struct(struct_decl) => {
                let method = &struct_decl.methods[0];
                assert_eq!(result.get(method.name.name), "add");
                assert!(method.receiver.is_some());
                assert_eq!(method.params.len(), 1);
                assert_eq!(result.get(method.params[0].name.name), "n");
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_struct_associated_function() {
        // Associated function (no self)
        let result = parse(
            "struct Point { x: i32, y: i32, fn new(x: i32, y: i32) -> Point { Point { x: x, y: y } } }",
        )
        .unwrap();
        assert_eq!(result.ast.items.len(), 1);
        match &result.ast.items[0] {
            Item::Struct(struct_decl) => {
                let method = &struct_decl.methods[0];
                assert_eq!(result.get(method.name.name), "new");
                assert!(method.receiver.is_none()); // no self
                assert_eq!(method.params.len(), 2);
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_struct_multiple_methods() {
        let result = parse(
            "struct Counter {
                 value: i32,
                 fn new() -> Counter { Counter { value: 0 } }
                 fn get(self) -> i32 { self.value }
                 fn increment(self) -> i32 { self.value + 1 }
             }",
        )
        .unwrap();
        assert_eq!(result.ast.items.len(), 1);
        match &result.ast.items[0] {
            Item::Struct(struct_decl) => {
                assert_eq!(struct_decl.methods.len(), 3);
                // First is associated function (no self)
                assert!(struct_decl.methods[0].receiver.is_none());
                assert_eq!(result.get(struct_decl.methods[0].name.name), "new");
                // Second is method (has self)
                assert!(struct_decl.methods[1].receiver.is_some());
                assert_eq!(result.get(struct_decl.methods[1].name.name), "get");
                // Third is method (has self)
                assert!(struct_decl.methods[2].receiver.is_some());
                assert_eq!(result.get(struct_decl.methods[2].name.name), "increment");
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_struct_method_with_directive() {
        let result = parse("struct Foo { @inline fn bar(self) -> i32 { 42 } }").unwrap();
        match &result.ast.items[0] {
            Item::Struct(struct_decl) => {
                let method = &struct_decl.methods[0];
                assert_eq!(method.directives.len(), 1);
                assert_eq!(result.get(method.directives[0].name.name), "inline");
            }
            _ => panic!("expected Struct"),
        }
    }

    // ==================== Field/Method Visibility (ADR-0073) ====================

    #[test]
    fn test_struct_field_visibility_default_private() {
        let result = parse("struct Point { x: i32, y: i32 }").unwrap();
        match &result.ast.items[0] {
            Item::Struct(s) => {
                assert_eq!(s.fields[0].visibility, Visibility::Private);
                assert_eq!(s.fields[1].visibility, Visibility::Private);
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_struct_field_visibility_pub() {
        let result = parse("struct Account { pub id: u64, balance: i64 }").unwrap();
        match &result.ast.items[0] {
            Item::Struct(s) => {
                assert_eq!(s.fields[0].visibility, Visibility::Public);
                assert_eq!(result.get(s.fields[0].name.name), "id");
                assert_eq!(s.fields[1].visibility, Visibility::Private);
                assert_eq!(result.get(s.fields[1].name.name), "balance");
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_method_visibility_default_private() {
        let result = parse("struct Foo { fn bar(self) -> i32 { 42 } }").unwrap();
        match &result.ast.items[0] {
            Item::Struct(s) => {
                assert_eq!(s.methods[0].visibility, Visibility::Private);
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_method_visibility_pub() {
        let result =
            parse("struct Foo { pub fn bar(self) -> i32 { 42 } fn helper(self) -> i32 { 1 } }")
                .unwrap();
        match &result.ast.items[0] {
            Item::Struct(s) => {
                assert_eq!(s.methods[0].visibility, Visibility::Public);
                assert_eq!(result.get(s.methods[0].name.name), "bar");
                assert_eq!(s.methods[1].visibility, Visibility::Private);
                assert_eq!(result.get(s.methods[1].name.name), "helper");
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_method_visibility_pub_with_directive() {
        // `pub` sits between the directive and `fn`.
        let result = parse("struct Foo { @inline pub fn bar(self) -> i32 { 42 } }").unwrap();
        match &result.ast.items[0] {
            Item::Struct(s) => {
                let m = &s.methods[0];
                assert_eq!(m.visibility, Visibility::Public);
                assert_eq!(m.directives.len(), 1);
                assert_eq!(result.get(m.directives[0].name.name), "inline");
            }
            _ => panic!("expected Struct"),
        }
    }

    #[test]
    fn test_enum_struct_variant_field_visibility() {
        let result = parse("enum Shape { Circle { pub r: i32, color: i32 } }").unwrap();
        match &result.ast.items[0] {
            Item::Enum(e) => {
                use crate::ast::EnumVariantKind;
                match &e.variants[0].kind {
                    EnumVariantKind::Struct(fields) => {
                        assert_eq!(fields[0].visibility, Visibility::Public);
                        assert_eq!(fields[1].visibility, Visibility::Private);
                    }
                    _ => panic!("expected struct variant"),
                }
            }
            _ => panic!("expected Enum"),
        }
    }

    // ==================== Enum Method Parsing Tests (ADR-0053) ====================

    #[test]
    fn test_enum_without_methods_still_parses() {
        let result = parse("enum Color { Red, Green, Blue }").unwrap();
        match &result.ast.items[0] {
            Item::Enum(enum_decl) => {
                assert_eq!(enum_decl.variants.len(), 3);
                assert!(enum_decl.methods.is_empty());
            }
            _ => panic!("expected Enum"),
        }
    }

    #[test]
    fn test_enum_with_single_method() {
        let result =
            parse("enum Opt { Some(i32), None, fn is_some(self) -> bool { true } }").unwrap();
        match &result.ast.items[0] {
            Item::Enum(enum_decl) => {
                assert_eq!(enum_decl.variants.len(), 2);
                assert_eq!(enum_decl.methods.len(), 1);
                let m = &enum_decl.methods[0];
                assert_eq!(result.get(m.name.name), "is_some");
                assert!(m.receiver.is_some());
            }
            _ => panic!("expected Enum"),
        }
    }

    #[test]
    fn test_enum_method_without_trailing_comma_on_variants() {
        // Methods are allowed after variants with or without a trailing comma.
        let result = parse("enum E { A, B fn count(self) -> i32 { 2 } }").unwrap();
        match &result.ast.items[0] {
            Item::Enum(enum_decl) => {
                assert_eq!(enum_decl.variants.len(), 2);
                assert_eq!(enum_decl.methods.len(), 1);
            }
            _ => panic!("expected Enum"),
        }
    }

    #[test]
    fn test_enum_associated_function() {
        let result = parse("enum Opt { Some(i32), None, fn zero() -> i32 { 0 } }").unwrap();
        match &result.ast.items[0] {
            Item::Enum(enum_decl) => {
                let m = &enum_decl.methods[0];
                assert_eq!(result.get(m.name.name), "zero");
                assert!(m.receiver.is_none()); // associated function
            }
            _ => panic!("expected Enum"),
        }
    }

    #[test]
    fn test_enum_multiple_methods() {
        let result = parse(
            "enum E {
                A,
                B,
                fn new() -> E { E::A }
                fn is_a(self) -> bool { true }
                fn is_b(self) -> bool { false }
             }",
        )
        .unwrap();
        match &result.ast.items[0] {
            Item::Enum(enum_decl) => {
                assert_eq!(enum_decl.methods.len(), 3);
                assert!(enum_decl.methods[0].receiver.is_none());
                assert!(enum_decl.methods[1].receiver.is_some());
                assert!(enum_decl.methods[2].receiver.is_some());
            }
            _ => panic!("expected Enum"),
        }
    }

    // ==================== Method Call Parsing Tests ====================

    #[test]
    fn test_method_call_simple() {
        let result = parse_expr("x.foo()").unwrap();
        match &result.expr {
            Expr::MethodCall(call) => {
                assert_eq!(result.get(call.method.name), "foo");
                assert!(call.args.is_empty());
                match call.receiver.as_ref() {
                    Expr::Ident(ident) => assert_eq!(result.get(ident.name), "x"),
                    _ => panic!("expected Ident receiver"),
                }
            }
            _ => panic!("expected MethodCall, got {:?}", result.expr),
        }
    }

    #[test]
    fn test_method_call_with_args() {
        let result = parse_expr("point.add(5, 10)").unwrap();
        match &result.expr {
            Expr::MethodCall(call) => {
                assert_eq!(result.get(call.method.name), "add");
                assert_eq!(call.args.len(), 2);
            }
            _ => panic!("expected MethodCall"),
        }
    }

    #[test]
    fn test_method_call_chained() {
        let result = parse_expr("x.foo().bar()").unwrap();
        match &result.expr {
            Expr::MethodCall(outer) => {
                assert_eq!(result.get(outer.method.name), "bar");
                match outer.receiver.as_ref() {
                    Expr::MethodCall(inner) => {
                        assert_eq!(result.get(inner.method.name), "foo");
                    }
                    _ => panic!("expected inner MethodCall"),
                }
            }
            _ => panic!("expected outer MethodCall"),
        }
    }

    #[test]
    fn test_method_call_on_field_access() {
        let result = parse_expr("obj.field.method()").unwrap();
        match &result.expr {
            Expr::MethodCall(call) => {
                assert_eq!(result.get(call.method.name), "method");
                match call.receiver.as_ref() {
                    Expr::Field(field) => {
                        assert_eq!(result.get(field.field.name), "field");
                    }
                    _ => panic!("expected Field receiver"),
                }
            }
            _ => panic!("expected MethodCall"),
        }
    }

    #[test]
    fn test_field_access_not_method_call() {
        // .field (not followed by parens) should parse as FieldExpr, not MethodCall
        let result = parse_expr("x.field").unwrap();
        match &result.expr {
            Expr::Field(field) => {
                assert_eq!(result.get(field.field.name), "field");
            }
            _ => panic!("expected Field, got {:?}", result.expr),
        }
    }

    #[test]
    fn test_method_call_on_struct_literal() {
        let result =
            parse("struct Point { x: i32 } fn main() -> i32 { Point { x: 1 }.get() }").unwrap();
        match &result.ast.items[1] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match block.expr.as_ref() {
                    Expr::MethodCall(call) => {
                        assert_eq!(result.get(call.method.name), "get");
                        match call.receiver.as_ref() {
                            Expr::StructLit(lit) => {
                                assert_eq!(result.get(lit.name.name), "Point")
                            }
                            _ => panic!("expected StructLit receiver"),
                        }
                    }
                    _ => panic!("expected MethodCall"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_method_call_on_paren_expr() {
        let result = parse_expr("(x).method()").unwrap();
        match &result.expr {
            Expr::MethodCall(call) => {
                assert_eq!(result.get(call.method.name), "method");
                match call.receiver.as_ref() {
                    Expr::Paren(_) => {}
                    _ => panic!("expected Paren receiver"),
                }
            }
            _ => panic!("expected MethodCall"),
        }
    }

    #[test]
    fn test_method_call_mixed_with_index() {
        // Complex chain: array[0].method().field
        let result = parse_expr("arr[0].get().value").unwrap();
        match &result.expr {
            Expr::Field(field) => {
                assert_eq!(result.get(field.field.name), "value");
                match field.base.as_ref() {
                    Expr::MethodCall(call) => {
                        assert_eq!(result.get(call.method.name), "get");
                        match call.receiver.as_ref() {
                            Expr::Index(_) => {}
                            _ => panic!("expected Index receiver"),
                        }
                    }
                    _ => panic!("expected MethodCall"),
                }
            }
            _ => panic!("expected Field"),
        }
    }

    #[test]
    fn test_associated_function_call() {
        // Type::function(args) syntax
        let result = parse_expr("Point::new(1, 2)").unwrap();
        match &result.expr {
            Expr::AssocFnCall(call) => {
                assert_eq!(result.get(call.type_name.name), "Point");
                assert_eq!(result.get(call.function.name), "new");
                assert_eq!(call.args.len(), 2);
            }
            _ => panic!("expected AssocFnCall, got {:?}", result.expr),
        }
    }

    // ==================== Block Expression Statement Tests ====================

    #[test]
    fn test_block_statement_followed_by_identifier() {
        // Block expression as a statement followed by an identifier expression
        // This is the regression test for gruel-wo1g
        let result = parse(
            "fn main() -> i32 {
                let a = 1;
                {
                    let b = 2;
                }
                a
            }",
        )
        .unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => {
                    // Should have 2 statements: let a = 1; and { let b = 2; }
                    assert_eq!(block.statements.len(), 2);
                    // First statement is a let
                    assert!(matches!(&block.statements[0], Statement::Let(_)));
                    // Second statement is an expression statement containing a block
                    match &block.statements[1] {
                        Statement::Expr(Expr::Block(_)) => {}
                        _ => panic!("expected Expr(Block), got {:?}", block.statements[1]),
                    }
                    // Final expression should be 'a' (simple identifier)
                    match block.expr.as_ref() {
                        Expr::Ident(ident) => assert_eq!(result.get(ident.name), "a"),
                        _ => panic!("expected Ident expression, got {:?}", block.expr),
                    }
                }
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    // ==================== Error Conversion Tests ====================

    #[test]
    fn test_error_preserves_span() {
        // Parse invalid syntax and verify error has span information
        let result = parse("fn main() -> i32 { let = 42; }");
        assert!(result.is_err());
        let errors = result.unwrap_err();
        // Get the first error and verify it has span information
        let error = errors.first().expect("should have at least one error");
        assert!(error.has_span());
        assert!(error.span().is_some());
    }

    #[test]
    fn test_error_expected_found() {
        // Missing expression after let
        let result = parse("fn main() -> i32 { let x = ; }");
        assert!(result.is_err());
        let errors = result.unwrap_err();
        let error = errors.first().expect("should have at least one error");
        // Error message should describe what was expected vs found
        let msg = error.to_string();
        assert!(
            msg.contains("expected") || msg.contains("found"),
            "error message: {}",
            msg
        );
    }

    #[test]
    fn test_error_unexpected_eof() {
        // Unterminated block
        let result = parse("fn main() -> i32 {");
        assert!(result.is_err());
        let errors = result.unwrap_err();
        let error = errors.first().expect("should have at least one error");
        let msg = error.to_string();
        // Should indicate end of file was reached unexpectedly
        assert!(
            msg.contains("end of file") || msg.contains("expected"),
            "error message: {}",
            msg
        );
    }

    #[test]
    fn test_format_pattern_token() {
        use chumsky::error::RichPattern;
        use chumsky::util::MaybeRef;

        let pattern = RichPattern::Token(MaybeRef::Val(TokenKind::Plus));
        let formatted = format_pattern(&pattern);
        // TokenKind::name() returns quoted form like "'+'"
        assert_eq!(formatted, "'+'");
    }

    #[test]
    fn test_format_pattern_label() {
        use chumsky::error::RichPattern;

        let pattern: RichPattern<'_, TokenKind> = RichPattern::Label(Cow::Borrowed("expression"));
        let formatted = format_pattern(&pattern);
        assert_eq!(formatted, "expression");
    }

    #[test]
    fn test_format_pattern_identifier() {
        use chumsky::error::RichPattern;

        let pattern: RichPattern<'_, TokenKind> = RichPattern::Identifier("while".to_string());
        let formatted = format_pattern(&pattern);
        assert_eq!(formatted, "'while'");
    }

    #[test]
    fn test_format_pattern_any() {
        use chumsky::error::RichPattern;

        let pattern: RichPattern<'_, TokenKind> = RichPattern::Any;
        let formatted = format_pattern(&pattern);
        assert_eq!(formatted, "any token");
    }

    #[test]
    fn test_format_pattern_end_of_input() {
        use chumsky::error::RichPattern;

        let pattern: RichPattern<'_, TokenKind> = RichPattern::EndOfInput;
        let formatted = format_pattern(&pattern);
        assert_eq!(formatted, "end of input");
    }

    #[test]
    fn test_parse_error_no_empty_found_clause() {
        // Test that error messages don't have empty "found" clauses
        // This was a bug when Custom errors were mapped to UnexpectedToken with empty found
        let result = parse("fn main() -> i32 { let x = ; }");
        assert!(result.is_err());
        let errors = result.unwrap_err();
        let error = errors.first().expect("should have at least one error");
        let msg = error.to_string();
        // Should not end with "found " (empty found)
        assert!(
            !msg.ends_with("found "),
            "error message should not have trailing empty 'found': {}",
            msg
        );
    }

    #[test]
    fn test_parse_error_variant_display() {
        // Directly test that ParseError displays correctly
        let error = CompileError::new(
            ErrorKind::ParseError("expected semicolon after expression".to_string()),
            gruel_util::Span::new(0, 10),
        );
        assert_eq!(error.to_string(), "expected semicolon after expression");
    }

    #[test]
    fn test_offset_to_u32_normal() {
        // Normal values should convert without issue
        assert_eq!(offset_to_u32(0), 0);
        assert_eq!(offset_to_u32(42), 42);
        assert_eq!(offset_to_u32(1000000), 1000000);
        assert_eq!(offset_to_u32(u32::MAX as usize), u32::MAX);
    }

    #[test]
    #[should_panic(expected = "offset 4294967296 exceeds u32::MAX")]
    #[cfg(debug_assertions)]
    fn test_offset_to_u32_overflow_panics_in_debug() {
        // Value just over u32::MAX should panic in debug builds
        let _ = offset_to_u32((u32::MAX as usize) + 1);
    }

    #[test]
    fn test_to_gruel_util_normal() {
        // Normal spans should convert without issue
        let simple = SimpleSpan::new(10, 20);
        let gruel = to_gruel_util(simple);
        assert_eq!(gruel.start, 10);
        assert_eq!(gruel.end, 20);
    }

    #[test]
    fn test_parse_returns_multiple_errors() {
        // Test that we return ALL parse errors, not just the first one.
        // This uses source with multiple syntax errors that can be detected at once.
        // Note: The actual number of errors depends on Chumsky's error recovery,
        // but this test ensures the infrastructure returns all errors it finds.
        let source = "fn main() { let }"; // Missing variable name and expression

        let result = parse(source);
        assert!(result.is_err(), "Expected parsing to fail");

        // We should get at least one error
        let errors = result.unwrap_err();
        assert!(
            !errors.is_empty(),
            "Expected at least one error but got none"
        );

        // Verify we can iterate over all errors
        let error_count = errors.len();
        assert!(
            error_count >= 1,
            "Expected at least 1 error, got {}",
            error_count
        );
    }

    #[test]
    fn test_parse_error_collection_preserves_all() {
        // Test that the error collection mechanism preserves all errors.
        // This directly tests the CompileErrors::from(Vec<CompileError>) path.
        let errors = vec![
            CompileError::without_span(ErrorKind::UnexpectedToken {
                expected: std::borrow::Cow::Borrowed("ident"),
                found: std::borrow::Cow::Borrowed("let"),
            }),
            CompileError::without_span(ErrorKind::UnexpectedToken {
                expected: std::borrow::Cow::Borrowed("expr"),
                found: std::borrow::Cow::Borrowed("rbrace"),
            }),
        ];

        let compile_errors = CompileErrors::from(errors);
        assert_eq!(compile_errors.len(), 2, "Expected 2 errors to be preserved");
    }

    // ==================== Qualified Struct Literal Tests ====================

    #[test]
    fn test_qualified_struct_literal() {
        // module.Point { x: 1, y: 2 } should parse as a qualified struct literal
        let result = parse_expr("mod.Point { x: 1, y: 2 }").unwrap();
        match &result.expr {
            Expr::StructLit(lit) => {
                // Verify it has a base (the module)
                assert!(
                    lit.base.is_some(),
                    "qualified struct literal should have a base"
                );
                match lit.base.as_ref().unwrap().as_ref() {
                    Expr::Ident(ident) => assert_eq!(result.get(ident.name), "mod"),
                    _ => panic!("base should be Ident, got {:?}", lit.base),
                }
                // Verify struct name
                assert_eq!(result.get(lit.name.name), "Point");
                // Verify fields
                assert_eq!(lit.fields.len(), 2);
                assert_eq!(result.get(lit.fields[0].name.name), "x");
                assert_eq!(result.get(lit.fields[1].name.name), "y");
            }
            _ => panic!("expected StructLit, got {:?}", result.expr),
        }
    }

    #[test]
    fn test_qualified_struct_literal_empty() {
        // module.Empty {} should parse as a qualified struct literal with no fields
        let result = parse_expr("mod.Empty {}").unwrap();
        match &result.expr {
            Expr::StructLit(lit) => {
                assert!(
                    lit.base.is_some(),
                    "qualified struct literal should have a base"
                );
                assert_eq!(result.get(lit.name.name), "Empty");
                assert_eq!(lit.fields.len(), 0);
            }
            _ => panic!("expected StructLit, got {:?}", result.expr),
        }
    }

    #[test]
    fn test_field_access_then_block() {
        // obj.field; { 1 } should parse as field access (discarded) followed by block expression
        // Note: obj.field { 1 } (without semicolon) is a syntax error because there's no
        // operator between the field access and the block.
        let result = parse("fn main() -> i32 { x.field; { 1 } }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => {
                    // The block should have a statement (field access discarded) and
                    // a final expression (the inner block returning 1)
                    assert_eq!(block.statements.len(), 1);
                    match &block.statements[0] {
                        Statement::Expr(Expr::Field(field)) => {
                            assert_eq!(result.get(field.field.name), "field");
                        }
                        _ => panic!("expected Field statement, got {:?}", block.statements[0]),
                    }
                    match block.expr.as_ref() {
                        Expr::Block(inner) => match inner.expr.as_ref() {
                            Expr::Int(lit) => assert_eq!(lit.value, 1),
                            _ => panic!("expected Int, got {:?}", inner.expr),
                        },
                        _ => panic!("expected Block, got {:?}", block.expr),
                    }
                }
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_field_access_block_without_semicolon_is_error() {
        // obj.field { 1 } without semicolon is a syntax error - it's not a struct literal
        // (because { 1 } doesn't match the { ident: } pattern) and it's not valid syntax.
        let result = parse("fn main() -> i32 { x.field { 1 } }");
        assert!(
            result.is_err(),
            "field + block without semicolon should be syntax error"
        );
    }

    #[test]
    fn test_chained_qualified_struct_literal() {
        // a.b.Point { x: 1 } - nested field access then struct literal
        let result = parse_expr("a.b.Point { x: 1 }").unwrap();
        match &result.expr {
            Expr::StructLit(lit) => {
                // Should have a base that's a.b
                assert!(lit.base.is_some());
                match lit.base.as_ref().unwrap().as_ref() {
                    Expr::Field(field) => {
                        assert_eq!(result.get(field.field.name), "b");
                        match field.base.as_ref() {
                            Expr::Ident(ident) => assert_eq!(result.get(ident.name), "a"),
                            _ => panic!("inner base should be Ident"),
                        }
                    }
                    _ => panic!("base should be Field, got {:?}", lit.base),
                }
                assert_eq!(result.get(lit.name.name), "Point");
            }
            _ => panic!("expected StructLit, got {:?}", result.expr),
        }
    }

    // ==================== Anonymous Struct Method Parsing Tests ====================

    #[test]
    fn test_anon_struct_with_fields_only() {
        // Anonymous struct with only fields (no methods)
        let result = parse("fn make_type() -> type { struct { x: i32, y: i32 } }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => {
                assert_eq!(result.get(f.name.name), "make_type");
                match &f.body {
                    Expr::Block(block) => match block.expr.as_ref() {
                        Expr::TypeLit(type_lit) => match &type_lit.type_expr {
                            TypeExpr::AnonymousStruct {
                                fields, methods, ..
                            } => {
                                assert_eq!(fields.len(), 2);
                                assert_eq!(result.get(fields[0].name.name), "x");
                                assert_eq!(result.get(fields[1].name.name), "y");
                                assert!(methods.is_empty());
                            }
                            _ => panic!("expected AnonymousStruct"),
                        },
                        _ => panic!("expected TypeLit"),
                    },
                    _ => panic!("expected Block"),
                }
            }
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_anon_struct_with_method() {
        // Anonymous struct with a single method
        let result =
            parse("fn make_type() -> type { struct { x: i32, fn get_x(self) -> i32 { self.x } } }")
                .unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match block.expr.as_ref() {
                    Expr::TypeLit(type_lit) => match &type_lit.type_expr {
                        TypeExpr::AnonymousStruct {
                            fields, methods, ..
                        } => {
                            assert_eq!(fields.len(), 1);
                            assert_eq!(result.get(fields[0].name.name), "x");
                            assert_eq!(methods.len(), 1);
                            assert_eq!(result.get(methods[0].name.name), "get_x");
                            assert!(
                                methods[0].receiver.is_some(),
                                "method should have self receiver"
                            );
                        }
                        _ => panic!("expected AnonymousStruct"),
                    },
                    _ => panic!("expected TypeLit"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_anon_struct_with_associated_function() {
        // Anonymous struct with an associated function (no self)
        let result = parse(
            "fn make_type() -> type { struct { x: i32, fn new() -> Self { Self { x: 0 } } } }",
        )
        .unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match block.expr.as_ref() {
                    Expr::TypeLit(type_lit) => match &type_lit.type_expr {
                        TypeExpr::AnonymousStruct {
                            fields, methods, ..
                        } => {
                            assert_eq!(fields.len(), 1);
                            assert_eq!(methods.len(), 1);
                            assert_eq!(result.get(methods[0].name.name), "new");
                            assert!(
                                methods[0].receiver.is_none(),
                                "associated function should not have self"
                            );
                            // Check return type is Self
                            match &methods[0].return_type {
                                Some(TypeExpr::Named(ident)) => {
                                    assert_eq!(result.get(ident.name), "Self");
                                }
                                _ => panic!("expected Self return type"),
                            }
                        }
                        _ => panic!("expected AnonymousStruct"),
                    },
                    _ => panic!("expected TypeLit"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_anon_struct_with_multiple_methods() {
        // Anonymous struct with multiple methods
        let result = parse(
            r#"
            fn make_type() -> type {
                struct {
                    value: i32,
                    fn get(self) -> i32 { self.value }
                    fn set(self, v: i32) -> Self { Self { value: v } }
                }
            }
        "#,
        )
        .unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match block.expr.as_ref() {
                    Expr::TypeLit(type_lit) => match &type_lit.type_expr {
                        TypeExpr::AnonymousStruct {
                            fields, methods, ..
                        } => {
                            assert_eq!(fields.len(), 1);
                            assert_eq!(result.get(fields[0].name.name), "value");
                            assert_eq!(methods.len(), 2);
                            assert_eq!(result.get(methods[0].name.name), "get");
                            assert_eq!(result.get(methods[1].name.name), "set");
                            // Check set has a parameter
                            assert_eq!(methods[1].params.len(), 1);
                            assert_eq!(result.get(methods[1].params[0].name.name), "v");
                        }
                        _ => panic!("expected AnonymousStruct"),
                    },
                    _ => panic!("expected TypeLit"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_anon_struct_methods_only() {
        // Anonymous struct with only methods (no fields)
        let result =
            parse("fn make_type() -> type { struct { fn new() -> Self { Self { } } } }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match block.expr.as_ref() {
                    Expr::TypeLit(type_lit) => match &type_lit.type_expr {
                        TypeExpr::AnonymousStruct {
                            fields, methods, ..
                        } => {
                            assert!(fields.is_empty());
                            assert_eq!(methods.len(), 1);
                            assert_eq!(result.get(methods[0].name.name), "new");
                        }
                        _ => panic!("expected AnonymousStruct"),
                    },
                    _ => panic!("expected TypeLit"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_self_type_in_return() {
        // Test Self as return type
        let result =
            parse("fn make_type() -> type { struct { x: i32, fn clone(self) -> Self { self } } }")
                .unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match block.expr.as_ref() {
                    Expr::TypeLit(type_lit) => match &type_lit.type_expr {
                        TypeExpr::AnonymousStruct { methods, .. } => {
                            match &methods[0].return_type {
                                Some(TypeExpr::Named(ident)) => {
                                    assert_eq!(result.get(ident.name), "Self");
                                }
                                _ => panic!("expected Self return type"),
                            }
                        }
                        _ => panic!("expected AnonymousStruct"),
                    },
                    _ => panic!("expected TypeLit"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_self_type_in_param() {
        // Test Self as parameter type
        let result = parse(
            "fn make_type() -> type { struct { fn combine(self, other: Self) -> Self { self } } }",
        )
        .unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match block.expr.as_ref() {
                    Expr::TypeLit(type_lit) => match &type_lit.type_expr {
                        TypeExpr::AnonymousStruct { methods, .. } => {
                            // Check parameter type is Self
                            let param = &methods[0].params[0];
                            match &param.ty {
                                TypeExpr::Named(ident) => {
                                    assert_eq!(result.get(ident.name), "Self");
                                }
                                _ => panic!("expected Self param type"),
                            }
                        }
                        _ => panic!("expected AnonymousStruct"),
                    },
                    _ => panic!("expected TypeLit"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_self_type_standalone() {
        // Test Self as a standalone type (e.g., in struct method context)
        // This just tests lexing/parsing of Self as a type keyword
        let result = parse("struct Foo { x: i32, fn clone(self) -> Self { self } }").unwrap();
        match &result.ast.items[0] {
            Item::Struct(struct_decl) => {
                let method = &struct_decl.methods[0];
                match &method.return_type {
                    Some(TypeExpr::Named(ident)) => {
                        assert_eq!(result.get(ident.name), "Self");
                    }
                    _ => panic!("expected Self return type"),
                }
            }
            _ => panic!("expected Struct"),
        }
    }

    // ========================================================================
    // Tuple parser tests (ADR-0048, phase 1)
    // ========================================================================

    #[test]
    fn test_tuple_expr_pair() {
        let result = parse_expr("(1, 2)").unwrap();
        match &result.expr {
            Expr::Tuple(t) => {
                assert_eq!(t.elems.len(), 2);
                match &t.elems[0] {
                    Expr::Int(lit) => assert_eq!(lit.value, 1),
                    _ => panic!("expected Int"),
                }
                match &t.elems[1] {
                    Expr::Int(lit) => assert_eq!(lit.value, 2),
                    _ => panic!("expected Int"),
                }
            }
            other => panic!("expected Tuple, got {:?}", other),
        }
    }

    #[test]
    fn test_tuple_expr_triple_mixed() {
        let result = parse_expr("(1, true, 3)").unwrap();
        match &result.expr {
            Expr::Tuple(t) => {
                assert_eq!(t.elems.len(), 3);
                assert!(matches!(t.elems[0], Expr::Int(_)));
                assert!(matches!(t.elems[1], Expr::Bool(_)));
                assert!(matches!(t.elems[2], Expr::Int(_)));
            }
            _ => panic!("expected Tuple"),
        }
    }

    #[test]
    fn test_tuple_expr_singleton_needs_trailing_comma() {
        // (x,) is a 1-tuple
        let result = parse_expr("(42,)").unwrap();
        match &result.expr {
            Expr::Tuple(t) => {
                assert_eq!(t.elems.len(), 1);
                assert!(matches!(t.elems[0], Expr::Int(_)));
            }
            _ => panic!("expected Tuple singleton"),
        }
    }

    #[test]
    fn test_paren_expr_without_comma_is_not_tuple() {
        // (x) stays a parenthesised expression, not a 1-tuple
        let result = parse_expr("(42)").unwrap();
        assert!(matches!(result.expr, Expr::Paren(_)));
    }

    #[test]
    fn test_unit_literal_is_not_tuple() {
        let result = parse_expr("()").unwrap();
        assert!(matches!(result.expr, Expr::Unit(_)));
    }

    #[test]
    fn test_tuple_expr_trailing_comma_allowed() {
        let result = parse_expr("(1, 2,)").unwrap();
        match &result.expr {
            Expr::Tuple(t) => assert_eq!(t.elems.len(), 2),
            _ => panic!("expected Tuple"),
        }
    }

    #[test]
    fn test_tuple_index_zero() {
        let result = parse_expr("t.0").unwrap();
        match &result.expr {
            Expr::TupleIndex(ti) => {
                assert_eq!(ti.index, 0);
                assert!(matches!(*ti.base, Expr::Ident(_)));
            }
            _ => panic!("expected TupleIndex"),
        }
    }

    #[test]
    fn test_tuple_index_multi_digit() {
        let result = parse_expr("t.42").unwrap();
        match &result.expr {
            Expr::TupleIndex(ti) => assert_eq!(ti.index, 42),
            _ => panic!("expected TupleIndex"),
        }
    }

    #[test]
    fn test_parenthesised_nested_tuple_access() {
        // (t.0).1 works; t.0.1 doesn't because the lexer treats `0.1` as Float
        let result = parse_expr("(t.0).1").unwrap();
        match &result.expr {
            Expr::TupleIndex(outer) => {
                assert_eq!(outer.index, 1);
                match &*outer.base {
                    Expr::Paren(p) => match &*p.inner {
                        Expr::TupleIndex(inner) => assert_eq!(inner.index, 0),
                        _ => panic!("expected inner TupleIndex"),
                    },
                    _ => panic!("expected Paren wrapping inner access"),
                }
            }
            _ => panic!("expected outer TupleIndex"),
        }
    }

    #[test]
    fn test_tuple_type_pair() {
        let result = parse("fn f() -> (i32, bool) { (1, true) }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match f.return_type.as_ref().unwrap() {
                TypeExpr::Tuple { elems, .. } => {
                    assert_eq!(elems.len(), 2);
                }
                other => panic!("expected Tuple type, got {:?}", other),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_tuple_type_singleton() {
        let result = parse("fn f() -> (i32,) { (1,) }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match f.return_type.as_ref().unwrap() {
                TypeExpr::Tuple { elems, .. } => assert_eq!(elems.len(), 1),
                _ => panic!("expected Tuple type"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_unit_type_still_unit() {
        let result = parse("fn f() -> () { () }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match f.return_type.as_ref().unwrap() {
                TypeExpr::Unit(_) => {}
                other => panic!("expected Unit type, got {:?}", other),
            },
            _ => panic!("expected Function"),
        }
    }

    fn assert_tuple_ident(
        elem: &TupleElemPattern,
        result: &ParseResult,
        expected: &str,
        expected_mut: bool,
    ) {
        match elem {
            TupleElemPattern::Pattern(Pattern::Ident { name, is_mut, .. }) => {
                assert_eq!(result.get(name.name), expected);
                assert_eq!(*is_mut, expected_mut);
            }
            other => panic!("expected Pattern::Ident, got {:?}", other),
        }
    }

    #[test]
    fn test_tuple_destructure_basic() {
        let result = parse("fn main() -> i32 { let (a, b) = (1, 2); a }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match &block.statements[0] {
                    Statement::Let(let_stmt) => match &let_stmt.pattern {
                        Pattern::Tuple { elems, .. } => {
                            assert_eq!(elems.len(), 2);
                            assert_tuple_ident(&elems[0], &result, "a", false);
                            assert_tuple_ident(&elems[1], &result, "b", false);
                        }
                        _ => panic!("expected Tuple pattern"),
                    },
                    _ => panic!("expected Let"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_tuple_destructure_mut_and_wildcard() {
        let result = parse("fn main() -> i32 { let (mut a, _) = (1, 2); a }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match &block.statements[0] {
                    Statement::Let(let_stmt) => match &let_stmt.pattern {
                        Pattern::Tuple { elems, .. } => {
                            assert_eq!(elems.len(), 2);
                            assert_tuple_ident(&elems[0], &result, "a", true);
                            assert!(matches!(
                                &elems[1],
                                TupleElemPattern::Pattern(Pattern::Wildcard(_))
                            ));
                        }
                        _ => panic!("expected Tuple pattern"),
                    },
                    _ => panic!("expected Let"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_tuple_destructure_singleton() {
        let result = parse("fn main() -> i32 { let (x,) = (42,); x }").unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match &block.statements[0] {
                    Statement::Let(let_stmt) => match &let_stmt.pattern {
                        Pattern::Tuple { elems, .. } => {
                            assert_eq!(elems.len(), 1);
                        }
                        _ => panic!("expected Tuple pattern"),
                    },
                    _ => panic!("expected Let"),
                },
                _ => panic!("expected Block"),
            },
            _ => panic!("expected Function"),
        }
    }

    // ==================== ADR-0049: nested pattern shapes ====================
    //
    // These tests drive the parser on nested pattern shapes. Previously the
    // post-parse validator gated them behind the `nested_patterns` preview
    // feature; now the feature is stabilized so parsing just works.

    fn parse_with_nested(source: &str) -> MultiErrorResult<ParseResult> {
        let lexer = Lexer::new(source);
        let (tokens, interner) = lexer.tokenize().unwrap();
        let parser = ChumskyParser::new(tokens, interner);
        parser
            .parse()
            .map(|(ast, interner)| ParseResult { ast, interner })
    }

    fn find_first_let_pattern(result: &ParseResult) -> &Pattern {
        match &result.ast.items[0] {
            Item::Function(f) => match &f.body {
                Expr::Block(block) => match &block.statements[0] {
                    Statement::Let(l) => &l.pattern,
                    _ => panic!("expected let"),
                },
                _ => panic!("expected block"),
            },
            _ => panic!("expected function"),
        }
    }

    fn find_first_match_arm_pattern(result: &ParseResult) -> &Pattern {
        match &result.ast.items[0] {
            Item::Function(f) => {
                fn find_match(e: &Expr) -> Option<&Pattern> {
                    match e {
                        Expr::Block(b) => find_match(&b.expr),
                        Expr::Match(m) => Some(&m.arms[0].pattern),
                        _ => None,
                    }
                }
                find_match(&f.body).expect("expected a match expression")
            }
            _ => panic!("expected function"),
        }
    }

    #[test]
    fn test_nested_let_struct_in_struct() {
        let source = r#"
            fn main() -> i32 {
                let Outer { inner: Inner { x, y }, tag } = make();
                0
            }
        "#;
        let result = parse_with_nested(source).unwrap();
        match find_first_let_pattern(&result) {
            Pattern::Struct { fields, .. } => {
                assert_eq!(fields.len(), 2);
                // inner: Inner { x, y }
                let inner = &fields[0];
                assert_eq!(result.get(inner.field_name.unwrap().name), "inner");
                match inner.sub.as_ref().unwrap() {
                    Pattern::Struct {
                        fields: inner_fields,
                        ..
                    } => assert_eq!(inner_fields.len(), 2),
                    other => panic!("expected nested Struct, got {:?}", other),
                }
                // tag (shorthand)
                let tag = &fields[1];
                assert_eq!(result.get(tag.field_name.unwrap().name), "tag");
                assert!(tag.sub.is_none());
            }
            other => panic!("expected Pattern::Struct, got {:?}", other),
        }
    }

    #[test]
    fn test_nested_let_tuple_of_tuples() {
        let source = "fn main() -> i32 { let ((a, b), c) = ((1, 2), 3); 0 }";
        let result = parse_with_nested(source).unwrap();
        match find_first_let_pattern(&result) {
            Pattern::Tuple { elems, .. } => {
                assert_eq!(elems.len(), 2);
                match &elems[0] {
                    TupleElemPattern::Pattern(Pattern::Tuple {
                        elems: inner_elems, ..
                    }) => assert_eq!(inner_elems.len(), 2),
                    other => panic!("expected nested tuple, got {:?}", other),
                }
            }
            other => panic!("expected Pattern::Tuple, got {:?}", other),
        }
    }

    #[test]
    fn test_tuple_pattern_in_match() {
        let source = r#"
            fn main() -> i32 {
                match pair() {
                    (0, 0) => 0,
                    _ => 1,
                }
            }
        "#;
        let result = parse_with_nested(source).unwrap();
        match find_first_match_arm_pattern(&result) {
            Pattern::Tuple { elems, .. } => {
                assert_eq!(elems.len(), 2);
                for e in elems {
                    match e {
                        TupleElemPattern::Pattern(Pattern::Int(lit)) => {
                            assert_eq!(lit.value, 0)
                        }
                        other => panic!("expected Int sub-pattern, got {:?}", other),
                    }
                }
            }
            other => panic!("expected Pattern::Tuple in match, got {:?}", other),
        }
    }

    #[test]
    fn test_rest_in_tuple() {
        let source = "fn main() -> i32 { let (a, .., z) = quintuple(); 0 }";
        let result = parse_with_nested(source).unwrap();
        match find_first_let_pattern(&result) {
            Pattern::Tuple { elems, .. } => {
                assert_eq!(elems.len(), 3);
                assert!(matches!(&elems[1], TupleElemPattern::Rest(_)));
            }
            other => panic!("expected Pattern::Tuple, got {:?}", other),
        }
    }

    #[test]
    fn test_rest_in_struct() {
        let source = "fn main() -> i32 { let Point { x, .. } = p(); 0 }";
        let result = parse_with_nested(source).unwrap();
        match find_first_let_pattern(&result) {
            Pattern::Struct { fields, .. } => {
                assert_eq!(fields.len(), 2);
                assert!(fields[0].field_name.is_some());
                assert!(fields[1].field_name.is_none()); // `..` sentinel
            }
            other => panic!("expected Pattern::Struct, got {:?}", other),
        }
    }

    // Post-stabilization note (ADR-0049 Phase 8): the former
    // `test_preview_gate_rejects_*` tests checked that the nested-pattern
    // syntax was rejected without the preview flag. Nested patterns now
    // parse unconditionally, so those tests were removed. Coverage of the
    // parsed AST shapes lives in the `parse_with_nested` tests above.
    #[test]
    fn test_flat_tuple_destructure_still_parses() {
        // Flat pre-existing forms must continue to parse.
        let source = "fn main() -> i32 { let (a, b) = pair(); 0 }";
        let result = parse(source);
        assert!(
            result.is_ok(),
            "flat tuple destructure should parse unconditionally"
        );
    }

    // ==================== ADR-0049 Phase 3: refutability ====================

    fn assert_refutable_in_let_err(result: &MultiErrorResult<ParseResult>) {
        use gruel_util::ErrorKind;
        let errors = result.as_ref().expect_err("expected errors");
        let found = errors
            .iter()
            .any(|e| matches!(e.kind, ErrorKind::RefutablePatternInLet));
        assert!(
            found,
            "expected RefutablePatternInLet in: {:?}",
            errors
                .iter()
                .map(|e| e.kind.to_string())
                .collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_refutable_int_literal_in_let() {
        // `let 1 = x;` is refutable — literals match only one value.
        let source = "fn main() -> i32 { let 1 = 1; 0 }";
        assert_refutable_in_let_err(&parse(source));
    }

    #[test]
    fn test_refutable_bool_in_let() {
        let source = "fn main() -> i32 { let true = true; 0 }";
        assert_refutable_in_let_err(&parse(source));
    }

    #[test]
    fn test_refutable_enum_path_in_let() {
        let source = "fn main() -> i32 { let Color::Red = c; 0 }";
        assert_refutable_in_let_err(&parse(source));
    }

    #[test]
    fn test_refutable_variant_in_let() {
        // `let Option::Some(x) = opt;` — refutable, even though the data-variant
        // pattern syntactically parses (stable after ADR-0049 Phase 8).
        let source = "fn main() -> i32 { let Option::Some(x) = opt(); 0 }";
        let result = parse_with_nested(source);
        assert_refutable_in_let_err(&result);
    }

    #[test]
    fn test_refutable_nested_literal_in_let() {
        // `let (1, y) = t;` — the inner `1` makes the overall pattern refutable.
        let source = "fn main() -> i32 { let (1, y) = t(); 0 }";
        let result = parse_with_nested(source);
        assert_refutable_in_let_err(&result);
    }

    #[test]
    fn test_irrefutable_tuple_in_let() {
        // All-irrefutable tuple is fine.
        let source = "fn main() -> i32 { let (a, b) = t(); 0 }";
        assert!(parse(source).is_ok());
    }

    #[test]
    fn test_irrefutable_nested_struct_in_let() {
        let source = "fn main() -> i32 { let Outer { inner: Inner { x, y }, tag } = make(); 0 }";
        assert!(parse_with_nested(source).is_ok());
    }

    // ========================================================================
    // ADR-0055: anonymous function expressions
    // ========================================================================

    #[test]
    fn test_anon_fn_single_param_with_return() {
        let result = parse_expr("fn(x: i32) -> i32 { x + 1 }").unwrap();
        match &result.expr {
            Expr::AnonFn(anon) => {
                assert_eq!(anon.params.len(), 1);
                assert_eq!(result.get(anon.params[0].name.name), "x");
                assert!(anon.return_type.is_some());
            }
            other => panic!("expected AnonFn, got {:?}", other),
        }
    }

    #[test]
    fn test_anon_fn_zero_param_no_return() {
        let result = parse_expr("fn() { 0 }").unwrap();
        match result.expr {
            Expr::AnonFn(anon) => {
                assert!(anon.params.is_empty());
                assert!(anon.return_type.is_none());
            }
            other => panic!("expected AnonFn, got {:?}", other),
        }
    }

    #[test]
    fn test_anon_fn_multi_param() {
        let result = parse_expr("fn(x: i32, y: i32) -> i32 { x + y }").unwrap();
        match &result.expr {
            Expr::AnonFn(anon) => {
                assert_eq!(anon.params.len(), 2);
                assert_eq!(result.get(anon.params[0].name.name), "x");
                assert_eq!(result.get(anon.params[1].name.name), "y");
            }
            other => panic!("expected AnonFn, got {:?}", other),
        }
    }

    #[test]
    fn test_anon_fn_in_call_arg() {
        // Anonymous function as a call argument, exercising the grammar inside
        // an argument list.
        let result = parse_expr("apply(fn(x: i32) -> i32 { x * 2 }, 3)").unwrap();
        match result.expr {
            Expr::Call(call) => {
                assert_eq!(call.args.len(), 2);
                assert!(matches!(call.args[0].expr, Expr::AnonFn(_)));
            }
            other => panic!("expected Call, got {:?}", other),
        }
    }

    #[test]
    fn test_anon_fn_nested() {
        // An anonymous function whose body returns another anonymous function.
        let result = parse_expr("fn() { fn(x: i32) -> i32 { x } }").unwrap();
        match result.expr {
            Expr::AnonFn(outer) => {
                assert!(matches!(*outer.body.expr, Expr::AnonFn(_)));
            }
            other => panic!("expected AnonFn, got {:?}", other),
        }
    }

    #[test]
    fn test_named_fn_at_top_level_still_works() {
        // Regression: adding `fn(` at expression position must not break the
        // `fn name(...)` item-level form.
        let result = parse("fn main() -> i32 { 0 }").unwrap();
        assert_eq!(result.ast.items.len(), 1);
        assert!(matches!(result.ast.items[0], Item::Function(_)));
    }

    // ============================================================
    // ADR-0089: doc-comment attachment tests
    // ============================================================

    fn parse_with_docs(source: &str) -> MultiErrorResult<ParseResult> {
        let lexer = Lexer::new(source);
        let (tokens, interner) = lexer.tokenize().map_err(CompileErrors::from)?;
        let parser = ChumskyParser::new(tokens, interner).with_source(source);
        let (ast, interner) = parser.parse()?;
        Ok(ParseResult { ast, interner })
    }

    #[test]
    fn test_docs_dropped_when_source_not_provided() {
        // Without `.with_source()`, the parser has no LineIndex and
        // therefore drops doc tokens at the boundary.
        let source = "/// Module docs.\nfn main() -> i32 { 0 }";
        let result = parse(source).unwrap();
        assert!(result.ast.module_doc.is_none());
        match &result.ast.items[0] {
            Item::Function(f) => assert!(f.doc.is_none()),
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_docs_on_attaches_glued_doc_to_function() {
        let source = "/// Docs for main.\nfn main() -> i32 { 0 }";
        let result = parse_with_docs(source).unwrap();
        assert!(result.ast.module_doc.is_none());
        match &result.ast.items[0] {
            Item::Function(f) => {
                let doc = f.doc.as_ref().expect("expected doc on main");
                assert_eq!(doc.body, "Docs for main.");
            }
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_module_doc_separated_from_first_item() {
        let source = "/// Module docs.\n\nfn main() -> i32 { 0 }";
        let result = parse_with_docs(source).unwrap();
        let module_doc = result
            .ast
            .module_doc
            .as_ref()
            .expect("expected a module doc");
        assert_eq!(module_doc.body, "Module docs.");
        match &result.ast.items[0] {
            Item::Function(f) => assert!(f.doc.is_none()),
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_module_doc_then_item_doc() {
        let source = "/// Module docs.\n\n/// Docs for main.\nfn main() -> i32 { 0 }";
        let result = parse_with_docs(source).unwrap();
        assert_eq!(result.ast.module_doc.as_ref().unwrap().body, "Module docs.");
        match &result.ast.items[0] {
            Item::Function(f) => {
                assert_eq!(f.doc.as_ref().unwrap().body, "Docs for main.");
            }
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_doc_block_joins_consecutive_lines() {
        let source = "/// Line 1\n/// Line 2\nfn main() -> i32 { 0 }";
        let result = parse_with_docs(source).unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => {
                assert_eq!(f.doc.as_ref().unwrap().body, "Line 1\nLine 2");
            }
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_doc_after_other_item_attaches_to_main() {
        // First item has no docs above it; second item has a glued doc.
        // First block can't be module candidate because helper is above main's docs.
        let source = "fn helper() {}\n\n/// Docs for main.\nfn main() -> i32 { 0 }";
        let result = parse_with_docs(source).unwrap();
        assert!(result.ast.module_doc.is_none());
        match &result.ast.items[1] {
            Item::Function(f) => {
                assert_eq!(f.doc.as_ref().unwrap().body, "Docs for main.");
            }
            _ => panic!("expected Function at index 1"),
        }
    }

    #[test]
    fn test_unglued_doc_after_first_item_is_error() {
        // Doc has an item above it (helper), and a blank line below before
        // the next item — disqualified as module candidate AND not glued.
        let source = "fn helper() {}\n\n/// Stray.\n\nfn main() -> i32 { 0 }";
        let result = parse_with_docs(source);
        assert!(result.is_err(), "expected parse error for orphan doc");
    }

    #[test]
    fn test_doc_strips_one_leading_space() {
        // Lexer strips one space; the body should not have the leading space.
        let source = "/// hello\nfn main() -> i32 { 0 }";
        let result = parse_with_docs(source).unwrap();
        match &result.ast.items[0] {
            Item::Function(f) => assert_eq!(f.doc.as_ref().unwrap().body, "hello"),
            _ => panic!("expected Function"),
        }
    }

    #[test]
    fn test_docs_on_struct_and_field() {
        let source = "\
/// Docs for Point.
struct Point {
    x: i32,
    y: i32,
}";
        let result = parse_with_docs(source).unwrap();
        match &result.ast.items[0] {
            Item::Struct(s) => {
                assert_eq!(s.doc.as_ref().unwrap().body, "Docs for Point.");
            }
            _ => panic!("expected Struct"),
        }
    }
}