allium_parser/

parser.rs

//! Recursive descent parser for Allium.
//!
//! Expressions use a Pratt parser (precedence climbing). Declarations and block
//! bodies use direct recursive descent. Multi-line clause values are detected
//! by comparing the line/column of the next token against the clause keyword.

use crate::ast::*;
use crate::diagnostic::Diagnostic;
use crate::lexer::{lex, SourceMap, Token, TokenKind};
use crate::Span;

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

#[derive(Debug)]
pub struct ParseResult {
    pub module: Module,
    pub diagnostics: Vec<Diagnostic>,
}

/// Parse an Allium source file into a [`Module`].
pub fn parse(source: &str) -> ParseResult {
    let tokens = lex(source);
    let source_map = SourceMap::new(source);
    let mut p = Parser {
        source,
        tokens,
        pos: 0,
        source_map,
        diagnostics: Vec::new(),
    };
    let module = p.parse_module();
    ParseResult {
        module,
        diagnostics: p.diagnostics,
    }
}

// ---------------------------------------------------------------------------
// Parser state
// ---------------------------------------------------------------------------

struct Parser<'s> {
    source: &'s str,
    tokens: Vec<Token>,
    pos: usize,
    source_map: SourceMap,
    diagnostics: Vec<Diagnostic>,
}

// ---------------------------------------------------------------------------
// Navigation helpers
// ---------------------------------------------------------------------------

impl<'s> Parser<'s> {
    fn peek(&self) -> Token {
        self.tokens[self.pos]
    }

    fn peek_kind(&self) -> TokenKind {
        self.tokens[self.pos].kind
    }

    fn peek_at(&self, offset: usize) -> Token {
        let idx = (self.pos + offset).min(self.tokens.len() - 1);
        self.tokens[idx]
    }

    fn advance(&mut self) -> Token {
        let tok = self.tokens[self.pos];
        if tok.kind != TokenKind::Eof {
            self.pos += 1;
        }
        tok
    }

    fn at(&self, kind: TokenKind) -> bool {
        self.peek_kind() == kind
    }

    fn at_eof(&self) -> bool {
        self.at(TokenKind::Eof)
    }

    fn eat(&mut self, kind: TokenKind) -> Option<Token> {
        if self.at(kind) {
            Some(self.advance())
        } else {
            None
        }
    }

    fn expect(&mut self, kind: TokenKind) -> Option<Token> {
        if self.at(kind) {
            Some(self.advance())
        } else {
            self.error(
                self.peek().span,
                format!("expected {kind}, found {}", self.peek_kind()),
            );
            None
        }
    }

    fn text(&self, span: Span) -> &'s str {
        &self.source[span.start..span.end]
    }

    fn line_of(&self, span: Span) -> u32 {
        self.source_map.line_col(span.start).0
    }

    fn col_of(&self, span: Span) -> u32 {
        self.source_map.line_col(span.start).1
    }

    fn error(&mut self, span: Span, msg: impl Into<String>) {
        self.diagnostics.push(Diagnostic::error(span, msg));
    }

    /// Consume and return an [`Ident`] from any word token.
    fn parse_ident(&mut self) -> Option<Ident> {
        self.parse_ident_in("identifier")
    }

    /// Consume and return an [`Ident`] with a context-specific label for errors.
    fn parse_ident_in(&mut self, context: &str) -> Option<Ident> {
        let tok = self.peek();
        if tok.kind.is_word() {
            self.advance();
            Some(Ident {
                span: tok.span,
                name: self.text(tok.span).to_string(),
            })
        } else {
            self.error(
                tok.span,
                format!("expected {context}, found {}", tok.kind),
            );
            None
        }
    }

    /// Consume a string token and produce a [`StringLiteral`].
    fn parse_string(&mut self) -> Option<StringLiteral> {
        let tok = self.expect(TokenKind::String)?;
        let raw = self.text(tok.span);
        // Strip surrounding quotes
        let inner = &raw[1..raw.len() - 1];
        let parts = parse_string_parts(inner, tok.span.start + 1);
        Some(StringLiteral {
            span: tok.span,
            parts,
        })
    }
}

/// Split the inner content of a string literal into text and interpolation
/// parts. `base_offset` is the byte offset of the first character after the
/// opening quote in the source file.
fn parse_string_parts(inner: &str, base_offset: usize) -> Vec<StringPart> {
    let mut parts = Vec::new();
    let mut buf = String::new();
    let bytes = inner.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'\\' && i + 1 < bytes.len() {
            buf.push(bytes[i + 1] as char);
            i += 2;
        } else if bytes[i] == b'{' {
            if !buf.is_empty() {
                parts.push(StringPart::Text(std::mem::take(&mut buf)));
            }
            i += 1; // skip {
            let start = i;
            while i < bytes.len() && bytes[i] != b'}' {
                i += 1;
            }
            let name = std::str::from_utf8(&bytes[start..i]).unwrap_or("").to_string();
            let span_start = base_offset + start;
            let span_end = base_offset + i;
            parts.push(StringPart::Interpolation(Ident {
                span: Span::new(span_start, span_end),
                name,
            }));
            if i < bytes.len() {
                i += 1; // skip }
            }
        } else {
            buf.push(bytes[i] as char);
            i += 1;
        }
    }
    if !buf.is_empty() {
        parts.push(StringPart::Text(buf));
    }
    parts
}

// ---------------------------------------------------------------------------
// Clause-keyword recognition
// ---------------------------------------------------------------------------

/// Returns true for identifiers that act as clause keywords inside blocks.
/// These are parsed as `Clause` items rather than `Assignment` items.
fn is_clause_keyword(text: &str) -> bool {
    matches!(
        text,
        "when"
            | "requires"
            | "ensures"
            | "trigger"
            | "facing"
            | "context"
            | "exposes"
            | "provides"
            | "related"
            | "timeout"
            | "guarantee"
            | "guidance"
            | "identified_by"
            | "within"
            | "tags"
            | "invariant"
    )
}

/// True for clause keywords whose value can start with a `name: expr` binding.
fn clause_allows_binding(keyword: &str) -> bool {
    matches!(keyword, "when")
}

/// True for keywords that use `keyword name: value` syntax (no colon after the
/// keyword). These directly embed a binding.
fn is_binding_clause_keyword(text: &str) -> bool {
    matches!(text, "facing" | "context")
}

/// True if the current token is a keyword that begins a clause.
fn token_is_clause_keyword(kind: TokenKind) -> bool {
    matches!(
        kind,
        TokenKind::When | TokenKind::Requires | TokenKind::Ensures | TokenKind::Within
    )
}

// ---------------------------------------------------------------------------
// Module parsing
// ---------------------------------------------------------------------------

impl<'s> Parser<'s> {
    fn parse_module(&mut self) -> Module {
        let start = self.peek().span;
        // Version marker is a comment: `-- allium: N`. Detect it from the raw
        // source before the lexer strips it.
        let version = detect_version(self.source);

        let mut decls = Vec::new();
        while !self.at_eof() {
            if let Some(d) = self.parse_decl() {
                decls.push(d);
            } else {
                // Recovery: skip one token and try again
                self.advance();
            }
        }
        let end = self.peek().span;
        Module {
            span: start.merge(end),
            version,
            declarations: decls,
        }
    }
}

fn detect_version(source: &str) -> Option<u32> {
    for line in source.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }
        if let Some(rest) = trimmed.strip_prefix("--") {
            let rest = rest.trim();
            if let Some(ver) = rest.strip_prefix("allium:") {
                return ver.trim().parse().ok();
            }
        }
        break; // only check leading lines
    }
    None
}

// ---------------------------------------------------------------------------
// Declaration parsing
// ---------------------------------------------------------------------------

impl<'s> Parser<'s> {
    fn parse_decl(&mut self) -> Option<Decl> {
        match self.peek_kind() {
            TokenKind::Use => self.parse_use_decl().map(Decl::Use),
            TokenKind::Rule => self.parse_block(BlockKind::Rule).map(Decl::Block),
            TokenKind::Entity => self.parse_block(BlockKind::Entity).map(Decl::Block),
            TokenKind::External => {
                let start = self.advance().span;
                if self.at(TokenKind::Entity) {
                    self.parse_block_from(start, BlockKind::ExternalEntity)
                        .map(Decl::Block)
                } else {
                    self.error(self.peek().span, "expected 'entity' after 'external'");
                    None
                }
            }
            TokenKind::Value => self.parse_block(BlockKind::Value).map(Decl::Block),
            TokenKind::Enum => self.parse_block(BlockKind::Enum).map(Decl::Block),
            TokenKind::Given => self.parse_anonymous_block(BlockKind::Given).map(Decl::Block),
            TokenKind::Config => self.parse_anonymous_block(BlockKind::Config).map(Decl::Block),
            TokenKind::Surface => self.parse_block(BlockKind::Surface).map(Decl::Block),
            TokenKind::Actor => self.parse_block(BlockKind::Actor).map(Decl::Block),
            TokenKind::Default => self.parse_default_decl().map(Decl::Default),
            TokenKind::Variant => self.parse_variant_decl().map(Decl::Variant),
            TokenKind::Deferred => self.parse_deferred_decl().map(Decl::Deferred),
            TokenKind::Open => self.parse_open_question_decl().map(Decl::OpenQuestion),
            TokenKind::Module => self.parse_module_decl(),
            // Qualified config: `alias/config { ... }`
            TokenKind::Ident
                if self.peek_at(1).kind == TokenKind::Slash
                    && self.text(self.peek_at(2).span) == "config" =>
            {
                self.parse_qualified_config().map(Decl::Block)
            }
            _ => {
                self.error(
                    self.peek().span,
                    format!(
                        "expected declaration (entity, rule, enum, value, config, surface, actor, \
                         given, default, variant, deferred, use, open question), found {}",
                        self.peek_kind(),
                    ),
                );
                None
            }
        }
    }

