luna_core/frontend/

parser.rs

//! Recursive-descent parser; grammar and operator priorities follow PUC
//! lparser.c. Statement/expression nesting is depth-limited like PUC's
//! C-stack guard.

use crate::frontend::ast::*;
use crate::frontend::error::SyntaxError;
use crate::frontend::goto_check::GotoCheck;
use crate::frontend::lexer::{Lexed, Lexer};
use crate::frontend::span::Span;
use crate::frontend::token::{Near, Token, TokenInfo, near_text};
use crate::version::LuaVersion;

/// PUC `LUAI_MAXCCALLS` — the parser's nesting cap. PUC sets it to 200 and
/// increments once per `subexpr`/`funcargs`/`simpleexp`/`block`/`statement`
/// call; luna's `enter()` fires on roughly the same surfaces (statement +
/// sub_expr + suffixedexp + block), so the same 200 budget keeps
/// errors.lua's `testrep` baseline — 190 levels compile, 201 hits the wall.
const MAX_DEPTH: u32 = 200;

/// PUC `MAXVARS`: active locals per function.
const MAXVARS: u32 = 200;

/// `(collective attrib, declared names, initializer exprs)` of a declaration.
type DeclList = (Option<Attrib>, Vec<AttribName>, Vec<ExprId>);

/// Binary operator priorities from lparser.c (left, right); right < left
/// means right-associative.
fn bin_priority(op: BinOp) -> (u8, u8) {
    match op {
        BinOp::Or => (1, 1),
        BinOp::And => (2, 2),
        BinOp::Lt | BinOp::Gt | BinOp::Le | BinOp::Ge | BinOp::Ne | BinOp::Eq => (3, 3),
        BinOp::BOr => (4, 4),
        BinOp::BXor => (5, 5),
        BinOp::BAnd => (6, 6),
        BinOp::Shl | BinOp::Shr => (7, 7),
        BinOp::Concat => (9, 8),
        BinOp::Add | BinOp::Sub => (10, 10),
        BinOp::Mul | BinOp::Div | BinOp::IDiv | BinOp::Mod => (11, 11),
        BinOp::Pow => (14, 13),
    }
}

const UNARY_PRIORITY: u8 = 12;

fn bin_op_of(tok: &Token) -> Option<BinOp> {
    Some(match tok {
        Token::Plus => BinOp::Add,
        Token::Minus => BinOp::Sub,
        Token::Star => BinOp::Mul,
        Token::Slash => BinOp::Div,
        Token::DSlash => BinOp::IDiv,
        Token::Percent => BinOp::Mod,
        Token::Caret => BinOp::Pow,
        Token::Concat => BinOp::Concat,
        Token::Eq => BinOp::Eq,
        Token::Ne => BinOp::Ne,
        Token::Lt => BinOp::Lt,
        Token::Le => BinOp::Le,
        Token::Gt => BinOp::Gt,
        Token::Ge => BinOp::Ge,
        Token::And => BinOp::And,
        Token::Or => BinOp::Or,
        Token::Amp => BinOp::BAnd,
        Token::Pipe => BinOp::BOr,
        Token::Tilde => BinOp::BXor,
        Token::Shl => BinOp::Shl,
        Token::Shr => BinOp::Shr,
        _ => return None,
    })
}

fn un_op_of(tok: &Token) -> Option<UnOp> {
    Some(match tok {
        Token::Minus => UnOp::Neg,
        Token::Not => UnOp::Not,
        Token::Hash => UnOp::Len,
        Token::Tilde => UnOp::BNot,
        _ => return None,
    })
}

/// Token feed for the recursive-descent parser. Either a live [`Lexer`]
/// (the default `parse(src, version)` path) or a pre-materialized token
/// vector (the [`parse_tokens`] entry point used by the MacroLua expander
/// pre-pass — see `frontend::macro_expander`). Both arms support
/// `next_token` and `src()`.
pub(crate) enum TokenSource<'s> {
    /// Streaming lexer over raw source bytes.
    Lexer(Lexer<'s>),
    /// Pre-materialized token stream + a back-pointer to the original
    /// source bytes so `Token::describe` can still slice spans for
    /// `... near 'tok'` error reporting.
    PreExpanded {
        tokens: Vec<TokenInfo>,
        cursor: usize,
        src: &'s [u8],
    },
}

/// A token as the parser holds it. `char` is set when the lexer handed back
/// a byte no token starts with; `info.tok` is then a placeholder that no
/// grammar rule accepts ([`Token::At`], which only MacroLua lexes, and
/// MacroLua never parses from a live lexer).
struct Cur {
    info: TokenInfo,
    char: Option<u8>,
}

impl<'s> TokenSource<'s> {
    fn next_token(&mut self) -> Result<Cur, SyntaxError> {
        match self {
            TokenSource::Lexer(l) => Ok(match l.next_lexed()? {
                Lexed::Tok(info) => Cur { info, char: None },
                Lexed::Char(c, mut info) => {
                    info.tok = Token::At;
                    Cur {
                        info,
                        char: Some(c),
                    }
                }
            }),
            TokenSource::PreExpanded {
                tokens,
                cursor,
                src,
            } => {
                if *cursor >= tokens.len() {
                    let line = tokens.last().map(|t| t.line).unwrap_or(1);
                    let _ = src;
                    Ok(Cur {
                        info: TokenInfo {
                            tok: Token::Eof,
                            span: Span::new(0, 0),
                            line,
                        },
                        char: None,
                    })
                } else {
                    let t = tokens[*cursor].clone();
                    *cursor += 1;
                    Ok(Cur {
                        info: t,
                        char: None,
                    })
                }
            }
        }
    }

    fn src(&self) -> &'s [u8] {
        match self {
            TokenSource::Lexer(l) => l.src(),
            TokenSource::PreExpanded { src, .. } => src,
        }
    }

    /// PUC `ls->linenumber`: where the scanner stands, which is where every
    /// syntax error is reported.
    fn line(&self) -> u32 {
        match self {
            TokenSource::Lexer(l) => l.line(),
            TokenSource::PreExpanded { tokens, cursor, .. } => tokens
                .get(cursor.saturating_sub(1))
                .or(tokens.last())
                .map_or(1, |t| t.line),
        }
    }
}