    // -- module declaration -----------------------------------------------

    fn parse_module_decl(&mut self) -> Option<Decl> {
        let start = self.expect(TokenKind::Module)?.span;
        let name = self.parse_ident_in("module name")?;
        Some(Decl::ModuleDecl(ModuleDecl {
            span: start.merge(name.span),
            name,
        }))
    }

    // -- use declaration ------------------------------------------------

    fn parse_use_decl(&mut self) -> Option<UseDecl> {
        let start = self.expect(TokenKind::Use)?.span;
        let path = self.parse_string()?;
        let alias = if self.eat(TokenKind::As).is_some() {
            Some(self.parse_ident_in("import alias")?)
        } else {
            None
        };
        let end = alias
            .as_ref()
            .map(|a| a.span)
            .unwrap_or(path.span);
        Some(UseDecl {
            span: start.merge(end),
            path,
            alias,
        })
    }

    // -- named block: `keyword Name { ... }` ----------------------------

    fn parse_block(&mut self, kind: BlockKind) -> Option<BlockDecl> {
        let start = self.advance().span; // consume keyword
        self.parse_block_from(start, kind)
    }

    fn parse_block_from(&mut self, start: Span, kind: BlockKind) -> Option<BlockDecl> {
        // For ExternalEntity the keyword was already consumed by the caller;
        // here we consume Entity.
        if kind == BlockKind::ExternalEntity {
            self.expect(TokenKind::Entity)?;
        }
        let context = match kind {
            BlockKind::Entity | BlockKind::ExternalEntity => "entity name",
            BlockKind::Rule => "rule name",
            BlockKind::Surface => "surface name",
            BlockKind::Actor => "actor name",
            BlockKind::Value => "value type name",
            BlockKind::Enum => "enum name",
            _ => "block name",
        };
        let name = Some(self.parse_ident_in(context)?);
        self.expect(TokenKind::LBrace)?;
        let items = if kind == BlockKind::Enum {
            self.parse_enum_body()
        } else {
            self.parse_block_items()
        };
        let end = self.expect(TokenKind::RBrace)?.span;
        Some(BlockDecl {
            span: start.merge(end),
            kind,
            name,
            items,
        })
    }

    // -- anonymous block: `keyword { ... }` -----------------------------

    /// Parse enum body: pipe-separated variant names.
    /// `{ pending | shipped | delivered }`
    fn parse_enum_body(&mut self) -> Vec<BlockItem> {
        let mut items = Vec::new();
        while !self.at(TokenKind::RBrace) && !self.at_eof() {
            if self.eat(TokenKind::Pipe).is_some() {
                continue;
            }
            if let Some(ident) = self.parse_ident_in("enum variant") {
                items.push(BlockItem {
                    span: ident.span,
                    kind: BlockItemKind::EnumVariant { name: ident },
                });
            } else {
                self.advance(); // skip unrecognised token
            }
        }
        items
    }

    fn parse_anonymous_block(&mut self, kind: BlockKind) -> Option<BlockDecl> {
        let start = self.advance().span;
        self.expect(TokenKind::LBrace)?;
        let items = self.parse_block_items();
        let end = self.expect(TokenKind::RBrace)?.span;
        Some(BlockDecl {
            span: start.merge(end),
            kind,
            name: None,
            items,
        })
    }

    // -- qualified config: `alias/config { ... }` -----------------------

    fn parse_qualified_config(&mut self) -> Option<BlockDecl> {
        let alias = self.parse_ident_in("config qualifier")?;
        let start = alias.span;
        self.expect(TokenKind::Slash)?;
        self.advance(); // consume "config" ident
        self.expect(TokenKind::LBrace)?;
        let items = self.parse_block_items();
        let end = self.expect(TokenKind::RBrace)?.span;
        Some(BlockDecl {
            span: start.merge(end),
            kind: BlockKind::Config,
            name: Some(alias),
            items,
        })
    }

    // -- default declaration -------------------------------------------

    fn parse_default_decl(&mut self) -> Option<DefaultDecl> {
        let start = self.expect(TokenKind::Default)?.span;

        // `default [TypeName] instanceName = value`
        // The type name is optional. If the next two tokens are both words
        // and the second is followed by `=`, the first is the type.
        let (type_name, name) = if self.peek_kind().is_word()
            && self.peek_at(1).kind.is_word()
            && self.peek_at(2).kind == TokenKind::Eq
        {
            let t = self.parse_ident_in("type name")?;
            let n = self.parse_ident_in("default name")?;
            (Some(t), n)
        } else {
            (None, self.parse_ident_in("default name")?)
        };

        self.expect(TokenKind::Eq)?;
        let value = self.parse_expr(0)?;
        Some(DefaultDecl {
            span: start.merge(value.span()),
            type_name,
            name,
            value,
        })
    }

    // -- variant declaration -------------------------------------------

    fn parse_variant_decl(&mut self) -> Option<VariantDecl> {
        let start = self.expect(TokenKind::Variant)?.span;
        let name = self.parse_ident_in("variant name")?;
        self.expect(TokenKind::Colon)?;
        let base = self.parse_expr(0)?;

        let items = if self.eat(TokenKind::LBrace).is_some() {
            let items = self.parse_block_items();
            self.expect(TokenKind::RBrace)?;
            items
        } else {
            Vec::new()
        };

        let end = if let Some(last) = items.last() {
            last.span
        } else {
            base.span()
        };
        Some(VariantDecl {
            span: start.merge(end),
            name,
            base,
            items,
        })
    }

    // -- deferred declaration ------------------------------------------

    fn parse_deferred_decl(&mut self) -> Option<DeferredDecl> {
        let start = self.expect(TokenKind::Deferred)?.span;
        let path = self.parse_expr(0)?;
        Some(DeferredDecl {
            span: start.merge(path.span()),
            path,
        })
    }

    // -- open question --------------------------------------------------

    fn parse_open_question_decl(&mut self) -> Option<OpenQuestionDecl> {
        let start = self.expect(TokenKind::Open)?.span;
        self.expect(TokenKind::Question)?;
        let text = self.parse_string()?;
        Some(OpenQuestionDecl {
            span: start.merge(text.span),
            text,
        })
    }
}

// ---------------------------------------------------------------------------
// Block item parsing
// ---------------------------------------------------------------------------

impl<'s> Parser<'s> {
    fn parse_block_items(&mut self) -> Vec<BlockItem> {
        let mut items = Vec::new();
        while !self.at(TokenKind::RBrace) && !self.at_eof() {
            if let Some(item) = self.parse_block_item() {
                items.push(item);
            } else {
                // Recovery: skip one token
                self.advance();
            }
        }
        items
    }

    fn parse_block_item(&mut self) -> Option<BlockItem> {
        let start = self.peek().span;

        // `let name = value`
        if self.at(TokenKind::Let) {
            return self.parse_let_item(start);
        }

        // `for binding in collection [where filter]: ...` at block level
        if self.at(TokenKind::For) {
            return self.parse_for_block_item(start);
        }

        // `open question "text"` (inside a block)
        if self.at(TokenKind::Open) && self.peek_at(1).kind == TokenKind::Question {
            self.advance(); // open
            self.advance(); // question
            let text = self.parse_string()?;
            return Some(BlockItem {
                span: start.merge(text.span),
                kind: BlockItemKind::OpenQuestion { text },
            });
        }

        // Everything else: `name: value` or `keyword: value` or
        // `name(params): value`
        if self.peek_kind().is_word() {
            // `facing name: Type` / `context name: Type [where ...]` — binding
            // clause keywords that don't use `:` after the keyword itself.
            if is_binding_clause_keyword(self.text(self.peek().span))
                && self.peek_at(1).kind.is_word()
                && self.peek_at(2).kind == TokenKind::Colon
            {
                return self.parse_binding_clause_item(start);
            }

            // Check for `name(` — potential parameterised assignment
            if self.peek_at(1).kind == TokenKind::LParen {
                return self.parse_param_or_clause_item(start);
            }

            // Check for `name:` — assignment or clause
            if self.peek_at(1).kind == TokenKind::Colon {
                return self.parse_assign_or_clause_item(start);
            }
        }

        // For clauses whose keyword is a separate TokenKind (when, requires, etc.)
        if token_is_clause_keyword(self.peek_kind()) && self.peek_at(1).kind == TokenKind::Colon {
            return self.parse_assign_or_clause_item(start);
        }

        self.error(
            start,
            format!(
                "expected block item (name: value, let name = value, when:/requires:/ensures: clause, \
                 for ... in ...:, or open question), found {}",
                self.peek_kind(),
            ),
        );
        None
    }