/// Parse a Lua source chunk for the given dialect into an arena AST
/// ([`Chunk`]).
///
/// `LuaVersion::MacroLua` sources are **not** routed through the macro
/// expander here — this entry point is dialect-agnostic and only sees
/// the raw token stream. The Vm's `eval` path runs the expander
/// transparently for MacroLua; direct callers feed expanded tokens via
/// [`parse_tokens`].
pub fn parse(src: &[u8], version: LuaVersion) -> Result<Chunk, SyntaxError> {
    parse_at_depth(src, version, 0).map(|p| p.chunk)
}

/// A parsed chunk with what the public [`Chunk`] has no place for.
pub(crate) struct Parsed {
    pub(crate) chunk: Chunk,
    /// the line of the closing `end` of each `while` / `for` statement, by
    /// `StatId` (0 for other statements): PUC attributes the code it emits
    /// after reading that `end` to its line
    pub(crate) end_lines: Vec<u32>,
}

/// [`parse`] run by a VM that is `c_depth` C calls deep. PUC's parser
/// counts its nesting on the running thread's `nCcalls`, so a chunk loaded
/// near the C-call limit fails to *parse* (and `require` reports it as an
/// error loading the module) before the call that would run it overflows.
pub(crate) fn parse_at_depth(
    src: &[u8],
    version: LuaVersion,
    c_depth: u32,
) -> Result<Parsed, SyntaxError> {
    let lex = Lexer::new(src, version);
    parse_from_source(TokenSource::Lexer(lex), version, c_depth)
}

/// Parse a **pre-materialized** token stream. Used by the MacroLua
/// expander pre-pass — it walks the lexer output once, expands
/// `@name(...)` invocations against the per-Vm macro registry, and
/// feeds the resulting `Vec<TokenInfo>` here.
pub fn parse_tokens(
    tokens: Vec<TokenInfo>,
    src: &[u8],
    version: LuaVersion,
) -> Result<Chunk, SyntaxError> {
    parse_tokens_at_depth(tokens, src, version, 0).map(|p| p.chunk)
}

/// [`parse_tokens`] at a C depth (see [`parse_at_depth`]).
pub(crate) fn parse_tokens_at_depth(
    tokens: Vec<TokenInfo>,
    src: &[u8],
    version: LuaVersion,
    c_depth: u32,
) -> Result<Parsed, SyntaxError> {
    parse_from_source(
        TokenSource::PreExpanded {
            tokens,
            cursor: 0,
            src,
        },
        version,
        c_depth,
    )
}

fn parse_from_source<'s>(
    mut lex: TokenSource<'s>,
    version: LuaVersion,
    c_depth: u32,
) -> Result<Parsed, SyntaxError> {
    let cur = lex.next_token()?;
    let mut p = Parser {
        lex,
        tok: cur.info,
        tok_char: cur.char,
        peeked: None,
        prev_line: 1,
        exprs: Vec::new(),
        stats: Vec::new(),
        stat_lines: Vec::new(),
        end_lines: Vec::new(),
        depth: c_depth,
        version,
        // the main chunk is the bottom-most function context (line 0 → main)
        func_local_count: vec![(0, 0, 0)],
        funcs: vec![FnFlow {
            vararg: true,
            loops: 0,
        }],
        gotos: GotoCheck::new(version),
        last_line: 1,
        upval_chain_51: if version <= LuaVersion::Lua51 {
            vec![FnUvSlot {
                line_defined: 0,
                ..Default::default()
            }]
        } else {
            Vec::new()
        },
    };
    if let Some(g) = p.gotos.as_mut() {
        g.enter_function();
    }
    let block = p.block()?;
    if p.tok.tok != Token::Eof {
        return Err(p.error_expected("<eof>"));
    }
    p.close_function()?;
    let end_line = p.prev_line;
    Ok(Parsed {
        chunk: Chunk {
            exprs: p.exprs,
            stats: p.stats,
            stat_lines: p.stat_lines,
            block,
            end_line,
        },
        end_lines: p.end_lines,
    })
}

struct Parser<'s> {
    lex: TokenSource<'s>,
    tok: TokenInfo,
    /// The byte behind a placeholder `tok` (see [`Cur`]).
    tok_char: Option<u8>,
    peeked: Option<Cur>,
    /// Per open function (main chunk first): what `...` and `break` are
    /// checked against while parsing, as PUC does.
    funcs: Vec<FnFlow>,
    /// Gotos (and 5.2-5.4 `break`) are resolved while parsing; see
    /// [`GotoCheck`].
    gotos: Option<GotoCheck>,
    /// PUC `ls->lastline`: where the scanner stood before reading the
    /// current token, i.e. the line the last consumed token ended on.
    last_line: u32,
    /// line of the previously consumed token (for the 5.1 ambiguity check)
    prev_line: u32,
    exprs: Vec<Expr>,
    stats: Vec<Stat>,
    /// starting source line of each statement (by StatId), for precise per-
    /// instruction line info in the compiler
    stat_lines: Vec<u32>,
    /// see [`Parsed::end_lines`]
    end_lines: Vec<u32>,
    depth: u32,
    version: LuaVersion,
    /// One entry per function context (main chunk + nested functions): the
    /// running active-local count (PUC `nactvar`), the function's defining
    /// line so the limit error can render "in function at line N", and the
    /// locals declared but not yet in scope (`local a, b` before its `=`
    /// list is parsed). Pushed by
    /// `func_body`, popped on exit. Without parse-time tracking, errors.lua
    /// :775 would race a later structural error (a missing `end`) and lose.
    func_local_count: Vec<(u32, u32, u32)>,
    /// Parse-time upvalue accounting for PUC 5.1 (errors.lua :238). PUC 5.1's
    /// `singlevaraux` resolves each identifier as it parses and stops at
    /// `MAXUPVAL=60`; luna defers name resolution to the compiler so a stack
    /// of 61 nested `function`s with no `end`s reaches `<eof>` first and the
    /// missing-`end` error wins. Tracking declared locals + accumulated
    /// upvalue names per nested function here lets the same 60-deep chain
    /// trip while we are still inside `foo61`'s body, with the offending
    /// function's defining line on the error. Only populated for 5.1 — 5.2+
    /// goes through `_ENV` (which would itself be an upvalue) and 5.5
    /// tolerates a wider cap.
    upval_chain_51: Vec<FnUvSlot>,
}

struct FnFlow {
    vararg: bool,
    /// Loops enclosing the current position inside this function.
    loops: u32,
}

#[derive(Default)]
struct FnUvSlot {
    locals: Vec<Box<str>>,
    upvalues: std::collections::HashSet<Box<str>>,
    line_defined: u32,
}

impl<'s> Parser<'s> {
    // ---- token plumbing ----

    fn advance(&mut self) -> Result<TokenInfo, SyntaxError> {
        self.last_line = self.lex.line();
        let next = match self.peeked.take() {
            Some(t) => t,
            None => self.lex.next_token()?,
        };
        self.prev_line = self.tok.line;
        self.tok_char = next.char;
        Ok(std::mem::replace(&mut self.tok, next.info))
    }

    fn peek(&mut self) -> Result<&Token, SyntaxError> {
        if self.peeked.is_none() {
            self.peeked = Some(self.lex.next_token()?);
        }
        Ok(&self.peeked.as_ref().unwrap().info.tok)
    }

    fn near(&self) -> Vec<u8> {
        match self.tok_char {
            Some(c) => near_text(self.version, Near::Char(c)),
            None => self
                .tok
                .tok
                .near_bytes(self.lex.src(), self.tok.span, self.version),
        }
    }

    /// PUC `luaX_syntaxerror`: `msg near <current token>`.
    fn error(&self, msg: impl AsRef<str>) -> SyntaxError {
        // a NUL byte comes back from PUC's scanner as token 0, which
        // `lexerror` reads as "no near-token"
        if self.tok_char == Some(0) {
            return self.plain_error(msg.as_ref());
        }
        let mut bytes = msg.as_ref().as_bytes().to_vec();
        bytes.extend_from_slice(b" near ");
        bytes.extend_from_slice(&self.near());
        SyntaxError {
            line: self.lex.line(),
            msg: bytes,
        }
    }

    /// PUC `luaK_semerror` / `luaX_lexerror(.., 0)`: no near-token.
    fn plain_error(&self, msg: impl Into<Vec<u8>>) -> SyntaxError {
        SyntaxError {
            line: self.lex.line(),
            msg: msg.into(),
        }
    }

    /// PUC `error_expected`. `what` is a token as `luaX_token2str` spells
    /// it; the `<name>`-style pseudo-tokens are quoted only by 5.1.
    fn error_expected(&self, what: &str) -> SyntaxError {
        if what.starts_with('<') && self.version >= LuaVersion::Lua52 {
            self.error(format!("{what} expected"))
        } else {
            self.error(format!("'{what}' expected"))
        }
    }

    fn accept(&mut self, tok: Token) -> Result<bool, SyntaxError> {
        if self.tok.tok == tok {
            self.advance()?;
            Ok(true)
        } else {
            Ok(false)
        }
    }

    fn expect(&mut self, tok: Token, what: &str) -> Result<(), SyntaxError> {
        if !self.accept(tok)? {
            return Err(self.error_expected(what));
        }
        Ok(())
    }

    /// Like PUC check_match: closing token with a pointer back to the opener.
    fn expect_match(
        &mut self,
        tok: Token,
        what: &str,
        who: &str,
        who_line: u32,
    ) -> Result<(), SyntaxError> {
        if !self.accept(tok)? {
            if who_line == self.lex.line() {
                return Err(self.error_expected(what));
            }
            return Err(self.error(format!(
                "'{what}' expected (to close '{who}' at line {who_line})"
            )));
        }
        Ok(())
    }

    fn expect_name(&mut self) -> Result<Name, SyntaxError> {
        if !matches!(self.tok.tok, Token::Name(_)) {
            return Err(self.error_expected("<name>"));
        }
        let info = self.advance()?;
        let Token::Name(text) = info.tok else {
            unreachable!()
        };
        Ok(Name {
            text,
            line: info.line,
        })
    }

    fn enter(&mut self) -> Result<(), SyntaxError> {
        self.depth += 1;
        // 5.1-5.3 `enterlevel` fails past the limit; 5.4+ `luaE_incCstack`
        // at it
        let limit = if self.version >= LuaVersion::Lua54 {
            MAX_DEPTH - 1
        } else {
            MAX_DEPTH
        };
        if self.depth > limit {
            return Err(self.levels_error());
        }
        Ok(())
    }

    /// PUC's nesting-limit error: 5.1 `enterlevel` has its own wording and
    /// no near-token; 5.2/5.3 run it through `errorlimit` ("C levels", in
    /// the function being parsed); 5.4+ count parser levels on the C stack,
    /// and `luaE_checkcstack` raises a runtime error that carries no
    /// position because the running function is `load`, not Lua code.
    fn levels_error(&self) -> SyntaxError {
        match self.version {
            LuaVersion::Lua51 => self.plain_error("chunk has too many syntax levels"),
            LuaVersion::Lua52 | LuaVersion::Lua53 => self.error(format!(
                "too many C levels (limit is 200) in {}",
                self.where_()
            )),
            _ => SyntaxError::unpositioned("C stack overflow"),
        }
    }

    /// PUC `errorlimit`'s `where`: the function being parsed.
    fn where_(&self) -> String {
        let &(_, line_defined, _) = self.func_local_count.last().expect("func ctx");
        if self.func_local_count.len() == 1 {
            "main function".to_string()
        } else {
            format!("function at line {line_defined}")
        }
    }

    fn leave(&mut self) {
        self.depth -= 1;
    }

    fn push_expr(&mut self, e: Expr) -> ExprId {
        self.exprs.push(e);
        ExprId((self.exprs.len() - 1) as u32)
    }

    fn push_stat(&mut self, s: Stat) -> StatId {
        self.stats.push(s);
        StatId((self.stats.len() - 1) as u32)
    }

    /// Push a statement that ended with the `end` just read.
    fn push_ended_stat(&mut self, s: Stat) -> StatId {
        let id = self.push_stat(s);
        let idx = id.0 as usize;
        self.end_lines.resize(idx + 1, 0);
        self.end_lines[idx] = self.prev_line;
        id
    }

    // ---- blocks & statements ----

    fn block_follow(&self) -> bool {
        matches!(
            self.tok.tok,
            Token::Eof | Token::End | Token::Else | Token::Elseif | Token::Until
        )
    }