    fn parse_let_item(&mut self, start: Span) -> Option<BlockItem> {
        self.advance(); // consume `let`
        let name = self.parse_ident_in("binding name")?;
        self.expect(TokenKind::Eq)?;
        let value = self.parse_clause_value(start)?;
        Some(BlockItem {
            span: start.merge(value.span()),
            kind: BlockItemKind::Let { name, value },
        })
    }

    /// Parse `facing name: Type` or `context name: Type [where ...]`.
    /// These keywords don't take `:` after the keyword — they embed a binding directly.
    fn parse_binding_clause_item(&mut self, start: Span) -> Option<BlockItem> {
        let keyword_tok = self.advance(); // consume facing/context
        let keyword = self.text(keyword_tok.span).to_string();
        let binding_name = self.parse_ident_in(&format!("{keyword} binding name"))?;
        self.advance(); // consume ':'
        let type_expr = self.parse_clause_value(start)?;
        let value_span = type_expr.span();
        let value = Expr::Binding {
            span: binding_name.span.merge(value_span),
            name: binding_name,
            value: Box::new(type_expr),
        };
        Some(BlockItem {
            span: start.merge(value_span),
            kind: BlockItemKind::Clause { keyword, value },
        })
    }

    /// Parse `for binding in collection [where filter]:` at block level.
    /// The body is a set of nested block items (let, requires, ensures, etc.).
    fn parse_for_block_item(&mut self, start: Span) -> Option<BlockItem> {
        self.advance(); // consume `for`
        let binding = self.parse_ident_in("loop variable")?;
        self.expect(TokenKind::In)?;

        let collection = self.parse_expr(BP_WITH_WHERE + 1)?;

        let filter = if self.eat(TokenKind::Where).is_some() {
            // Parse filter at min_bp 0 — colon terminates naturally since
            // it's not an expression operator.
            Some(self.parse_expr(0)?)
        } else {
            None
        };

        self.expect(TokenKind::Colon)?;

        // The body contains nested block items at higher indentation.
        let for_line = self.line_of(start);
        let next_line = self.line_of(self.peek().span);

        let items = if next_line > for_line {
            let base_col = self.col_of(self.peek().span);
            self.parse_indented_block_items(base_col)
        } else {
            // Single-line for: parse one block item
            let mut items = Vec::new();
            if let Some(item) = self.parse_block_item() {
                items.push(item);
            }
            items
        };

        let end = items
            .last()
            .map(|i| i.span)
            .unwrap_or(start);

        Some(BlockItem {
            span: start.merge(end),
            kind: BlockItemKind::ForBlock {
                binding,
                collection,
                filter,
                items,
            },
        })
    }

    /// Collect block items at column >= `base_col` (for indented for-block bodies).
    fn parse_indented_block_items(&mut self, base_col: u32) -> Vec<BlockItem> {
        let mut items = Vec::new();
        while !self.at_eof()
            && !self.at(TokenKind::RBrace)
            && self.col_of(self.peek().span) >= base_col
        {
            if let Some(item) = self.parse_block_item() {
                items.push(item);
            } else {
                self.advance();
                break;
            }
        }
        items
    }

    fn parse_assign_or_clause_item(&mut self, start: Span) -> Option<BlockItem> {
        let name_tok = self.advance(); // consume name/keyword
        let name_text = self.text(name_tok.span).to_string();
        self.advance(); // consume ':'

        let allows_binding = clause_allows_binding(&name_text);
        let value = self.parse_clause_value_maybe_binding(start, allows_binding)?;
        let value_span = value.span();

        let kind = if is_clause_keyword(&name_text) {
            BlockItemKind::Clause {
                keyword: name_text,
                value,
            }
        } else {
            BlockItemKind::Assignment {
                name: Ident {
                    span: name_tok.span,
                    name: name_text,
                },
                value,
            }
        };

        Some(BlockItem {
            span: start.merge(value_span),
            kind,
        })
    }

    fn parse_param_or_clause_item(&mut self, start: Span) -> Option<BlockItem> {
        // Could be `name(params): value` (param assignment) or
        // `name(args)` which is an expression that happens to start a clause
        // value. Peek far enough to see if `)` is followed by `:`.
        let saved_pos = self.pos;
        let _name_tok = self.advance();
        self.advance(); // (

        // Try to scan past balanced parens
        let mut depth = 1u32;
        while !self.at_eof() && depth > 0 {
            match self.peek_kind() {
                TokenKind::LParen => {
                    depth += 1;
                    self.advance();
                }
                TokenKind::RParen => {
                    depth -= 1;
                    self.advance();
                }
                _ => {
                    self.advance();
                }
            }
        }

        if self.at(TokenKind::Colon) {
            // It's a parameterised assignment: restore and parse properly
            self.pos = saved_pos;
            let name = self.parse_ident_in("derived value name")?;
            self.expect(TokenKind::LParen)?;
            let params = self.parse_ident_list()?;
            self.expect(TokenKind::RParen)?;
            self.expect(TokenKind::Colon)?;
            let value = self.parse_clause_value(start)?;
            Some(BlockItem {
                span: start.merge(value.span()),
                kind: BlockItemKind::ParamAssignment {
                    name,
                    params,
                    value,
                },
            })
        } else {
            // Not a param assignment — restore and fall through to assignment
            self.pos = saved_pos;
            // Check for regular `name: value`
            if self.peek_at(1).kind == TokenKind::Colon {
                // Nope, the (1) is LParen not Colon. Re-examine.
            }
            // Fall back: treat as `name: value` where value starts with a call
            self.parse_assign_or_clause_item(start)
        }
    }

    fn parse_ident_list(&mut self) -> Option<Vec<Ident>> {
        let mut params = Vec::new();
        if !self.at(TokenKind::RParen) {
            params.push(self.parse_ident_in("parameter name")?);
            while self.eat(TokenKind::Comma).is_some() {
                params.push(self.parse_ident_in("parameter name")?);
            }
        }
        Some(params)
    }

    /// Parse a clause value, optionally checking for a `name: expr` binding
    /// pattern at the start. Used for when, facing and context clauses where
    /// the first `ident:` is a binding rather than a nested assignment.
    fn parse_clause_value_maybe_binding(
        &mut self,
        clause_start: Span,
        allow_binding: bool,
    ) -> Option<Expr> {
        if allow_binding
            && self.peek_kind().is_word()
            && self.peek_at(1).kind == TokenKind::Colon
        {
            // Check this isn't at the start of a new block item on the next line.
            // Bindings only apply on the same line or the immediate indented value.
            let clause_line = self.line_of(clause_start);
            let next_line = self.line_of(self.peek().span);
            let colon_is_block_item = next_line > clause_line
                && self.peek_at(2).kind != TokenKind::Eof
                && self.line_of(self.peek_at(2).span) == next_line;

            if next_line == clause_line || colon_is_block_item {
                let name = self.parse_ident_in("binding name")?;
                self.advance(); // consume ':'
                let inner = self.parse_clause_value(clause_start)?;
                return Some(Expr::Binding {
                    span: name.span.merge(inner.span()),
                    name,
                    value: Box::new(inner),
                });
            }
        }
        self.parse_clause_value(clause_start)
    }

    /// Parse a clause value. If the next token is on a new line (indented),
    /// collect a multi-line block. Otherwise parse a single expression.
    fn parse_clause_value(&mut self, clause_start: Span) -> Option<Expr> {
        let clause_line = self.line_of(clause_start);
        let next = self.peek();
        let next_line = self.line_of(next.span);

        if next_line > clause_line {
            // Multi-line block
            let base_col = self.col_of(next.span);
            self.parse_indented_block(base_col)
        } else {
            // Single-line — parse primary expression, then check for suffix predicate
            let expr = self.parse_expr(0)?;
            self.maybe_wrap_suffix_predicate(expr, clause_line)
        }
    }

    /// If there are remaining tokens on `clause_line` after the primary
    /// expression, collect them as a suffix predicate tail.
    fn maybe_wrap_suffix_predicate(&mut self, expr: Expr, clause_line: u32) -> Option<Expr> {
        if self.at_eof()
            || self.at(TokenKind::RBrace)
            || self.line_of(self.peek().span) != clause_line
        {
            return Some(expr);
        }

        let mut tail = Vec::new();
        while !self.at_eof()
            && !self.at(TokenKind::RBrace)
            && self.line_of(self.peek().span) == clause_line
        {
            if let Some(e) = self.try_parse_expr(0) {
                tail.push(e);
            } else {
                // Unrecognised token — consume as raw identifier to avoid stalling.
                let tok = self.advance();
                tail.push(Expr::Ident(Ident {
                    span: tok.span,
                    name: self.text(tok.span).to_string(),
                }));
            }
        }

        if tail.is_empty() {
            Some(expr)
        } else {
            let end = tail.last().unwrap().span();
            Some(Expr::Predicate {
                span: expr.span().merge(end),
                subject: Box::new(expr),
                tail,
            })
        }
    }