    fn block(&mut self) -> Result<Block, SyntaxError> {
        self.enter()?;
        // PUC `leaveblock` restores `nactvar` to the count at block entry, so
        // a block's locals fall out of scope when it ends. Snapshot the count
        // here so the limit check tracks ACTIVE locals (locals.lua opens many
        // short blocks; without this the cap fires spuriously).
        let local_snapshot = self.func_local_count.last().expect("func ctx").0;
        let locals_51_snap = self.snap_locals_51();
        self.goto_step(|g| {
            g.enter_block(false);
            Ok(())
        })?;
        let mut stats = Vec::new();
        loop {
            // labels wait for the no-op statements that follow them
            if self.gotos.as_ref().is_some_and(GotoCheck::has_open_labels)
                && !matches!(self.tok.tok, Token::Semi | Token::DColon)
            {
                let last = matches!(
                    self.tok.tok,
                    Token::Else | Token::Elseif | Token::End | Token::Eof
                );
                self.goto_step(|g| g.finish_labels(last))?;
            }
            if self.block_follow() {
                break;
            }
            if self.tok.tok == Token::Return {
                stats.push(self.return_stat()?);
                break;
            }
            if self.tok.tok == Token::Break && self.version.break_is_last_statement() {
                let line = self.tok.line;
                self.break_stat()?;
                stats.push(self.push_stat(Stat::Break { line }));
                self.accept(Token::Semi)?;
                break;
            }
            if let Some(s) = self.statement()? {
                stats.push(s);
            }
            if !self.version.has_empty_statement() {
                // 5.1: ';' is a separator after a statement, not a statement
                self.accept(Token::Semi)?;
            }
        }
        self.goto_step(GotoCheck::leave_block)?;
        self.leave();
        self.func_local_count.last_mut().expect("func ctx").0 = local_snapshot;
        self.restore_locals_51(locals_51_snap);
        Ok(Block { stats })
    }

    fn return_stat(&mut self) -> Result<StatId, SyntaxError> {
        let line = self.tok.line;
        self.advance()?;
        let exprs = if self.block_follow() || self.tok.tok == Token::Semi {
            Vec::new()
        } else {
            self.exprlist()?
        };
        self.accept(Token::Semi)?;
        Ok(self.push_stat(Stat::Return { exprs, line }))
    }

    fn statement(&mut self) -> Result<Option<StatId>, SyntaxError> {
        // PUC's `statement` does not bump `nCcalls` itself — the surrounding
        // `block` does, and nested forms (do/while/if/function/...) each
        // recurse through `block` again. Counting both would double the cost
        // per `do … end` nesting; errors.lua's `testrep("do ", "", " end")`
        // expects 190 levels to compile and 201 to fail at the same wall as
        // the other shapes.
        let start_line = self.tok.line;
        // 5.5 `global` is a contextual keyword: a declaration only when it
        // leads a statement and the next token starts one (name / '*' /
        // function / attribute '<'). Otherwise it is an ordinary identifier
        // (e.g. `global = 1`, `global()`, `return global`).
        if self.version.has_global_decl()
            && matches!(&self.tok.tok, Token::Name(n) if &**n == "global")
            && matches!(
                self.peek()?,
                Token::Name(_) | Token::Star | Token::Function | Token::Lt
            )
        {
            let stat = self.global_stat()?;
            self.set_stat_line(stat, start_line);
            return Ok(Some(stat));
        }
        let stat = match self.tok.tok {
            Token::Semi => {
                if !self.version.has_empty_statement() {
                    return Err(self.error("unexpected symbol"));
                }
                self.advance()?;
                None
            }
            Token::If => Some(self.if_stat()?),
            Token::While => Some(self.while_stat()?),
            Token::Do => {
                let line = self.tok.line;
                self.advance()?;
                let body = self.block()?;
                self.expect_match(Token::End, "end", "do", line)?;
                Some(self.push_stat(Stat::Do(body)))
            }
            Token::For => Some(self.for_stat()?),
            Token::Repeat => Some(self.repeat_stat()?),
            Token::Function => Some(self.function_stat()?),
            Token::Local => Some(self.local_stat()?),
            Token::DColon => {
                self.advance()?;
                let name = self.expect_name()?;
                let text = name.text.clone();
                self.goto_step(|g| g.label_before_close(&text, start_line))?;
                self.expect(Token::DColon, "::")?;
                Some(self.push_stat(Stat::Label(name)))
            }
            Token::Break => {
                let line = self.tok.line;
                self.break_stat()?;
                Some(self.push_stat(Stat::Break { line }))
            }
            Token::Goto => {
                // 5.4 reads the goto's line after skipping the keyword, 5.5
                // takes the statement's
                let mut line = self.lex.line();
                self.advance()?;
                if self.version >= LuaVersion::Lua55 {
                    line = start_line;
                } else if self.version >= LuaVersion::Lua54 {
                    line = self.lex.line();
                }
                let name = self.expect_name()?;
                let text = name.text.clone();
                self.goto_step(|g| g.goto_stat(&text, line))?;
                Some(self.push_stat(Stat::Goto(name)))
            }
            _ => Some(self.expr_stat()?),
        };
        if let Some(sid) = stat {
            self.set_stat_line(sid, start_line);
        }
        Ok(stat)
    }

    fn set_stat_line(&mut self, sid: StatId, line: u32) {
        let idx = sid.0 as usize;
        if self.stat_lines.len() <= idx {
            self.stat_lines.resize(idx + 1, 0);
        }
        self.stat_lines[idx] = line;
    }

    /// Consume `break`, checking it the way the dialect does: 5.1 and 5.5
    /// on the spot (5.1 after skipping the keyword, 5.5 before); 5.2–5.4
    /// treat it as a goto to the loop's end, so a break outside a loop is
    /// an unresolved goto when the function closes.
    fn break_stat(&mut self) -> Result<(), SyntaxError> {
        let line = self.lex.line();
        let in_loop = self.funcs.last().expect("func ctx").loops > 0;
        if !in_loop && self.version >= LuaVersion::Lua55 {
            return Err(self.error("break outside loop"));
        }
        self.advance()?;
        if !in_loop && self.version <= LuaVersion::Lua51 {
            return Err(self.error("no loop to break"));
        }
        if self.version >= LuaVersion::Lua55 {
            return Ok(());
        }
        self.goto_step(|g| g.goto_stat("break", line))
    }

    /// A loop body with the loop's own variables (`vars`) in scope: PUC's
    /// loop block, which places the "break" label, around a block for the
    /// declared variables.
    fn loop_block(&mut self, vars: &[Name]) -> Result<Block, SyntaxError> {
        self.funcs.last_mut().expect("func ctx").loops += 1;
        self.goto_step(|g| {
            g.enter_block(true);
            g.enter_block(false);
            for v in vars {
                g.declare(&v.text);
            }
            Ok(())
        })?;
        let body = self.block()?;
        self.goto_step(|g| {
            g.leave_block()?;
            g.leave_block()
        })?;
        self.funcs.last_mut().expect("func ctx").loops -= 1;
        Ok(body)
    }

    /// PUC `close_func` → `leaveblock` of the function's outer block, which
    /// runs after the closing token has been consumed: a goto (or 5.2-5.4
    /// `break`) that found no label is reported there, at the scanner's
    /// line.
    fn close_function(&mut self) -> Result<(), SyntaxError> {
        let _ = self.funcs.pop().expect("func ctx");
        self.goto_step(GotoCheck::leave_block)
    }

    /// Run a step of the goto check (dialects that have one), turning its
    /// error into a syntax error without a near-token (PUC `semerror`),
    /// which 5.5 reports at the line of the last token consumed.
    fn goto_step(
        &mut self,
        step: impl FnOnce(&mut GotoCheck) -> Result<(), String>,
    ) -> Result<(), SyntaxError> {
        match self.gotos.as_mut().map(step) {
            Some(Err(msg)) if self.version >= LuaVersion::Lua55 => Err(SyntaxError {
                line: self.last_line,
                msg: msg.into_bytes(),
            }),
            Some(Err(msg)) => Err(self.plain_error(msg)),
            _ => Ok(()),
        }
    }

    fn if_stat(&mut self) -> Result<StatId, SyntaxError> {
        let line = self.tok.line;
        self.advance()?;
        let mut arms = Vec::new();
        let cond = self.expr()?;
        let then_line = self.tok.line;
        self.expect(Token::Then, "then")?;
        arms.push((cond, then_line, self.block()?));
        while self.tok.tok == Token::Elseif {
            self.advance()?;
            let cond = self.expr()?;
            let then_line = self.tok.line;
            self.expect(Token::Then, "then")?;
            arms.push((cond, then_line, self.block()?));
        }
        let else_body = if self.accept(Token::Else)? {
            Some(self.block()?)
        } else {
            None
        };
        self.expect_match(Token::End, "end", "if", line)?;
        Ok(self.push_stat(Stat::If { arms, else_body }))
    }

    fn while_stat(&mut self) -> Result<StatId, SyntaxError> {
        let line = self.tok.line;
        self.advance()?;
        let cond = self.expr()?;
        self.expect(Token::Do, "do")?;
        let body = self.loop_block(&[])?;
        self.expect_match(Token::End, "end", "while", line)?;
        Ok(self.push_ended_stat(Stat::While { cond, body }))
    }

    fn repeat_stat(&mut self) -> Result<StatId, SyntaxError> {
        let line = self.tok.line;
        self.advance()?;
        let body = self.loop_block(&[])?;
        self.expect_match(Token::Until, "until", "repeat", line)?;
        let cond = self.expr()?;
        Ok(self.push_stat(Stat::Repeat { body, cond }))
    }

    fn for_stat(&mut self) -> Result<StatId, SyntaxError> {
        let line = self.tok.line;
        self.advance()?;
        let first = self.expect_name()?;
        match self.tok.tok {
            Token::Assign => {
                self.advance()?;
                let start = self.expr()?;
                self.expect(Token::Comma, ",")?;
                let limit = self.expr()?;
                let step = if self.accept(Token::Comma)? {
                    Some(self.expr()?)
                } else {
                    None
                };
                self.expect(Token::Do, "do")?;
                self.add_local_51(&first.text);
                let body = self.loop_block(std::slice::from_ref(&first))?;
                self.expect_match(Token::End, "end", "for", line)?;
                Ok(self.push_ended_stat(Stat::NumericFor {
                    var: first,
                    start,
                    limit,
                    step,
                    body,
                }))
            }
            Token::Comma | Token::In => {
                let mut vars = vec![first];
                while self.accept(Token::Comma)? {
                    vars.push(self.expect_name()?);
                }
                self.expect(Token::In, "in")?;
                let expr_line = self.tok.line;
                let exprs = self.exprlist()?;
                self.expect(Token::Do, "do")?;
                for v in &vars {
                    self.add_local_51(&v.text);
                }
                let body = self.loop_block(&vars)?;
                self.expect_match(Token::End, "end", "for", line)?;
                Ok(self.push_ended_stat(Stat::GenericFor {
                    vars,
                    exprs,
                    body,
                    expr_line,
                }))
            }
            _ => Err(self.error("'=' or 'in' expected")),
        }
    }

    fn function_stat(&mut self) -> Result<StatId, SyntaxError> {
        let line = self.tok.line;
        self.advance()?;
        let base = self.expect_name()?;
        let mut path = Vec::new();
        while self.accept(Token::Dot)? {
            path.push(self.expect_name()?);
        }
        let method = if self.accept(Token::Colon)? {
            Some(self.expect_name()?)
        } else {
            None
        };
        let body = self.func_body(line)?;
        Ok(self.push_stat(Stat::Function {
            name: FuncName { base, path, method },
            body,
        }))
    }

    fn attrib(&mut self) -> Result<Option<Attrib>, SyntaxError> {
        if !(self.version.has_attribs() && self.tok.tok == Token::Lt) {
            return Ok(None);
        }
        self.advance()?;
        let name = self.expect_name()?;
        let attrib = match &*name.text {
            "const" => Attrib::Const,
            "close" => Attrib::Close,
            other => {
                return Err(SyntaxError {
                    line: name.line,
                    msg: format!("unknown attribute '{other}'").into_bytes(),
                });
            }
        };
        self.expect(Token::Gt, ">")?;
        Ok(Some(attrib))
    }

    /// `[attrib] Name [attrib] {',' Name [attrib]} ['=' explist]` — shared by
    /// `local` and `global` declarations.
    fn attnamelist(&mut self) -> Result<DeclList, SyntaxError> {
        let collective = if self.version.has_collective_attrib() {
            self.attrib()?
        } else {
            None
        };
        let mut names = Vec::new();
        loop {
            let name = self.expect_name()?;
            self.new_local()?;
            let attrib = self.attrib()?;
            names.push(AttribName { name, attrib });
            if !self.accept(Token::Comma)? {
                break;
            }
        }
        let exprs = if self.accept(Token::Assign)? {
            self.exprlist()?
        } else {
            Vec::new()
        };
        Ok((collective, names, exprs))
    }