    /// Collect expressions that start at column >= `base_col` into a block.
    /// Also handles `let name = value` bindings inside clause value blocks.
    fn parse_indented_block(&mut self, base_col: u32) -> Option<Expr> {
        let start = self.peek().span;
        let mut items = Vec::new();

        while !self.at_eof()
            && !self.at(TokenKind::RBrace)
            && self.col_of(self.peek().span) >= base_col
        {
            // Handle `let name = value` inside expression blocks
            if self.at(TokenKind::Let) {
                let let_start = self.advance().span;
                if let Some(name) = self.parse_ident_in("binding name") {
                    if self.expect(TokenKind::Eq).is_some() {
                        if let Some(value) = self.parse_expr(0) {
                            items.push(Expr::LetExpr {
                                span: let_start.merge(value.span()),
                                name,
                                value: Box::new(value),
                            });
                            continue;
                        }
                    }
                }
                break;
            }

            if let Some(expr) = self.parse_expr(0) {
                items.push(expr);
            } else {
                self.advance();
                break;
            }
        }

        if items.len() == 1 {
            Some(items.pop().unwrap())
        } else {
            let end = items.last().map(|e| e.span()).unwrap_or(start);
            Some(Expr::Block {
                span: start.merge(end),
                items,
            })
        }
    }
}

// ---------------------------------------------------------------------------
// Expression parsing — Pratt parser
// ---------------------------------------------------------------------------

// Binding powers (even = left, odd = right for right-associative)
const BP_LAMBDA: u8 = 4;
const BP_WHEN_GUARD: u8 = 5;
const BP_OR: u8 = 10;
const BP_AND: u8 = 20;
const BP_COMPARE: u8 = 30;
const BP_TRANSITION: u8 = 32;
const BP_WITH_WHERE: u8 = 35;
const BP_PROJECTION: u8 = 37;
const BP_NULL_COALESCE: u8 = 40;
const BP_ADD: u8 = 50;
const BP_MUL: u8 = 60;
const BP_PIPE: u8 = 65;
const BP_PREFIX: u8 = 70;
const BP_POSTFIX: u8 = 80;

impl<'s> Parser<'s> {
    pub fn parse_expr(&mut self, min_bp: u8) -> Option<Expr> {
        let mut lhs = self.parse_prefix()?;

        loop {
            if let Some((l_bp, r_bp)) = self.infix_bp() {
                if l_bp < min_bp {
                    break;
                }
                lhs = self.parse_infix(lhs, r_bp)?;
            } else if let Some(l_bp) = self.postfix_bp() {
                if l_bp < min_bp {
                    break;
                }
                lhs = self.parse_postfix(lhs)?;
            } else {
                break;
            }
        }

        Some(lhs)
    }

    /// Try to parse an expression without emitting diagnostics on failure.
    /// Restores position if parsing fails.
    fn try_parse_expr(&mut self, min_bp: u8) -> Option<Expr> {
        let saved_pos = self.pos;
        let saved_diag_count = self.diagnostics.len();
        match self.parse_expr(min_bp) {
            Some(expr) => Some(expr),
            None => {
                self.pos = saved_pos;
                self.diagnostics.truncate(saved_diag_count);
                None
            }
        }
    }

    // -- prefix ---------------------------------------------------------

    fn parse_prefix(&mut self) -> Option<Expr> {
        match self.peek_kind() {
            TokenKind::Not => {
                let start = self.advance().span;
                if self.at(TokenKind::Exists) {
                    self.advance();
                    let operand = self.parse_expr(BP_PREFIX)?;
                    Some(Expr::NotExists {
                        span: start.merge(operand.span()),
                        operand: Box::new(operand),
                    })
                } else {
                    let operand = self.parse_expr(BP_PREFIX)?;
                    Some(Expr::Not {
                        span: start.merge(operand.span()),
                        operand: Box::new(operand),
                    })
                }
            }
            TokenKind::Exists => {
                // When `exists` is not followed by an expression-start token,
                // treat it as a plain identifier (e.g. `label: exists`).
                let next = self.peek_at(1).kind;
                if matches!(
                    next,
                    TokenKind::RParen
                        | TokenKind::RBrace
                        | TokenKind::RBracket
                        | TokenKind::Comma
                        | TokenKind::Eof
                ) {
                    let id = self.parse_ident()?;
                    return Some(Expr::Ident(id));
                }
                let start = self.advance().span;
                let operand = self.parse_expr(BP_PREFIX)?;
                Some(Expr::Exists {
                    span: start.merge(operand.span()),
                    operand: Box::new(operand),
                })
            }
            TokenKind::If => self.parse_if_expr(),
            TokenKind::For => self.parse_for_expr(),
            TokenKind::LBrace => self.parse_brace_expr(),
            TokenKind::LBracket => self.parse_list_literal(),
            TokenKind::LParen => self.parse_paren_expr(),
            TokenKind::Number => {
                let t = self.advance();
                Some(Expr::NumberLiteral {
                    span: t.span,
                    value: self.text(t.span).to_string(),
                })
            }
            TokenKind::Duration => {
                let t = self.advance();
                Some(Expr::DurationLiteral {
                    span: t.span,
                    value: self.text(t.span).to_string(),
                })
            }
            TokenKind::String => {
                let sl = self.parse_string()?;
                Some(Expr::StringLiteral(sl))
            }
            TokenKind::True => {
                let t = self.advance();
                Some(Expr::BoolLiteral {
                    span: t.span,
                    value: true,
                })
            }
            TokenKind::False => {
                let t = self.advance();
                Some(Expr::BoolLiteral {
                    span: t.span,
                    value: false,
                })
            }
            TokenKind::Null => {
                let t = self.advance();
                Some(Expr::Null { span: t.span })
            }
            TokenKind::Now => {
                let t = self.advance();
                Some(Expr::Now { span: t.span })
            }
            TokenKind::This => {
                let t = self.advance();
                Some(Expr::This { span: t.span })
            }
            TokenKind::Within => {
                let t = self.advance();
                Some(Expr::Within { span: t.span })
            }
            k if k.is_word() => {
                let id = self.parse_ident()?;
                Some(Expr::Ident(id))
            }
            TokenKind::Minus => {
                // Unary minus: -expr → BinaryOp(0, Sub, expr)
                let start = self.advance().span;
                let operand = self.parse_expr(BP_PREFIX)?;
                Some(Expr::BinaryOp {
                    span: start.merge(operand.span()),
                    left: Box::new(Expr::NumberLiteral {
                        span: start,
                        value: "0".into(),
                    }),
                    op: BinaryOp::Sub,
                    right: Box::new(operand),
                })
            }
            _ => {
                self.error(
                    self.peek().span,
                    format!(
                        "expected expression (identifier, number, string, true/false, null, \
                         if/for/not/exists, '(', '{{', '['), found {}",
                        self.peek_kind(),
                    ),
                );
                None
            }
        }
    }

    // -- infix binding powers -------------------------------------------

    fn infix_bp(&self) -> Option<(u8, u8)> {
        match self.peek_kind() {
            TokenKind::FatArrow => Some((BP_LAMBDA, BP_LAMBDA - 1)), // right-assoc
            // `when` as an inline guard on provides/related items
            TokenKind::When => Some((BP_WHEN_GUARD, BP_WHEN_GUARD + 1)),
            TokenKind::Pipe => Some((BP_PIPE, BP_PIPE + 1)),
            TokenKind::Or => Some((BP_OR, BP_OR + 1)),
            TokenKind::And => Some((BP_AND, BP_AND + 1)),
            TokenKind::Eq | TokenKind::EqEq | TokenKind::BangEq => {
                Some((BP_COMPARE, BP_COMPARE + 1))
            }
            TokenKind::Lt => {
                // If `<` is immediately adjacent to a word token (no space),
                // treat as generic type postfix, not comparison infix.
                if self.pos > 0 {
                    let prev = self.tokens[self.pos - 1];
                    if prev.span.end == self.peek().span.start && prev.kind.is_word() {
                        return None;
                    }
                }
                Some((BP_COMPARE, BP_COMPARE + 1))
            }
            TokenKind::LtEq | TokenKind::Gt | TokenKind::GtEq => {
                Some((BP_COMPARE, BP_COMPARE + 1))
            }
            TokenKind::In => Some((BP_COMPARE, BP_COMPARE + 1)),
            // `not in` — only when followed by `in`
            TokenKind::Not if self.peek_at(1).kind == TokenKind::In => {
                Some((BP_COMPARE, BP_COMPARE + 1))
            }
            TokenKind::TransitionsTo => Some((BP_TRANSITION, BP_TRANSITION + 1)),
            TokenKind::Becomes => Some((BP_TRANSITION, BP_TRANSITION + 1)),
            TokenKind::Includes => Some((BP_COMPARE, BP_COMPARE + 1)),
            TokenKind::Excludes => Some((BP_COMPARE, BP_COMPARE + 1)),
            TokenKind::Where => Some((BP_WITH_WHERE, BP_WITH_WHERE + 1)),
            TokenKind::With => Some((BP_WITH_WHERE, BP_WITH_WHERE + 1)),
            TokenKind::ThinArrow => Some((BP_PROJECTION, BP_PROJECTION + 1)),
            TokenKind::QuestionQuestion => Some((BP_NULL_COALESCE, BP_NULL_COALESCE + 1)),
            TokenKind::DotDot => Some((BP_ADD + 1, BP_ADD + 2)), // tighter than +/-
            TokenKind::Plus | TokenKind::Minus => Some((BP_ADD, BP_ADD + 1)),
            TokenKind::Star | TokenKind::Slash => Some((BP_MUL, BP_MUL + 1)),
            _ => None,
        }
    }