    fn local_stat(&mut self) -> Result<StatId, SyntaxError> {
        self.advance()?;
        if self.accept(Token::Function)? {
            let line = self.prev_line;
            let name = self.expect_name()?;
            // `local function f` declares `f` in the enclosing function before
            // the body is parsed (PUC `localfunc`'s pre-declare); count it.
            self.new_local()?;
            self.activate_locals()?;
            self.add_local_51(&name.text);
            let text = name.text.clone();
            self.goto_step(|g| {
                g.declare(&text);
                Ok(())
            })?;
            let body = self.func_body(line)?;
            return Ok(self.push_stat(Stat::LocalFunction { name, body }));
        }
        let (collective, names, exprs) = self.attnamelist()?;
        self.activate_locals()?;
        self.goto_step(|g| {
            for an in &names {
                g.declare(&an.name.text);
            }
            Ok(())
        })?;
        for an in &names {
            self.add_local_51(&an.name.text);
        }
        Ok(self.push_stat(Stat::Local {
            collective,
            names,
            exprs,
        }))
    }

    fn global_stat(&mut self) -> Result<StatId, SyntaxError> {
        self.advance()?;
        if self.accept(Token::Function)? {
            let line = self.prev_line;
            let name = self.expect_name()?;
            let text = name.text.clone();
            self.goto_step(|g| {
                g.declare(&text);
                Ok(())
            })?;
            let body = self.func_body(line)?;
            return Ok(self.push_stat(Stat::GlobalFunction { name, body }));
        }
        // `global [attrib] '*'`
        let leading = self.attrib()?;
        if self.accept(Token::Star)? {
            self.goto_step(|g| {
                g.declare("*");
                Ok(())
            })?;
            return Ok(self.push_stat(Stat::GlobalAll { attrib: leading }));
        }
        let mut names = Vec::new();
        loop {
            let name = self.expect_name()?;
            let attrib = self.attrib()?;
            names.push(AttribName { name, attrib });
            if !self.accept(Token::Comma)? {
                break;
            }
        }
        let exprs = if self.accept(Token::Assign)? {
            self.exprlist()?
        } else {
            Vec::new()
        };
        // the declared names come into scope after their initializers
        self.goto_step(|g| {
            for an in &names {
                g.declare(&an.name.text);
            }
            Ok(())
        })?;
        Ok(self.push_stat(Stat::Global {
            collective: leading,
            names,
            exprs,
        }))
    }

    fn expr_stat(&mut self) -> Result<StatId, SyntaxError> {
        let first = self.suffixed_expr()?;
        let is_call = matches!(
            self.exprs[first.0 as usize],
            Expr::Call { .. } | Expr::MethodCall { .. }
        );
        // 5.1 `exprstat` takes anything that is not a call as the start of
        // an assignment (so a lone `x` wants an '='); 5.2+ look for '=' or
        // ',' first and otherwise demand a call.
        let assign = if self.version <= LuaVersion::Lua51 {
            !is_call
        } else {
            matches!(self.tok.tok, Token::Assign | Token::Comma)
        };
        if !assign {
            if !is_call {
                return Err(self.error("syntax error"));
            }
            return Ok(self.push_stat(Stat::Call(first)));
        }
        // PUC `assignment`/`restassign` check each target as soon as it is
        // parsed, so the near-token is the one following that target.
        let mut targets = vec![first];
        let mut entered = 0;
        loop {
            let last = *targets.last().expect("one target");
            if !matches!(
                self.exprs[last.0 as usize],
                Expr::Name(_) | Expr::Index { .. }
            ) {
                return Err(self.error("syntax error"));
            }
            if !self.accept(Token::Comma)? {
                break;
            }
            // PUC recurses once per extra target and bounds that against
            // the C-call budget (errors.lua :650 expects the error for 500
            // targets), after reading the target: 5.1 as a count of
            // "variables in assignment", 5.2/5.3 as C levels, 5.4+ by
            // entering a level that stays entered until the statement ends.
            let nvars = targets.len() as u32;
            targets.push(self.suffixed_expr()?);
            match self.version {
                LuaVersion::Lua51 => {
                    let limit = MAX_DEPTH.saturating_sub(self.depth);
                    if nvars > limit {
                        return Err(self.plain_error(format!(
                            "{} has more than {limit} variables in assignment",
                            self.where_()
                        )));
                    }
                }
                LuaVersion::Lua52 | LuaVersion::Lua53 => {
                    if nvars + self.depth > MAX_DEPTH {
                        return Err(self.levels_error());
                    }
                }
                _ => {
                    self.enter()?;
                    entered += 1;
                }
            }
        }
        self.expect(Token::Assign, "=")?;
        let exprs = self.exprlist()?;
        self.depth -= entered;
        Ok(self.push_stat(Stat::Assign { targets, exprs }))
    }

    // ---- expressions ----

    fn exprlist(&mut self) -> Result<Vec<ExprId>, SyntaxError> {
        let mut list = vec![self.expr()?];
        while self.accept(Token::Comma)? {
            list.push(self.expr()?);
        }
        Ok(list)
    }

    fn expr(&mut self) -> Result<ExprId, SyntaxError> {
        self.sub_expr(0)
    }

    fn sub_expr(&mut self, limit: u8) -> Result<ExprId, SyntaxError> {
        self.enter()?;
        let mut left = if let Some(op) = un_op_of(&self.tok.tok) {
            let line = self.tok.line;
            self.advance()?;
            let operand = self.sub_expr(UNARY_PRIORITY)?;
            self.push_expr(Expr::UnOp { op, operand, line })
        } else {
            self.simple_expr()?
        };
        while let Some(op) = bin_op_of(&self.tok.tok) {
            let (lp, rp) = bin_priority(op);
            if lp <= limit {
                break;
            }
            let line = self.tok.line;
            self.advance()?;
            let rhs = self.sub_expr(rp)?;
            left = self.push_expr(Expr::BinOp {
                op,
                lhs: left,
                rhs,
                line,
            });
        }
        self.leave();
        Ok(left)
    }