    fn parse_infix(&mut self, lhs: Expr, r_bp: u8) -> Option<Expr> {
        let op_tok = self.advance();
        match op_tok.kind {
            TokenKind::FatArrow => {
                let body = self.parse_expr(r_bp)?;
                Some(Expr::Lambda {
                    span: lhs.span().merge(body.span()),
                    param: Box::new(lhs),
                    body: Box::new(body),
                })
            }
            TokenKind::Pipe => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Pipe {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    right: Box::new(rhs),
                })
            }
            TokenKind::Or => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::LogicalOp {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: LogicalOp::Or,
                    right: Box::new(rhs),
                })
            }
            TokenKind::And => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::LogicalOp {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: LogicalOp::And,
                    right: Box::new(rhs),
                })
            }
            TokenKind::Eq | TokenKind::EqEq => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Comparison {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: ComparisonOp::Eq,
                    right: Box::new(rhs),
                })
            }
            TokenKind::BangEq => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Comparison {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: ComparisonOp::NotEq,
                    right: Box::new(rhs),
                })
            }
            TokenKind::Lt => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Comparison {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: ComparisonOp::Lt,
                    right: Box::new(rhs),
                })
            }
            TokenKind::LtEq => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Comparison {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: ComparisonOp::LtEq,
                    right: Box::new(rhs),
                })
            }
            TokenKind::Gt => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Comparison {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: ComparisonOp::Gt,
                    right: Box::new(rhs),
                })
            }
            TokenKind::GtEq => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Comparison {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: ComparisonOp::GtEq,
                    right: Box::new(rhs),
                })
            }
            TokenKind::In => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::In {
                    span: lhs.span().merge(rhs.span()),
                    element: Box::new(lhs),
                    collection: Box::new(rhs),
                })
            }
            TokenKind::Not => {
                // `not in`
                self.expect(TokenKind::In)?;
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::NotIn {
                    span: lhs.span().merge(rhs.span()),
                    element: Box::new(lhs),
                    collection: Box::new(rhs),
                })
            }
            TokenKind::Where => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Where {
                    span: lhs.span().merge(rhs.span()),
                    source: Box::new(lhs),
                    condition: Box::new(rhs),
                })
            }
            TokenKind::With => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::With {
                    span: lhs.span().merge(rhs.span()),
                    source: Box::new(lhs),
                    predicate: Box::new(rhs),
                })
            }
            TokenKind::QuestionQuestion => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::NullCoalesce {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    right: Box::new(rhs),
                })
            }
            TokenKind::Plus => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::BinaryOp {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: BinaryOp::Add,
                    right: Box::new(rhs),
                })
            }
            TokenKind::Minus => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::BinaryOp {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: BinaryOp::Sub,
                    right: Box::new(rhs),
                })
            }
            TokenKind::Star => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::BinaryOp {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: BinaryOp::Mul,
                    right: Box::new(rhs),
                })
            }
            TokenKind::Slash => {
                // Check for qualified name: `alias/Name` or `alias/config`
                // Qualified if the LHS is a bare identifier and the RHS is a
                // word that either starts with uppercase or is a block keyword
                // (like `config`).
                if let Expr::Ident(ref id) = lhs {
                    if self.peek_kind().is_word() {
                        let next_text = self.text(self.peek().span);
                        let is_qualified = next_text
                            .chars()
                            .next()
                            .is_some_and(|c| c.is_uppercase())
                            || matches!(
                                self.peek_kind(),
                                TokenKind::Config | TokenKind::Entity | TokenKind::Value
                            );
                        if is_qualified {
                            let name_tok = self.advance();
                            return Some(Expr::QualifiedName(QualifiedName {
                                span: lhs.span().merge(name_tok.span),
                                qualifier: Some(id.name.clone()),
                                name: self.text(name_tok.span).to_string(),
                            }));
                        }
                    }
                }
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::BinaryOp {
                    span: lhs.span().merge(rhs.span()),
                    left: Box::new(lhs),
                    op: BinaryOp::Div,
                    right: Box::new(rhs),
                })
            }
            TokenKind::ThinArrow => {
                let field = self.parse_ident_in("projection field")?;
                Some(Expr::ProjectionMap {
                    span: lhs.span().merge(field.span),
                    source: Box::new(lhs),
                    field,
                })
            }
            TokenKind::TransitionsTo => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::TransitionsTo {
                    span: lhs.span().merge(rhs.span()),
                    subject: Box::new(lhs),
                    new_state: Box::new(rhs),
                })
            }
            TokenKind::Becomes => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Becomes {
                    span: lhs.span().merge(rhs.span()),
                    subject: Box::new(lhs),
                    new_state: Box::new(rhs),
                })
            }
            TokenKind::Includes => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Includes {
                    span: lhs.span().merge(rhs.span()),
                    collection: Box::new(lhs),
                    element: Box::new(rhs),
                })
            }
            TokenKind::Excludes => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Excludes {
                    span: lhs.span().merge(rhs.span()),
                    collection: Box::new(lhs),
                    element: Box::new(rhs),
                })
            }
            TokenKind::When => {
                // Inline guard: `action when condition`
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::WhenGuard {
                    span: lhs.span().merge(rhs.span()),
                    action: Box::new(lhs),
                    condition: Box::new(rhs),
                })
            }
            TokenKind::DotDot => {
                let rhs = self.parse_expr(r_bp)?;
                Some(Expr::Range {
                    span: lhs.span().merge(rhs.span()),
                    start: Box::new(lhs),
                    end: Box::new(rhs),
                })
            }
            _ => {
                self.error(
                    op_tok.span,
                    format!("unexpected infix operator {}", op_tok.kind),
                );
                None
            }
        }
    }

    // -- postfix --------------------------------------------------------

    fn postfix_bp(&self) -> Option<u8> {
        match self.peek_kind() {
            TokenKind::Dot | TokenKind::QuestionDot => Some(BP_POSTFIX),
            TokenKind::QuestionMark => Some(BP_POSTFIX),
            // `<` for generic types like `Set<T>`, `List<T>` — only treated
            // as postfix when it immediately follows a word with no space.
            TokenKind::Lt => {
                if self.pos > 0 {
                    let prev = self.tokens[self.pos - 1];
                    // Only if `<` starts immediately after the previous token
                    // (no whitespace gap) to distinguish from comparisons.
                    if prev.span.end == self.peek().span.start && prev.kind.is_word() {
                        return Some(BP_POSTFIX);
                    }
                }
                None
            }
            TokenKind::LParen => Some(BP_POSTFIX),
            TokenKind::LBrace => {
                // Join lookup: only when preceded by something that looks
                // like an entity name (handled generically — any expr can
                // be followed by { for join lookup in expression position).
                // But only if the { is on the same line to avoid consuming
                // a block body.
                let next = self.peek();
                let prev_end = if self.pos > 0 {
                    self.tokens[self.pos - 1].span.end
                } else {
                    0
                };
                // Same line check
                if self.line_of(Span::new(prev_end, prev_end))
                    == self.line_of(next.span)
                {
                    Some(BP_POSTFIX)
                } else {
                    None
                }
            }
            _ => None,
        }
    }

    fn parse_postfix(&mut self, lhs: Expr) -> Option<Expr> {
        match self.peek_kind() {
            TokenKind::QuestionMark => {
                let end = self.advance().span;
                Some(Expr::TypeOptional {
                    span: lhs.span().merge(end),
                    inner: Box::new(lhs),
                })
            }
            TokenKind::Lt => {
                // Generic type: `Set<T>`, `List<Node?>`
                self.advance(); // consume <
                let mut args = Vec::new();
                // Parse args above comparison BP so `>` isn't consumed as infix
                while !self.at(TokenKind::Gt) && !self.at_eof() {
                    args.push(self.parse_expr(BP_COMPARE + 1)?);
                    self.eat(TokenKind::Comma);
                }
                let end = self.expect(TokenKind::Gt)?.span;
                Some(Expr::GenericType {
                    span: lhs.span().merge(end),
                    name: Box::new(lhs),
                    args,
                })
            }
            TokenKind::Dot => {
                self.advance();
                let field = self.parse_ident_in("field name")?;
                Some(Expr::MemberAccess {
                    span: lhs.span().merge(field.span),
                    object: Box::new(lhs),
                    field,
                })
            }
            TokenKind::QuestionDot => {
                self.advance();
                let field = self.parse_ident_in("field name")?;
                Some(Expr::OptionalAccess {
                    span: lhs.span().merge(field.span),
                    object: Box::new(lhs),
                    field,
                })
            }
            TokenKind::LParen => {
                self.advance();
                let args = self.parse_call_args()?;
                let end = self.expect(TokenKind::RParen)?.span;
                Some(Expr::Call {
                    span: lhs.span().merge(end),
                    function: Box::new(lhs),
                    args,
                })
            }
            TokenKind::LBrace => {
                self.advance();
                let fields = self.parse_join_fields()?;
                let end = self.expect(TokenKind::RBrace)?.span;
                Some(Expr::JoinLookup {
                    span: lhs.span().merge(end),
                    entity: Box::new(lhs),
                    fields,
                })
            }
            _ => None,
        }
    }

    // -- call arguments -------------------------------------------------

    fn parse_call_args(&mut self) -> Option<Vec<CallArg>> {
        let mut args = Vec::new();
        while !self.at(TokenKind::RParen) && !self.at_eof() {
            // Check for named argument: `name: value`
            if self.peek_kind().is_word() && self.peek_at(1).kind == TokenKind::Colon {
                let name = self.parse_ident_in("argument name")?;
                self.advance(); // :
                let value = self.parse_expr(0)?;
                args.push(CallArg::Named(NamedArg {
                    span: name.span.merge(value.span()),
                    name,
                    value,
                }));
            } else {
                let expr = self.parse_expr(0)?;
                args.push(CallArg::Positional(expr));
            }
            self.eat(TokenKind::Comma);
        }
        Some(args)
    }

    // -- join fields ----------------------------------------------------

    fn parse_join_fields(&mut self) -> Option<Vec<JoinField>> {
        let mut fields = Vec::new();
        while !self.at(TokenKind::RBrace) && !self.at_eof() {
            let field = self.parse_ident_in("join field name")?;
            let value = if self.eat(TokenKind::Colon).is_some() {
                Some(self.parse_expr(0)?)
            } else {
                None
            };
            fields.push(JoinField {
                span: field.span.merge(
                    value
                        .as_ref()
                        .map(|v| v.span())
                        .unwrap_or(field.span),
                ),
                field,
                value,
            });
            self.eat(TokenKind::Comma);
        }
        Some(fields)
    }

    // -- if expression --------------------------------------------------

    fn parse_if_expr(&mut self) -> Option<Expr> {
        let start = self.advance().span; // consume `if`
        let mut branches = Vec::new();

        // First branch
        let condition = self.parse_expr(0)?;
        self.expect(TokenKind::Colon)?;
        let body = self.parse_branch_body(start)?;
        branches.push(CondBranch {
            span: start.merge(body.span()),
            condition,
            body,
        });

        // else if / else
        let mut else_body = None;
        while self.at(TokenKind::Else) {
            let else_tok = self.advance();
            if self.at(TokenKind::If) {
                let if_start = self.advance().span;
                let cond = self.parse_expr(0)?;
                self.expect(TokenKind::Colon)?;
                let body = self.parse_branch_body(else_tok.span)?;
                branches.push(CondBranch {
                    span: if_start.merge(body.span()),
                    condition: cond,
                    body,
                });
            } else {
                self.expect(TokenKind::Colon)?;
                let body = self.parse_branch_body(else_tok.span)?;
                else_body = Some(Box::new(body));
                break;
            }
        }

        let end = else_body
            .as_ref()
            .map(|b| b.span())
            .or_else(|| branches.last().map(|b| b.body.span()))
            .unwrap_or(start);

        Some(Expr::Conditional {
            span: start.merge(end),
            branches,
            else_body,
        })
    }

    fn parse_branch_body(&mut self, keyword_span: Span) -> Option<Expr> {
        let keyword_line = self.line_of(keyword_span);
        let next_line = self.line_of(self.peek().span);

        if next_line > keyword_line {
            let base_col = self.col_of(self.peek().span);
            self.parse_indented_block(base_col)
        } else {
            self.parse_expr(0)
        }
    }

    // -- for expression -------------------------------------------------

    fn parse_for_expr(&mut self) -> Option<Expr> {
        let start = self.advance().span; // consume `for`
        let binding = self.parse_ident_in("loop variable")?;
        self.expect(TokenKind::In)?;

        // Parse collection, stopping before `where` and `:`
        let collection = self.parse_expr(BP_WITH_WHERE + 1)?;

        let filter = if self.eat(TokenKind::Where).is_some() {
            // Parse filter at min_bp 0 — colon terminates naturally.
            Some(Box::new(self.parse_expr(0)?))
        } else {
            None
        };

        self.expect(TokenKind::Colon)?;
        let body = self.parse_branch_body(start)?;

        Some(Expr::For {
            span: start.merge(body.span()),
            binding,
            collection: Box::new(collection),
            filter,
            body: Box::new(body),
        })
    }

    // -- brace expressions: set literal or object literal ---------------

    fn parse_brace_expr(&mut self) -> Option<Expr> {
        let start = self.advance().span; // consume {

        if self.at(TokenKind::RBrace) {
            let end = self.advance().span;
            return Some(Expr::SetLiteral {
                span: start.merge(end),
                elements: Vec::new(),
            });
        }

        // Peek: if first item is `ident:`, it's an object literal
        if self.peek_kind().is_word() && self.peek_at(1).kind == TokenKind::Colon {
            return self.parse_object_literal(start);
        }

        // Otherwise set literal
        self.parse_set_literal(start)
    }

    fn parse_list_literal(&mut self) -> Option<Expr> {
        let start = self.advance().span; // consume [
        let mut elements = Vec::new();
        while !self.at(TokenKind::RBracket) && !self.at_eof() {
            elements.push(self.parse_expr(0)?);
            self.eat(TokenKind::Comma);
        }
        let end = self.expect(TokenKind::RBracket)?.span;
        Some(Expr::ListLiteral {
            span: start.merge(end),
            elements,
        })
    }

    fn parse_object_literal(&mut self, start: Span) -> Option<Expr> {
        let mut fields = Vec::new();
        while !self.at(TokenKind::RBrace) && !self.at_eof() {
            let name = self.parse_ident_in("field name")?;
            self.expect(TokenKind::Colon)?;
            let value = self.parse_expr(0)?;
            fields.push(NamedArg {
                span: name.span.merge(value.span()),
                name,
                value,
            });
            self.eat(TokenKind::Comma);
        }
        let end = self.expect(TokenKind::RBrace)?.span;
        Some(Expr::ObjectLiteral {
            span: start.merge(end),
            fields,
        })
    }

    fn parse_set_literal(&mut self, start: Span) -> Option<Expr> {
        let mut elements = Vec::new();
        while !self.at(TokenKind::RBrace) && !self.at_eof() {
            elements.push(self.parse_expr(0)?);
            self.eat(TokenKind::Comma);
        }
        let end = self.expect(TokenKind::RBrace)?.span;
        Some(Expr::SetLiteral {
            span: start.merge(end),
            elements,
        })
    }

    // -- parenthesised expression ---------------------------------------

    fn parse_paren_expr(&mut self) -> Option<Expr> {
        self.advance(); // (
        let expr = self.parse_expr(0)?;
        self.expect(TokenKind::RParen)?;
        Some(expr)
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    fn parse_ok(src: &str) -> ParseResult {
        let result = parse(src);
        if !result.diagnostics.is_empty() {
            for d in &result.diagnostics {
                eprintln!(
                    "  [{:?}] {} ({}..{})",
                    d.severity, d.message, d.span.start, d.span.end
                );
            }
        }
        result
    }

    #[test]
    fn version_marker() {
        let r = parse_ok("-- allium: 1\n");
        assert_eq!(r.module.version, Some(1));
    }

    #[test]
    fn empty_entity() {
        let r = parse_ok("entity User {}");
        assert_eq!(r.diagnostics.len(), 0);
        assert_eq!(r.module.declarations.len(), 1);
        match &r.module.declarations[0] {
            Decl::Block(b) => {
                assert_eq!(b.kind, BlockKind::Entity);
                assert_eq!(b.name.as_ref().unwrap().name, "User");
            }
            other => panic!("expected Block, got {other:?}"),
        }
    }

    #[test]
    fn entity_with_fields() {
        let src = r#"entity Order {
    customer: Customer
    status: pending | active | completed
    total: Decimal
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        match &r.module.declarations[0] {
            Decl::Block(b) => {
                assert_eq!(b.items.len(), 3);
            }
            other => panic!("expected Block, got {other:?}"),
        }
    }

    #[test]
    fn use_declaration() {
        let r = parse_ok(r#"use "github.com/specs/oauth/abc123" as oauth"#);
        assert_eq!(r.diagnostics.len(), 0);
        match &r.module.declarations[0] {
            Decl::Use(u) => {
                assert_eq!(u.alias.as_ref().unwrap().name, "oauth");
            }
            other => panic!("expected Use, got {other:?}"),
        }
    }

    #[test]
    fn enum_declaration() {
        let src = "enum OrderStatus { pending | shipped | delivered }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn config_block() {
        let src = r#"config {
    max_retries: Integer = 3
    timeout: Duration = 24.hours
}"#;
        // Config entries are `name: Type = default`. The parser sees
        // `name: Type = default` as an assignment where the value is
        // `Type = default` (comparison with Eq). That's fine for the
        // parse tree — semantic pass separates type from default.
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn rule_declaration() {
        let src = r#"rule PlaceOrder {
    when: CustomerPlacesOrder(customer, items, total)
    requires: total > 0
    ensures: Order.created(customer: customer, status: pending, total: total)
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        match &r.module.declarations[0] {
            Decl::Block(b) => {
                assert_eq!(b.kind, BlockKind::Rule);
                assert_eq!(b.items.len(), 3);
            }
            other => panic!("expected Block, got {other:?}"),
        }
    }

    #[test]
    fn expression_precedence() {
        let r = parse_ok("rule T { v: a + b * c }");
        // The value should be Add(a, Mul(b, c))
        match &r.module.declarations[0] {
            Decl::Block(b) => match &b.items[0].kind {
                BlockItemKind::Assignment { value, .. } => match value {
                    Expr::BinaryOp { op, right, .. } => {
                        assert_eq!(*op, BinaryOp::Add);
                        assert!(matches!(**right, Expr::BinaryOp { op: BinaryOp::Mul, .. }));
                    }
                    other => panic!("expected BinaryOp, got {other:?}"),
                },
                other => panic!("expected Assignment, got {other:?}"),
            },
            other => panic!("expected Block, got {other:?}"),
        }
    }

    #[test]
    fn default_declaration() {
        let src = r#"default Role admin = { name: "admin", permissions: { "read" } }"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn open_question() {
        let src = r#"open question "Should admins be role-specific?""#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn external_entity() {
        let src = "external entity Customer { email: String }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        match &r.module.declarations[0] {
            Decl::Block(b) => assert_eq!(b.kind, BlockKind::ExternalEntity),
            other => panic!("expected Block, got {other:?}"),
        }
    }

    #[test]
    fn where_expression() {
        let src = "entity E { active: items where status = active }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn with_expression() {
        let src = "entity E { slots: InterviewSlot with candidacy = this }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn lambda_expression() {
        let src = "entity E { v: items.any(i => i.active) }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn deferred() {
        let src = "deferred InterviewerMatching.suggest";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn variant_declaration() {
        let src = "variant Email : Notification { subject: String }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- projection mapping -----------------------------------------------

    #[test]
    fn projection_arrow() {
        let src = "entity E { confirmed: confirmations where status = confirmed -> interviewer }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- transitions_to / becomes ------------------------------------------

    #[test]
    fn transitions_to_trigger() {
        let src = "rule R { when: Interview.status transitions_to scheduled\n    ensures: Notification.created() }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn becomes_trigger() {
        let src = "rule R { when: Interview.status becomes scheduled\n    ensures: Notification.created() }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- binding colon in clause values ------------------------------------

    #[test]
    fn when_binding() {
        let src = "rule R {\n    when: interview: Interview.status transitions_to scheduled\n    ensures: Notification.created()\n}";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        // The when clause value should be a Binding wrapping a TransitionsTo
        let decl = &r.module.declarations[0];
        if let Decl::Block(b) = decl {
            if let BlockItemKind::Clause { keyword, value } = &b.items[0].kind {
                assert_eq!(keyword, "when");
                assert!(matches!(value, Expr::Binding { .. }));
            } else {
                panic!("expected clause");
            }
        } else {
            panic!("expected block decl");
        }
    }

    #[test]
    fn when_binding_temporal() {
        let src = "rule R {\n    when: invitation: Invitation.expires_at <= now\n    ensures: Invitation.expired()\n}";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn when_binding_created() {
        let src = "rule R {\n    when: batch: DigestBatch.created\n    ensures: Email.created()\n}";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn facing_binding() {
        let src = "surface S {\n    facing viewer: Interviewer\n    exposes: InterviewList\n}";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn context_binding() {
        let src = "surface S {\n    facing viewer: Interviewer\n    context assignment: SlotConfirmation where interviewer = viewer\n}";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- rule-level for block item -----------------------------------------

    #[test]
    fn rule_level_for() {
        let src = r#"rule ProcessDigests {
    when: schedule: DigestSchedule.next_run_at <= now
    for user in Users where notification_setting.digest_enabled:
        ensures: DigestBatch.created(user: user)
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        if let Decl::Block(b) = &r.module.declarations[0] {
            // Should have when clause + for block item
            assert!(b.items.len() >= 2);
            assert!(matches!(b.items[1].kind, BlockItemKind::ForBlock { .. }));
        } else {
            panic!("expected block decl");
        }
    }

    // -- let inside ensures blocks -----------------------------------------

    #[test]
    fn let_in_ensures_block() {
        let src = r#"rule R {
    when: ScheduleInterview(candidacy, time, interviewers)
    ensures:
        let slot = InterviewSlot.created(time: time, candidacy: candidacy)
        for interviewer in interviewers:
            SlotConfirmation.created(slot: slot, interviewer: interviewer)
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- when guard on provides items --------------------------------------

    #[test]
    fn provides_when_guard() {
        let src = "surface S {\n    facing viewer: Interviewer\n    provides: ConfirmSlot(viewer, slot) when slot.status = pending\n}";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- optional type suffix ----------------------------------------------

    #[test]
    fn optional_type_suffix() {
        let src = "entity E { locked_until: Timestamp? }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    #[test]
    fn optional_trigger_param() {
        let src = "rule R { when: Report(interviewer, interview, reason, details?)\n    ensures: Done() }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- qualified name with config ----------------------------------------

    #[test]
    fn qualified_config_access() {
        let src = "entity E { duration: oauth/config.session_duration }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- comprehensive integration test ------------------------------------

    #[test]
    fn realistic_spec() {
        let src = r#"-- allium: 1

enum OrderStatus { pending | shipped | delivered }

external entity Customer {
    email: String
    name: String
}

entity Order {
    customer: Customer
    status: OrderStatus
    total: Decimal
    items: OrderItem with order = this
    shipped_items: items where status = shipped
    confirmed_items: items where status = confirmed -> item
    is_complete: status = delivered
    locked_until: Timestamp?
}

config {
    max_retries: Integer = 3
    timeout: Duration = 24.hours
}

rule PlaceOrder {
    when: CustomerPlacesOrder(customer, items, total)
    requires: total > 0
    ensures: Order.created(customer: customer, status: pending, total: total)
}

rule ShipOrder {
    when: order: Order.status transitions_to shipped
    ensures: Email.created(to: order.customer.email, template: order_shipped)
}

open question "How do we handle partial shipments?"
"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0, "expected no errors");
        assert_eq!(r.module.version, Some(1));
        assert_eq!(r.module.declarations.len(), 7);
    }

    #[test]
    fn extension_behaviour_excerpt() {
        // Exercises: inline enums, generic types, or-triggers, named call
        // args, config with typed defaults, module declaration.
        let src = r#"value Document {
    uri: String
    text: String
}

entity Finding {
    code: String
    severity: error | warning | info
    range: FindingRange
}

entity DiagnosticsMode {
    value: strict | relaxed
}

config {
    duplicateKey: String = "allium.config.duplicateKey"
}

rule RefreshDiagnostics {
    when: DocumentOpened(document) or DocumentChanged(document)
    requires: document.language_id = "allium"
    ensures: FindingsComputed(document)
}

surface DiagnosticsDashboard {
    facing viewer: Developer
    context doc: Document where viewer.active_document = doc
    provides: RunChecks(viewer) when doc.language_id = "allium"
    exposes: FindingList
}

rule ProcessDigests {
    when: schedule: DigestSchedule.next_run_at <= now
    for user in Users where notification_setting.digest_enabled:
        let settings = user.notification_setting
        ensures: DigestBatch.created(user: user)
}
"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0, "expected no errors");
        // value + entity + entity + config + rule + surface + rule = 7
        assert_eq!(r.module.declarations.len(), 7);
    }

    #[test]
    fn suffix_predicate_simple() {
        let src = r#"rule R {
    when: RenameRequested(symbol)
    requires: symbol resolves_to_single_definition
    ensures: RenameApplied()
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        // when + requires + ensures = 3 items
        assert_eq!(b.items.len(), 3);
        // The requires value should be a Predicate
        let BlockItemKind::Clause { keyword, value } = &b.items[1].kind else { panic!() };
        assert_eq!(keyword, "requires");
        assert!(matches!(value, Expr::Predicate { .. }));
    }

    #[test]
    fn suffix_predicate_with_arg() {
        let src = r#"rule R {
    when: X()
    requires: finding.code starts_with "allium."
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::Clause { value, .. } = &b.items[1].kind else { panic!() };
        if let Expr::Predicate { subject, tail, .. } = value {
            assert!(matches!(subject.as_ref(), Expr::MemberAccess { .. }));
            assert_eq!(tail.len(), 2); // starts_with + "allium."
        } else {
            panic!("expected Predicate, got {:?}", value);
        }
    }

    #[test]
    fn suffix_predicate_with_comparison() {
        let src = r#"rule R {
    when: X()
    requires: clause compares_literals = true
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::Clause { value, .. } = &b.items[1].kind else { panic!() };
        // Should be Predicate(clause, [Comparison(compares_literals, Eq, true)])
        if let Expr::Predicate { tail, .. } = value {
            assert_eq!(tail.len(), 1);
            assert!(matches!(tail[0], Expr::Comparison { .. }));
        } else {
            panic!("expected Predicate");
        }
    }

    #[test]
    fn range_literal_in_list() {
        let src = r#"rule R {
    when: X()
    requires: width in [1..8]
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::Clause { value, .. } = &b.items[1].kind else { panic!() };
        // Should be In(width, ListLiteral([Range(1, 8)]))
        if let Expr::In { collection, .. } = value {
            if let Expr::ListLiteral { elements, .. } = collection.as_ref() {
                assert_eq!(elements.len(), 1);
                assert!(matches!(elements[0], Expr::Range { .. }));
            } else {
                panic!("expected ListLiteral");
            }
        } else {
            panic!("expected In");
        }
    }

    #[test]
    fn exists_as_identifier() {
        let src = r#"rule R {
    when: X()
    ensures: CompletionItemAvailable(label: exists)
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- pipe precedence: tighter than boolean ops ----------------------------

    #[test]
    fn pipe_binds_tighter_than_or() {
        // `a or b | c` should parse as `a or (b | c)`, not `(a or b) | c`
        let src = "entity E { v: a or b | c }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::Assignment { value, .. } = &b.items[0].kind else { panic!() };
        // Top-level should be LogicalOp(Or)
        let Expr::LogicalOp { op, right, .. } = value else {
            panic!("expected LogicalOp, got {value:?}");
        };
        assert_eq!(*op, LogicalOp::Or);
        // Right side should be Pipe(b, c)
        assert!(matches!(right.as_ref(), Expr::Pipe { .. }));
    }

    // -- variant with expression base -----------------------------------------

    #[test]
    fn variant_with_pipe_base() {
        let src = "variant Mixed : TypeA | TypeB";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Variant(v) = &r.module.declarations[0] else { panic!() };
        assert!(matches!(v.base, Expr::Pipe { .. }));
    }

    // -- trigger clause keyword -----------------------------------------------

    #[test]
    fn trigger_clause() {
        let src = "rule R { trigger: ExternalEvent(data)\n    ensures: Done() }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::Clause { keyword, .. } = &b.items[0].kind else { panic!() };
        assert_eq!(keyword, "trigger");
    }

    // -- for-block with comparison in where filter ----------------------------

    #[test]
    fn for_block_where_comparison() {
        let src = r#"rule R {
    when: X()
    for item in Items where item.status = active:
        ensures: Processed(item: item)
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::ForBlock { filter, .. } = &b.items[1].kind else { panic!() };
        assert!(filter.is_some());
        assert!(matches!(filter.as_ref().unwrap(), Expr::Comparison { .. }));
    }

    // -- for-expression with comparison in where filter -----------------------

    #[test]
    fn for_expr_where_comparison() {
        let src = r#"rule R {
    when: X()
    ensures:
        for item in Items where item.active = true:
            Processed(item: item)
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- if/else if/else chain ------------------------------------------------

    #[test]
    fn if_else_if_else() {
        let src = r#"rule R {
    when: X(v)
    ensures:
        if v < 10: Small()
        else if v < 100: Medium()
        else: Large()
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- null coalescing and optional chaining --------------------------------

    #[test]
    fn null_coalesce_and_optional_chain() {
        let src = "entity E { v: a?.b ?? fallback }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::Assignment { value, .. } = &b.items[0].kind else { panic!() };
        // Top-level should be NullCoalesce
        assert!(matches!(value, Expr::NullCoalesce { .. }));
    }

    // -- generic types --------------------------------------------------------

    #[test]
    fn generic_type_nested() {
        let src = "entity E { v: List<Set<String>> }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- set literal, list literal, object literal ----------------------------

    #[test]
    fn collection_literals() {
        let src = r#"rule R {
    when: X()
    ensures:
        let s = {a, b, c}
        let l = [1, 2, 3]
        let o = {name: "test", count: 42}
        Done()
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- given block ----------------------------------------------------------

    #[test]
    fn given_block() {
        let src = "given { viewer: User\n    time: Timestamp }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        assert_eq!(b.kind, BlockKind::Given);
        assert!(b.name.is_none());
    }

    // -- actor block ----------------------------------------------------------

    #[test]
    fn actor_block() {
        let src = "actor Admin { identified_by: User where role = admin }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        assert_eq!(b.kind, BlockKind::Actor);
    }

    // -- join lookup ----------------------------------------------------------

    #[test]
    fn join_lookup() {
        let src = "entity E { match: Other{field_a, field_b: value} }";
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
        let Decl::Block(b) = &r.module.declarations[0] else { panic!() };
        let BlockItemKind::Assignment { value, .. } = &b.items[0].kind else { panic!() };
        assert!(matches!(value, Expr::JoinLookup { .. }));
    }

    // -- includes / excludes --------------------------------------------------

    #[test]
    fn includes_excludes() {
        let src = r#"rule R {
    when: X(a, b)
    requires: a.items includes b
    requires: a.items excludes b
    ensures: Done()
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- in / not in with set literal -----------------------------------------

    #[test]
    fn in_not_in_set() {
        let src = r#"rule R {
    when: X(s)
    requires: s in {a, b, c}
    requires: s not in {d, e}
    ensures: Done()
}"#;
        let r = parse_ok(src);
        assert_eq!(r.diagnostics.len(), 0);
    }

    // -- comprehensive fixture file -------------------------------------------

    #[test]
    fn comprehensive_fixture() {
        let src = include_str!("../tests/fixtures/comprehensive-edge-cases.allium");
        let r = parse(src);
        assert_eq!(
            r.diagnostics.len(),
            0,
            "expected no errors in comprehensive fixture, got: {:?}",
            r.diagnostics.iter().map(|d| &d.message).collect::<Vec<_>>(),
        );
        assert!(r.module.declarations.len() > 30, "expected many declarations");
    }

    // -- error message quality ------------------------------------------------

    #[test]
    fn error_expected_declaration() {
        let r = parse("+ invalid");
        assert!(r.diagnostics.len() >= 1);
        let msg = &r.diagnostics[0].message;
        assert!(msg.contains("expected declaration"), "got: {msg}");
        assert!(msg.contains("entity"), "should list valid options, got: {msg}");
        assert!(msg.contains("rule"), "should list valid options, got: {msg}");
    }

    #[test]
    fn error_expected_expression() {
        let r = parse("entity E { v: }");
        assert!(r.diagnostics.len() >= 1);
        let msg = &r.diagnostics[0].message;
        assert!(msg.contains("expected expression"), "got: {msg}");
        assert!(msg.contains("identifier"), "should list valid starters, got: {msg}");
    }

    #[test]
    fn error_expected_block_item() {
        let r = parse("entity E { + }");
        assert!(r.diagnostics.len() >= 1);
        let msg = &r.diagnostics[0].message;
        assert!(msg.contains("expected block item"), "got: {msg}");
    }

    #[test]
    fn error_expected_identifier() {
        let r = parse("entity 123 {}");
        assert!(r.diagnostics.len() >= 1);
        let msg = &r.diagnostics[0].message;
        // Context-aware: says "entity name" not generic "identifier"
        assert!(msg.contains("expected entity name"), "got: {msg}");
        // Human-friendly: says "number" not "Number" or "TokenKind::Number"
        assert!(msg.contains("number"), "should say what was found, got: {msg}");
    }

    #[test]
    fn error_missing_brace() {
        let r = parse("entity E {");
        assert!(r.diagnostics.len() >= 1);
        let msg = &r.diagnostics[0].message;
        assert!(msg.contains("expected"), "got: {msg}");
    }

    #[test]
    fn error_recovery_multiple() {
        // Parser should recover and report multiple errors
        let r = parse("entity E { + }\nentity F { - }");
        assert!(r.diagnostics.len() >= 2, "expected at least 2 errors, got {}", r.diagnostics.len());
    }
}