    fn simple_expr(&mut self) -> Result<ExprId, SyntaxError> {
        let e = match &self.tok.tok {
            Token::Nil => {
                self.advance()?;
                Expr::Nil
            }
            Token::True => {
                self.advance()?;
                Expr::True
            }
            Token::False => {
                self.advance()?;
                Expr::False
            }
            Token::Ellipsis => {
                if !self.funcs.last().expect("func ctx").vararg {
                    return Err(self.error("cannot use '...' outside a vararg function"));
                }
                self.advance()?;
                Expr::Vararg
            }
            Token::Int(_) => {
                let Token::Int(v) = self.advance()?.tok else {
                    unreachable!()
                };
                Expr::Int(v)
            }
            Token::Float(_) => {
                let Token::Float(v) = self.advance()?.tok else {
                    unreachable!()
                };
                Expr::Float(v)
            }
            Token::Str(_) => {
                let Token::Str(s) = self.advance()?.tok else {
                    unreachable!()
                };
                Expr::Str(s)
            }
            Token::LBrace => return self.table_constructor(),
            Token::Function => {
                let line = self.tok.line;
                self.advance()?;
                Expr::Function(self.func_body(line)?)
            }
            _ => return self.suffixed_expr(),
        };
        Ok(self.push_expr(e))
    }

    fn primary_expr(&mut self) -> Result<ExprId, SyntaxError> {
        match &self.tok.tok {
            Token::Name(_) => {
                let name = self.expect_name()?;
                self.ident_lookup_51(&name.text)?;
                Ok(self.push_expr(Expr::Name(name)))
            }
            Token::LParen => {
                let line = self.tok.line;
                self.advance()?;
                let inner = self.expr()?;
                self.expect_match(Token::RParen, ")", "(", line)?;
                Ok(self.push_expr(Expr::Paren(inner)))
            }
            _ => Err(self.error("unexpected symbol")),
        }
    }

    fn suffixed_expr(&mut self) -> Result<ExprId, SyntaxError> {
        // PUC's `suffixedexp` does *not* bump `nCcalls` on its own — only its
        // callers do (subexpr, funcargs, …). Doing so here too would
        // double-count `(` nesting, since `simpleexp`'s default branch dives
        // through `suffixed_expr` → `primary_expr` → `expr()` → `sub_expr`
        // (which already enters). Keeping the entry out lets errors.lua's
        // `testrep("(")` (paren-only nesting) hit the same 200-level wall as
        // `{`/`,` nesting.
        // PUC 5.1–5.3 `suffixedexp` captured the line of the *primary*
        // expression once and pinned every chained call/method to it
        // (`a\n(...)` → error reports on `a`'s line); 5.4 switched to
        // tracking the current line at each suffix and reports on the `(`
        // line instead. errors.lua's `lineerror` covers both:
        //   - 5.3:  `lineerror([[a\n(\n23)]], 1)` — expects `a`'s line
        //   - 5.4+: `lineerror([[a\n(...)\n23)]], 2)` — expects `(`'s line
        let primary_line = self.tok.line;
        let mut e = self.primary_expr()?;
        loop {
            match &self.tok.tok {
                Token::Dot => {
                    self.advance()?;
                    let name = self.expect_name()?;
                    let key = self.push_expr(Expr::Str(name.text.into_boxed_bytes().into_vec()));
                    e = self.push_expr(Expr::Index { obj: e, key });
                }
                Token::LBracket => {
                    self.advance()?;
                    let key = self.expr()?;
                    self.expect(Token::RBracket, "]")?;
                    e = self.push_expr(Expr::Index { obj: e, key });
                }
                Token::Colon => {
                    self.advance()?;
                    let method = self.expect_name()?;
                    let line = if self.version <= LuaVersion::Lua53 {
                        primary_line
                    } else {
                        self.tok.line
                    };
                    let args = self.call_args()?;
                    e = self.push_expr(Expr::MethodCall {
                        obj: e,
                        method,
                        args,
                        line,
                    });
                }
                Token::LParen | Token::Str(_) | Token::LBrace => {
                    let line = if self.version <= LuaVersion::Lua53 {
                        primary_line
                    } else {
                        self.tok.line
                    };
                    let args = self.call_args()?;
                    e = self.push_expr(Expr::Call {
                        func: e,
                        args,
                        line,
                    });
                }
                _ => break,
            }
        }
        Ok(e)
    }

    fn call_args(&mut self) -> Result<Vec<ExprId>, SyntaxError> {
        match &self.tok.tok {
            Token::LParen => {
                // 5.1 rejects a call paren on a new line (removed in 5.2)
                if self.version == LuaVersion::Lua51 && self.tok.line != self.prev_line {
                    return Err(self.error("ambiguous syntax (function call x new statement)"));
                }
                let line = self.tok.line;
                self.advance()?;
                let args = if self.tok.tok == Token::RParen {
                    Vec::new()
                } else {
                    self.exprlist()?
                };
                self.expect_match(Token::RParen, ")", "(", line)?;
                Ok(args)
            }
            Token::Str(_) => {
                let Token::Str(s) = self.advance()?.tok else {
                    unreachable!()
                };
                Ok(vec![self.push_expr(Expr::Str(s))])
            }
            Token::LBrace => Ok(vec![self.table_constructor()?]),
            _ => Err(self.error("function arguments expected")),
        }
    }

    fn table_constructor(&mut self) -> Result<ExprId, SyntaxError> {
        let line = self.tok.line;
        self.expect(Token::LBrace, "{")?;
        let mut fields = Vec::new();
        loop {
            if self.tok.tok == Token::RBrace {
                break;
            }
            if self.tok.tok == Token::LBracket {
                self.advance()?;
                let key = self.expr()?;
                self.expect(Token::RBracket, "]")?;
                self.expect(Token::Assign, "=")?;
                let value = self.expr()?;
                fields.push(TableField::Keyed(key, value));
            } else if matches!(self.tok.tok, Token::Name(_)) && *self.peek()? == Token::Assign {
                let name = self.expect_name()?;
                self.advance()?; // '='
                let value = self.expr()?;
                fields.push(TableField::Named(name, value));
            } else {
                fields.push(TableField::Item(self.expr()?));
            }
            if !(self.accept(Token::Comma)? || self.accept(Token::Semi)?) {
                break;
            }
        }
        self.expect_match(Token::RBrace, "}", "{", line)?;
        Ok(self.push_expr(Expr::Table { fields, line }))
    }

    // ---- functions ----

    fn func_body(&mut self, line: u32) -> Result<FuncBody, SyntaxError> {
        self.expect(Token::LParen, "(")?;
        self.func_local_count.push((0, line, 0));
        self.enter_fn_51(line);
        let mut params = Vec::new();
        let mut vararg = Vararg::None;
        if self.tok.tok != Token::RParen {
            loop {
                match &self.tok.tok {
                    Token::Ellipsis => {
                        self.advance()?;
                        vararg = if self.version.has_named_vararg()
                            && matches!(self.tok.tok, Token::Name(_))
                        {
                            Vararg::Named(self.expect_name()?)
                        } else {
                            Vararg::Anonymous
                        };
                        if let Vararg::Named(ref n) = vararg {
                            self.new_local()?;
                            self.add_local_51(&n.text);
                        }
                        break;
                    }
                    Token::Name(_) => {
                        let p = self.expect_name()?;
                        self.new_local()?;
                        self.add_local_51(&p.text);
                        params.push(p);
                    }
                    _ => return Err(self.error("<name> or '...' expected")),
                }
                if !self.accept(Token::Comma)? {
                    break;
                }
            }
        }
        self.activate_locals()?;
        self.goto_step(|g| {
            g.enter_function();
            for p in &params {
                g.declare(&p.text);
            }
            Ok(())
        })?;
        self.expect(Token::RParen, ")")?;
        self.funcs.push(FnFlow {
            vararg: !matches!(vararg, Vararg::None),
            loops: 0,
        });
        let block = self.block()?;
        let end_line = self.tok.line; // the `end` token's line, before consuming
        self.expect_match(Token::End, "end", "function", line)?;
        self.close_function()?;
        self.func_local_count.pop();
        self.leave_fn_51();
        Ok(FuncBody {
            params,
            vararg,
            block,
            line,
            end_line,
        })
    }

    fn track_uv_51(&self) -> bool {
        !self.upval_chain_51.is_empty()
    }

    fn add_local_51(&mut self, name: &str) {
        if self.track_uv_51() {
            self.upval_chain_51
                .last_mut()
                .expect("fn ctx")
                .locals
                .push(name.into());
        }
    }

    fn snap_locals_51(&self) -> usize {
        if self.track_uv_51() {
            self.upval_chain_51.last().expect("fn ctx").locals.len()
        } else {
            0
        }
    }

    fn restore_locals_51(&mut self, snap: usize) {
        if self.track_uv_51() {
            self.upval_chain_51
                .last_mut()
                .expect("fn ctx")
                .locals
                .truncate(snap);
        }
    }

    fn enter_fn_51(&mut self, line_defined: u32) {
        if self.track_uv_51() {
            self.upval_chain_51.push(FnUvSlot {
                line_defined,
                ..Default::default()
            });
        }
    }

    fn leave_fn_51(&mut self) {
        if self.track_uv_51() {
            self.upval_chain_51.pop();
        }
    }

    /// PUC 5.1 `singlevaraux`-equivalent: resolve `name` against the current
    /// nested-function stack of declared locals, accumulating an upvalue entry
    /// in every intermediate function between the referencing site and the
    /// owning scope. Returns PUC 5.1's "has more than 60 upvalues" error the
    /// moment a link's upvalue set crosses 60. No-op for non-5.1 dialects.
    fn ident_lookup_51(&mut self, name: &str) -> Result<(), SyntaxError> {
        if !self.track_uv_51() {
            return Ok(());
        }
        const MAXUPVAL: usize = 60;
        let n = self.upval_chain_51.len();
        let mut owner: Option<usize> = None;
        for k in (0..n).rev() {
            if self.upval_chain_51[k]
                .locals
                .iter()
                .any(|s| s.as_ref() == name)
            {
                owner = Some(k);
                break;
            }
        }
        let Some(owner_idx) = owner else {
            return Ok(());
        };
        if owner_idx + 1 == n {
            return Ok(());
        }
        for k in (owner_idx + 1)..n {
            let inserted = self.upval_chain_51[k].upvalues.insert(name.into());
            if inserted && self.upval_chain_51[k].upvalues.len() > MAXUPVAL {
                let line_defined = self.upval_chain_51[k].line_defined;
                let where_ = if k == 0 {
                    "main function".to_string()
                } else {
                    format!("function at line {line_defined}")
                };
                // 5.1 `errorlimit`: "<where> has more than <limit> <what>"
                return Err(SyntaxError {
                    line: self.tok.line,
                    msg: format!("{where_} has more than {MAXUPVAL} upvalues").into_bytes(),
                });
            }
        }
        Ok(())
    }

    /// PUC `new_localvar`, right after a local's name is read: up to 5.4
    /// the local cap counts declared-but-pending names too, and the error
    /// points at the token after the name (5.1 words it differently and
    /// shows no token).
    fn new_local(&mut self) -> Result<(), SyntaxError> {
        let &(active, line_defined, pending) = self.func_local_count.last().expect("func ctx");
        if self.version <= LuaVersion::Lua54 && active + pending + 1 > MAXVARS {
            return Err(if self.version <= LuaVersion::Lua51 {
                let what = if self.func_local_count.len() == 1 {
                    "main function".to_string()
                } else {
                    format!("function at line {line_defined}")
                };
                self.plain_error(format!("{what} has more than {MAXVARS} local variables"))
            } else {
                self.local_limit_error()
            });
        }
        self.func_local_count.last_mut().expect("func ctx").2 += 1;
        Ok(())
    }

    /// PUC `adjustlocalvars`: the pending locals come into scope. 5.5 checks
    /// the cap here instead of at declaration.
    fn activate_locals(&mut self) -> Result<(), SyntaxError> {
        let (active, _, pending) = *self.func_local_count.last().expect("func ctx");
        if self.version >= LuaVersion::Lua55 && active + pending > MAXVARS {
            return Err(self.local_limit_error());
        }
        let slot = self.func_local_count.last_mut().expect("func ctx");
        slot.0 += pending;
        slot.2 = 0;
        Ok(())
    }

    fn local_limit_error(&self) -> SyntaxError {
        self.error(format!(
            "too many local variables (limit is {MAXVARS}) in {}",
            self.where_()
        ))
    }
}