module parser

import os
import strings
import v3.flat
import v3.pref
import v3.scanner
import v3.token

// C.open declares the C open symbol used by parser.
fn C.open(charptr, int, int) int

// C.read declares the C read symbol used by parser.
fn C.read(int, voidptr, int) int

// C.close declares the C close symbol used by parser.
fn C.close(int) int

// C.malloc declares the C malloc symbol used by parser.
fn C.malloc(int) &u8

const max_source_file_size = 8388608

// Parser represents parser data used by parser.
pub struct Parser {
    prefs &pref.Preferences
mut:
    s                scanner.Scanner
    tok              token.Token
    lit              string
    tok_pos          int
    prev_tok         token.Token
    peek_tok         token.Token = .eof
    peek_lit         string
    peek_pos         int
    has_peek         bool
    cur_file         string
    cur_module       string
    cur_fn           string
    pending_flag     bool
    pending_params   bool
    pending_export   string
    skip_next_decl   bool
    disable_fn_body  bool
    in_for_container bool
pub mut:
    a              &flat.FlatAst = unsafe { nil }
    parsed_v_files int
}

// new creates a Parser value for parser.
pub fn Parser.new(prefs &pref.Preferences) &Parser {
    return &Parser{
        prefs: unsafe { prefs }
        s:     scanner.new_scanner(prefs, .normal)
        a:     &flat.FlatAst{
            nodes:           []flat.Node{cap: 256}
            children:        []flat.NodeId{cap: 512}
            disabled_fns:    map[string]bool{}
            export_fn_names: map[string]string{}
        }
    }
}

// parse_file reads parse file input for parser.
pub fn (mut p Parser) parse_file(path string) &flat.FlatAst {
    p.parse_into(path)
    return p.a
}

// parse_files reads parse files input for parser.
pub fn (mut p Parser) parse_files(paths []string) &flat.FlatAst {
    for path in paths {
        p.parse_into(path)
    }
    return p.a
}

// parse_into reads parse into input for parser.
pub fn (mut p Parser) parse_into(path string) {
    p.cur_file = path
    p.cur_module = ''
    p.cur_fn = ''
    p.pending_flag = false
    p.pending_params = false
    p.pending_export = ''
    p.skip_next_decl = false
    p.disable_fn_body = false
    p.in_for_container = false
    // File marker before content so import resolver can track source files
    p.a.add_node(flat.Node{
        kind:  .file
        value: path
    })
    src := read_source_file_raw(path)
    if src.len == 0 {
        // An empty but existing `.v` file is valid (declares nothing); only a
        // genuine read failure (missing file) is an error worth reporting.
        if !os.exists(path) {
            eprintln('error reading ${path}')
        }
        return
    }
    if path.ends_with('.v') {
        p.parsed_v_files++
    }
    mut file_set := token.FileSet.new()
    file := file_set.add_file(path, -1, src.len)
    p.s.init(file, src)
    p.next()

    mut ids := []flat.NodeId{}
    for p.tok != .eof {
        if p.tok == .semicolon {
            p.next()
            continue
        }
        if p.tok == .key_module {
            p.next()
            p.cur_module = p.lit
            mod_id := p.a.add_node(flat.Node{
                kind:  .module_decl
                value: p.lit
            })
            ids << mod_id
            p.next()
            if p.tok == .semicolon || p.lit == '' {
                p.next()
            }
            continue
        }
        id := p.top_level_stmt()
        if int(id) >= 0 {
            ids << id
        }
    }
    start := p.add_children(ids)
    p.a.add_node(flat.Node{
        kind:           .file
        value:          path
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

// read_source_file_raw reads read source file raw input for parser.
fn read_source_file_raw(path string) string {
    cpath := cstring_from_vstring(path)
    fd := C.open(cpath, 0, 0)
    if fd < 0 {
        return ''
    }
    size := os.file_size(path)
    if size == 0 {
        C.close(fd)
        return ''
    }
    expected := if size > max_source_file_size { max_source_file_size } else { int(size) }
    buf := C.malloc(expected + 1)
    mut total := 0
    for total < expected {
        nread := C.read(fd, unsafe { buf + total }, expected - total)
        if nread <= 0 {
            break
        }
        total += nread
    }
    C.close(fd)
    if total <= 0 {
        return ''
    }
    unsafe {
        return tos(buf, total)
    }
}

// cstring_from_vstring converts cstring from vstring data for parser.
fn cstring_from_vstring(s string) &u8 {
    buf := C.malloc(s.len + 1)
    unsafe {
        for i in 0 .. s.len {
            buf[i] = s[i]
        }
        buf[s.len] = 0
    }
    return buf
}

// vmod_root_for_file supports vmod root for file handling for parser.
fn vmod_root_for_file(path string) string {
    mut dir := if path.len > 0 { os.dir(path) } else { os.getwd() }
    if dir.len == 0 {
        dir = os.getwd()
    }
    original_dir := dir
    for {
        if os.exists(os.join_path(dir, 'v.mod')) {
            return dir
        }
        parent := os.dir(dir)
        if parent == dir || parent.len == 0 {
            return original_dir
        }
        dir = parent
    }
    return dir
}

// next supports next handling for Parser.
fn (mut p Parser) next() {
    p.prev_tok = p.tok
    if p.has_peek {
        p.tok = p.peek_tok
        p.lit = p.peek_lit
        p.tok_pos = p.peek_pos
        p.has_peek = false
        return
    }
    p.tok = p.s.scan()
    p.lit = p.s.lit
    p.tok_pos = p.s.pos
    for p.tok == .comment {
        p.tok = p.s.scan()
        p.lit = p.s.lit
        p.tok_pos = p.s.pos
    }
}

// peek supports peek handling for Parser.
fn (mut p Parser) peek() token.Token {
    if !p.has_peek {
        p.peek_tok = p.s.scan()
        p.peek_lit = p.s.lit
        p.peek_pos = p.s.pos
        for p.peek_tok == .comment {
            p.peek_tok = p.s.scan()
            p.peek_lit = p.s.lit
            p.peek_pos = p.s.pos
        }
        p.has_peek = true
    }
    return p.peek_tok
}

// peek_is supports peek is handling for Parser.
fn (mut p Parser) peek_is(tok token.Token) bool {
    return p.peek() == tok
}

fn (mut p Parser) check(expected token.Token) {
    if p.tok == expected {
        p.next()
    }
}

fn (mut p Parser) expect(expected token.Token) string {
    lit := p.lit
    if p.tok != expected {
        eprintln('expected ${expected}, got ${p.tok} "${p.lit}"')
    }
    p.next()
    return lit
}

fn (mut p Parser) expect_name() string {
    name := p.lit
    if p.tok != .name && p.lit.len == 0 {
        eprintln('expected name, got ${p.tok} "${p.lit}"')
    }
    p.next()
    return name
}

fn (mut p Parser) expect_name_or_keyword() string {
    name := p.lit
    p.next()
    return name
}

fn token_id_is_infix(tv int) bool {
    return tv == 0 || tv == 1 || tv == 3 || tv == 13 || tv == 20 || tv == 21 || tv == 22 || tv == 44
        || tv == 46 || tv == 74 || tv == 75 || tv == 77 || tv == 80 || tv == 81 || tv == 83
        || tv == 85 || tv == 88 || tv == 90 || tv == 91 || tv == 94 || tv == 95 || tv == 99
        || tv == 101 || tv == 109
}

fn token_is_infix(tok token.Token) bool {
    return token_id_is_infix(int(tok))
}

fn token_id_is_postfix(tv int) bool {
    return tv == 11 || tv == 24
}

fn token_is_postfix(tok token.Token) bool {
    return token_id_is_postfix(int(tok))
}

fn token_id_is_assignment(tv int) bool {
    return tv == 2 || tv == 4 || tv == 12 || tv == 14 || tv == 76 || tv == 82 || tv == 84
        || tv == 86 || tv == 93 || tv == 96 || tv == 100 || tv == 102 || tv == 110
}

fn token_is_assignment(tok token.Token) bool {
    return token_id_is_assignment(int(tok))
}

fn token_id_left_binding_power(tv int) token.BindingPower {
    if tv == 77 {
        return token.BindingPower.logical_or
    }
    if tv == 1 {
        return token.BindingPower.logical_and
    }
    if tv == 20 || tv == 88 || tv == 80 || tv == 74 || tv == 22 || tv == 21 || tv == 44 || tv == 90
        || tv == 46 || tv == 91 {
        return token.BindingPower.compare
    }
    if tv == 94 {
        return token.BindingPower.bit_or
    }
    if tv == 109 {
        return token.BindingPower.bit_xor
    }
    if tv == 75 || tv == 99 || tv == 101 {
        return token.BindingPower.shift
    }
    if tv == 95 || tv == 81 {
        return token.BindingPower.add
    }
    if tv == 85 || tv == 13 || tv == 83 || tv == 0 {
        return token.BindingPower.product
    }
    return token.BindingPower.lowest
}

fn token_left_binding_power(tok token.Token) token.BindingPower {
    return token_id_left_binding_power(int(tok))
}

fn token_id_right_binding_power(tv int) token.BindingPower {
    bp := token_id_left_binding_power(tv)
    if bp == .logical_or {
        return token.BindingPower.logical_and
    }
    if bp == .logical_and {
        return token.BindingPower.compare
    }
    if bp == .compare {
        return token.BindingPower.bit_or
    }
    if bp == .bit_or {
        return token.BindingPower.bit_xor
    }
    if bp == .bit_xor {
        return token.BindingPower.shift
    }
    if bp == .shift {
        return token.BindingPower.add
    }
    if bp == .add {
        return token.BindingPower.product
    }
    if bp == .product {
        return token.BindingPower.highest
    }
    return token.BindingPower.lowest
}

fn token_right_binding_power(tok token.Token) token.BindingPower {
    return token_id_right_binding_power(int(tok))
}

fn token_id_to_op(tv int) flat.Op {
    if tv == 95 {
        return flat.Op.plus
    }
    if tv == 81 {
        return flat.Op.minus
    }
    if tv == 85 {
        return flat.Op.mul
    }
    if tv == 13 {
        return flat.Op.div
    }
    if tv == 83 {
        return flat.Op.mod
    }
    if tv == 20 {
        return flat.Op.eq
    }
    if tv == 88 {
        return flat.Op.ne
    }
    if tv == 80 {
        return flat.Op.lt
    }
    if tv == 22 {
        return flat.Op.gt
    }
    if tv == 74 {
        return flat.Op.le
    }
    if tv == 21 {
        return flat.Op.ge
    }
    if tv == 0 {
        return flat.Op.amp
    }
    if tv == 94 {
        return flat.Op.pipe
    }
    if tv == 109 {
        return flat.Op.xor
    }
    if tv == 75 {
        return flat.Op.left_shift
    }
    if tv == 99 {
        return flat.Op.right_shift
    }
    if tv == 101 {
        return flat.Op.right_shift_unsigned
    }
    if tv == 1 {
        return flat.Op.logical_and
    }
    if tv == 77 {
        return flat.Op.logical_or
    }
    if tv == 89 {
        return flat.Op.not
    }
    if tv == 6 {
        return flat.Op.bit_not
    }
    if tv == 4 {
        return flat.Op.assign
    }
    if tv == 96 {
        return flat.Op.plus_assign
    }
    if tv == 82 {
        return flat.Op.minus_assign
    }
    if tv == 86 {
        return flat.Op.mul_assign
    }
    if tv == 14 {
        return flat.Op.div_assign
    }
    if tv == 84 {
        return flat.Op.mod_assign
    }
    if tv == 2 {
        return flat.Op.amp_assign
    }
    if tv == 93 {
        return flat.Op.pipe_assign
    }
    if tv == 110 {
        return flat.Op.xor_assign
    }
    if tv == 76 {
        return flat.Op.left_shift_assign
    }
    if tv == 100 {
        return flat.Op.right_shift_assign
    }
    if tv == 102 {
        return flat.Op.right_shift_unsigned_assign
    }
    if tv == 24 {
        return flat.Op.inc
    }
    if tv == 11 {
        return flat.Op.dec
    }
    if tv == 16 {
        return flat.Op.dot
    }
    if tv == 3 {
        return flat.Op.arrow
    }
    return flat.Op.none
}

fn (p &Parser) tok_can_be_decl_name() bool {
    return p.tok == .name || (int(p.tok) >= int(token.Token.key_as)
        && int(p.tok) <= int(token.Token.key_unsafe))
}

fn (mut p Parser) add_children(ids []flat.NodeId) int {
    start := p.a.children.len
    for id in ids {
        p.a.children << id
    }
    return start
}

fn (mut p Parser) add_child(id flat.NodeId) int {
    start := p.a.children.len
    p.a.children << id
    return start
}

fn (mut p Parser) add_children2(a flat.NodeId, b flat.NodeId) int {
    start := p.a.children.len
    p.a.children << a
    p.a.children << b
    return start
}

// ==================== top-level ====================

fn (mut p Parser) top_level_stmt() flat.NodeId {
    match p.tok {
        .key_fn {
            return p.fn_decl()
        }
        .key_pub {
            p.next()
            return p.top_level_stmt()
        }
        .key_struct, .key_union {
            return p.struct_decl()
        }
        .key_global {
            return p.global_decl()
        }
        .key_const {
            return p.const_decl()
        }
        .key_enum {
            return p.enum_decl()
        }
        .key_type {
            return p.type_decl()
        }
        .key_interface {
            return p.interface_decl()
        }
        .key_import {
            return p.import_stmt()
        }
        .key_module {
            return p.module_stmt()
        }
        .attribute {
            p.skip_attrs()
            return p.parse_decl_after_attrs()
        }
        .lsbr {
            p.skip_attrs()
            return p.parse_decl_after_attrs()
        }
        .dollar {
            return p.parse_top_level_comptime_if()
        }
        .hash {
            return p.directive()
        }
        .key_assert {
            return p.assert_stmt()
        }
        .semicolon {
            p.next()
            return flat.empty_node
        }
        else {
            return p.stmt()
        }
    }
}

// parse_decl_after_attrs parses the declaration that follows an attribute group.
// A newline after `@[...]` yields an auto-inserted semicolon, which is consumed
// here so the declaration itself is parsed next. When the attribute group is a
// disabled `@[if flag ?]` (skip_next_decl set), functions are emitted as no-op
// stubs (empty body): the signature must remain so call sites still type-check
// and link, but the body is elided. Other disabled declarations are skipped.
fn (mut p Parser) parse_decl_after_attrs() flat.NodeId {
    p.consume_decl_prefix_after_attrs()
    if p.skip_next_decl {
        p.pending_params = false
        p.skip_next_decl = false
        if p.cur_decl_is_fn() {
            p.disable_fn_body = true
            res := p.top_level_stmt()
            p.disable_fn_body = false
            p.skip_next_decl = false
            return res
        }
        p.skip_top_level_stmt()
        p.skip_next_decl = false
        p.pending_export = ''
        return flat.empty_node
    }
    res := p.top_level_stmt()
    p.pending_params = false
    p.pending_export = ''
    return res
}

fn (mut p Parser) consume_decl_prefix_after_attrs() {
    for p.tok == .semicolon || p.tok == .attribute || p.tok == .lsbr {
        if p.tok == .semicolon {
            p.next()
            continue
        }
        p.skip_attrs()
    }
}

fn (mut p Parser) cur_decl_is_fn() bool {
    if p.tok == .key_fn {
        return true
    }
    return p.tok == .key_pub && p.peek() == .key_fn
}

fn (mut p Parser) fn_decl() flat.NodeId {
    p.check(.key_fn)
    mut name := ''
    mut receiver_name := ''
    mut receiver_type := ''
    mut receiver_is_mut := false
    mut is_method := false

    // method receiver: fn (mut r Type) name()
    if p.tok == .lpar {
        is_method = true
        p.next()
        mut is_mut := false
        if p.tok == .key_mut || p.tok == .key_shared {
            is_mut = p.tok == .key_mut
            receiver_is_mut = is_mut
            p.next()
        }
        receiver_name = p.expect_name()
        receiver_type = p.parse_type_name()
        if is_mut {
            receiver_type = '&' + receiver_type
        }
        p.check(.rpar)

        // operator overload: fn (r Type) + (other Type) RetType { }
        if p.tok != .name && p.tok != .eof {
            if p.tok.is_overloadable() {
                op_name := overload_token_name(p.tok)
                p.next()
                return p.fn_operator_overload(receiver_name, receiver_type, receiver_is_mut,
                    op_name)
            }
        }
    }

    // function name
    if p.tok_can_be_decl_name() {
        name = p.expect_name_or_keyword()
        if p.tok == .dot {
            p.next()
            if name == 'C' || name == 'JS' {
                // C.func or JS.func
                name = p.expect_name_or_keyword()
                for p.tok == .dot {
                    p.next()
                    name += '.' + p.expect_name_or_keyword()
                }
                if is_method {
                    clean_type := receiver_type.trim_left('&')
                    name = '${clean_type}.${name}'
                }
                return p.fn_decl_body(name, receiver_name, receiver_type, receiver_is_mut,
                    is_method, true)
            }
            // module.func or Type.static_method
            second := p.expect_name_or_keyword()
            if is_method {
                // This shouldn't happen for methods
                name = name + '.' + second
            } else {
                // Static method: Type.name
                receiver_type = name
                name = second
                is_method = true
            }
        }
    }

    if is_method && receiver_type.len > 0 {
        clean_type := receiver_type.trim_left('&')
        name = '${clean_type}.${name}'
    }

    return p.fn_decl_body(name, receiver_name, receiver_type, receiver_is_mut, is_method, false)
}

fn (mut p Parser) fn_operator_overload(receiver_name string, receiver_type string, receiver_is_mut bool, op_name string) flat.NodeId {
    disable_body := p.disable_fn_body
    p.disable_fn_body = false
    // parse parameter
    p.check(.lpar)
    mut param_ids := []flat.NodeId{}
    // receiver
    param_ids << p.a.add_node(flat.Node{
        kind:  .param
        value: receiver_name
        typ:   receiver_type
        op:    if receiver_is_mut { .amp } else { .none }
    })
    // operator param
    if p.tok == .key_mut {
        p.next()
    }
    for p.tok != .rpar && p.tok != .eof {
        start_offset := p.s.offset
        param_ids << p.parse_param_group(false)
        if p.s.offset == start_offset && p.tok != .rpar && p.tok != .eof {
            p.next()
        }
    }
    p.check(.rpar)

    mut ret_type := 'void'
    if p.tok != .lcbr && p.tok != .semicolon && p.tok != .eof {
        ret_type = p.parse_type_name()
    }

    clean_type := receiver_type.trim_left('&')
    name := '${clean_type}.${op_name}'

    mut body_ids := []flat.NodeId{}
    if p.tok == .lcbr {
        prev_fn := p.cur_fn
        p.cur_fn = name
        if disable_body {
            p.mark_disabled_fn(name)
            p.skip_block()
        } else {
            p.check(.lcbr)
            for p.tok != .rcbr && p.tok != .eof {
                id := p.stmt()
                if int(id) >= 0 {
                    body_ids << id
                }
            }
            p.check(.rcbr)
        }
        p.cur_fn = prev_fn
    }

    mut all_ids := []flat.NodeId{cap: param_ids.len + body_ids.len}
    for id in param_ids {
        all_ids << id
    }
    for id in body_ids {
        all_ids << id
    }
    start := p.add_children(all_ids)
    id := p.a.add_node(flat.Node{
        kind:           .fn_decl
        value:          name
        typ:            ret_type
        children_start: start
        children_count: flat.child_count(all_ids.len)
    })
    p.register_pending_export(name)
    return id
}

fn (mut p Parser) fn_decl_body(name string, receiver_name string, receiver_type string, receiver_is_mut bool, is_method bool, is_c_decl bool) flat.NodeId {
    // Capture & clear here so it applies only to this function (not nested closures
    // or a following declaration), and is cleared even on the extern/no-body path.
    disable_body := p.disable_fn_body
    p.disable_fn_body = false
    // generic params — skip
    mut generic_params := []string{}
    if p.tok == .lsbr {
        generic_params = p.parse_generic_param_names()
    }

    // params
    p.check(.lpar)
    mut param_ids := []flat.NodeId{}
    if is_method && receiver_name.len > 0 {
        param_ids << p.a.add_node(flat.Node{
            kind:  .param
            value: receiver_name
            typ:   receiver_type
            op:    if receiver_is_mut { .amp } else { .none }
        })
    }
    for p.tok != .rpar && p.tok != .eof {
        start_offset := p.s.offset
        param_ids << p.parse_param_group(is_c_decl)
        if p.s.offset == start_offset && p.tok != .rpar && p.tok != .eof {
            p.next()
        }
    }
    p.check(.rpar)

    // return type
    mut ret_type := 'void'
    if p.tok == .name || p.tok == .amp || p.tok == .question || p.tok == .not || p.tok == .lsbr
        || p.tok == .lpar || p.tok == .key_fn || p.tok == .ellipsis {
        ret_type = p.parse_type_name()
    }
    // no body — extern/C declaration
    if p.tok != .lcbr {
        for p.tok == .semicolon {
            p.next()
        }
        start := p.add_children(param_ids)
        id := p.a.add_node(flat.Node{
            kind:           .c_fn_decl
            value:          name
            typ:            ret_type
            generic_params: generic_params
            children_start: start
            children_count: flat.child_count(param_ids.len)
        })
        p.pending_export = ''
        return id
    }

    // body
    mut body_ids := []flat.NodeId{}
    prev_fn := p.cur_fn
    p.cur_fn = name
    // A disabled `@[if flag ?]` function keeps its signature but gets an empty body
    // (a no-op stub), so callers still resolve while the body is compiled out.
    if disable_body {
        p.mark_disabled_fn(name)
        p.skip_block()
    } else {
        p.check(.lcbr)
        for p.tok != .rcbr && p.tok != .eof {
            id := p.stmt()
            if int(id) >= 0 {
                body_ids << id
            }
        }
        p.check(.rcbr)
    }
    p.cur_fn = prev_fn

    mut all_ids := []flat.NodeId{cap: param_ids.len + body_ids.len}
    for id in param_ids {
        all_ids << id
    }
    for id in body_ids {
        all_ids << id
    }
    start := p.add_children(all_ids)
    id := p.a.add_node(flat.Node{
        kind:           .fn_decl
        value:          name
        typ:            ret_type
        generic_params: generic_params
        children_start: start
        children_count: flat.child_count(all_ids.len)
    })
    p.register_pending_export(name)
    return id
}

fn (mut p Parser) mark_disabled_fn(name string) {
    if name.len == 0 {
        return
    }
    if p.cur_module.len > 0 && p.cur_module != 'main' && p.cur_module != 'builtin' {
        qname := if name.starts_with('${p.cur_module}.') { name } else { '${p.cur_module}.${name}' }
        p.a.disabled_fns[qname] = true
    }
    p.a.disabled_fns[name] = true
}

fn (mut p Parser) register_pending_export(name string) {
    if p.pending_export.len == 0 || name.len == 0 {
        p.pending_export = ''
        return
    }
    qname := if p.cur_module.len > 0 && p.cur_module != 'main' && p.cur_module != 'builtin'
        && !name.starts_with('${p.cur_module}.') {
        '${p.cur_module}.${name}'
    } else {
        name
    }
    if name in p.a.disabled_fns || qname in p.a.disabled_fns {
        p.pending_export = ''
        return
    }
    p.a.export_fn_names[qname] = p.pending_export
    p.pending_export = ''
}

fn (mut p Parser) parse_param_group(is_c_decl bool) []flat.NodeId {
    mut ids := []flat.NodeId{}
    mut names := []string{}
    mut is_mut := false
    if p.tok == .key_mut {
        is_mut = true
        p.next()
    }
    if p.tok == .key_shared {
        p.next()
    }
    // variadic ...Type (no param name)
    if p.tok == .ellipsis {
        typ := p.parse_type_name()
        ids << p.a.add_node(flat.Node{
            kind:  .param
            value: ''
            typ:   typ
            op:    if is_mut { .amp } else { .none }
        })
        if p.tok == .comma {
            p.next()
        }
        return ids
    }
    if is_c_decl && p.c_anon_param_starts_type() {
        mut typ := p.parse_type_name()
        if is_mut && !typ.starts_with('&') {
            typ = '&' + typ
        }
        ids << p.a.add_node(flat.Node{
            kind:  .param
            value: ''
            typ:   typ
            op:    if is_mut { .amp } else { .none }
        })
        if p.tok == .comma {
            p.next()
        }
        return ids
    }
    names << p.lit
    p.next()
    for p.tok == .comma {
        p.next()
        if p.tok == .key_mut {
            p.next()
        }
        if p.tok == .name {
            names << p.lit
            p.next()
        }
    }
    mut typ := p.parse_type_name()
    if is_mut && !typ.starts_with('&') {
        typ = '&' + typ
    }
    for name in names {
        ids << p.a.add_node(flat.Node{
            kind:  .param
            value: name
            typ:   typ
            op:    if is_mut { .amp } else { .none }
        })
    }
    if p.tok == .comma {
        p.next()
    }
    return ids
}

fn (mut p Parser) c_anon_param_starts_type() bool {
    if p.tok in [.amp, .and, .question, .not, .lsbr, .lpar, .key_fn, .key_atomic, .key_struct] {
        return true
    }
    if p.tok == .name {
        if p.lit == '&' {
            return true
        }
        pk := p.peek()
        if pk == .dot || pk == .rpar || pk == .eof {
            return true
        }
        if pk == .comma && (is_builtin_type(p.lit) || is_c_anon_simple_type_name(p.lit)) {
            return true
        }
    }
    return false
}

fn (mut p Parser) struct_decl() flat.NodeId {
    is_union := p.tok == .key_union
    is_params := p.pending_params
    p.pending_params = false
    p.next() // skip 'struct' or 'union'
    mut name := p.expect(.name)
    if (name == 'C' || name == 'JS') && p.tok == .dot {
        for p.tok == .dot {
            p.next()
            name += '.' + p.expect_name_or_keyword()
        }
    }
    // generic params — skip
    mut is_generic := false
    mut generic_params := []string{}
    if p.tok == .lsbr {
        is_generic = true
        generic_params = p.parse_generic_param_names()
    }
    // implements clause
    if p.tok == .name && p.lit == 'implements' {
        p.next()
        p.parse_type_name()
        for p.tok == .comma {
            p.next()
            p.parse_type_name()
        }
    }
    // no body (C struct forward decl)
    if p.tok != .lcbr {
        if p.tok == .semicolon {
            p.next()
        }
        return p.a.add_node(flat.Node{
            kind:           .struct_decl
            value:          name
            typ:            struct_decl_typ(is_union, is_generic, is_params)
            generic_params: generic_params
        })
    }
    p.check(.lcbr)
    mut ids := []flat.NodeId{}
    for p.tok != .rcbr && p.tok != .eof {
        // access modifiers
        if p.tok == .key_pub {
            p.next()
            if p.tok == .key_mut {
                p.next()
            }
            if p.tok == .name && p.lit == 'module_mut' {
                p.next()
            }
            if p.tok == .colon {
                p.next()
            }
            continue
        }
        if p.tok == .key_mut {
            p.next()
            if p.tok == .colon {
                p.next()
            }
            continue
        }
        if p.tok == .semicolon {
            p.next()
            continue
        }
        // comptime $if in struct fields
        if p.tok == .dollar {
            id := p.parse_comptime_if()
            if int(id) >= 0 {
                ids << id
            }
            continue
        }
        // attributes — skip
        if p.tok == .attribute {
            p.skip_attrs()
            continue
        }
        // field: name type [= default] [@[attrs]]
        if p.tok == .name || p.tok.is_keyword() {
            field_name := p.expect_name_or_keyword()
            if p.tok == .dot {
                p.next()
                second := p.expect_name_or_keyword()
                full_type := '${field_name}.${second}'
                field_type := full_type + p.parse_type_generic_suffix()
                ids << p.a.add_node(flat.Node{
                    kind:  .field_decl
                    value: full_type
                    typ:   field_type
                })
                if p.tok == .semicolon {
                    p.next()
                }
                continue
            }
            // embedded struct (type on its own line, followed by semicolon)
            if p.tok == .semicolon || p.tok == .rcbr {
                ids << p.a.add_node(flat.Node{
                    kind:  .field_decl
                    value: field_name
                    typ:   field_name
                })
                if p.tok == .semicolon {
                    p.next()
                }
                continue
            }
            // grouped fields: x, y int
            if p.tok == .comma {
                mut names := []string{}
                names << field_name
                for p.tok == .comma {
                    p.next()
                    names << p.expect_name_or_keyword()
                }
                field_type := p.parse_type_name()
                for n in names {
                    ids << p.a.add_node(flat.Node{
                        kind:  .field_decl
                        value: n
                        typ:   field_type
                    })
                }
                if p.tok == .semicolon {
                    p.next()
                }
                continue
            }
            // For embedded structs followed by access modifier or another field,
            // check if the next token could be a type
            field_type := p.parse_type_name()
            mut default_id := flat.empty_node
            // default value
            if p.tok == .assign {
                p.next()
                default_id = p.expr(.lowest)
            }
            mut children_start := 0
            mut children_count := 0
            if int(default_id) >= 0 {
                children_start = p.add_child(default_id)
                children_count = 1
            }
            // trailing field attributes — skip
            if p.tok == .attribute || p.tok == .lsbr {
                p.skip_attrs()
            }
            ids << p.a.add_node(flat.Node{
                kind:           .field_decl
                value:          field_name
                typ:            field_type
                children_start: children_start
                children_count: flat.child_count(children_count)
            })
            if p.tok == .semicolon {
                p.next()
            }
        } else {
            p.next()
        }
    }
    p.check(.rcbr)
    p.pending_params = false
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .struct_decl
        value:          name
        typ:            struct_decl_typ(is_union, is_generic, is_params)
        generic_params: generic_params
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn struct_decl_typ(is_union bool, is_generic bool, is_params bool) string {
    mut parts := []string{}
    if is_union {
        parts << 'union'
    }
    if is_generic {
        parts << 'generic'
    }
    if is_params {
        parts << 'params'
    }
    return parts.join(',')
}

fn (mut p Parser) global_decl() flat.NodeId {
    p.next() // skip '__global'
    is_grouped := p.tok == .lpar
    if is_grouped {
        p.next()
    }
    mut ids := []flat.NodeId{}
    for {
        if p.tok == .semicolon {
            p.next()
            if !is_grouped {
                break
            }
            if p.tok == .rpar {
                p.next()
                if p.tok == .semicolon {
                    p.next()
                }
                break
            }
            continue
        }
        if p.tok == .key_pub {
            p.next()
        }
        if p.tok == .key_mut {
            p.next()
        }
        if p.tok == .name || p.tok.is_keyword() {
            gname := p.expect_name_or_keyword()
            // handle qualified names: C.errno
            mut full_name := gname
            for p.tok == .dot {
                p.next()
                full_name += '.' + p.expect_name_or_keyword()
            }
            if p.tok == .assign {
                // global with initializer: __global name = expr
                p.next()
                val_id := p.expr(.lowest)
                vstart := p.add_child(val_id)
                ids << p.a.add_node(flat.Node{
                    kind:           .field_decl
                    value:          full_name
                    typ:            ''
                    children_start: vstart
                    children_count: 1
                })
            } else {
                gtype := p.parse_type_name()
                ids << p.a.add_node(flat.Node{
                    kind:  .field_decl
                    value: full_name
                    typ:   gtype
                })
            }
            if p.tok == .semicolon {
                p.next()
            }
            if !is_grouped {
                break
            }
            if is_grouped && p.tok == .rpar {
                p.next()
                if p.tok == .semicolon {
                    p.next()
                }
                break
            }
        } else if p.tok == .rpar {
            p.next()
            if p.tok == .semicolon {
                p.next()
            }
            break
        } else {
            p.next()
            if !is_grouped {
                break
            }
        }
    }
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .global_decl
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) const_decl() flat.NodeId {
    p.next() // skip 'const'
    is_grouped := p.tok == .lpar
    if is_grouped {
        p.next()
    }
    mut ids := []flat.NodeId{}
    for {
        if p.tok == .semicolon {
            p.next()
            if !is_grouped {
                break
            }
            if p.tok == .rpar {
                p.next()
                if p.tok == .semicolon {
                    p.next()
                }
                break
            }
            continue
        }
        if p.tok == .name {
            cname := p.expect_name()
            mut full_name := cname
            // C.NAME
            if full_name == 'C' && p.tok == .dot {
                p.next()
                full_name = 'C.' + p.expect_name_or_keyword()
            }
            if p.tok == .assign {
                p.next()
                val_id := p.expr(.lowest)
                vstart := p.add_child(val_id)
                ids << p.a.add_node(flat.Node{
                    kind:           .const_field
                    value:          full_name
                    children_start: vstart
                    children_count: 1
                })
            } else {
                // const with type only (header files)
                ctype := p.parse_type_name()
                ids << p.a.add_node(flat.Node{
                    kind:  .const_field
                    value: full_name
                    typ:   ctype
                })
            }
            if p.tok == .semicolon {
                p.next()
            }
            if !is_grouped {
                break
            }
            if is_grouped && p.tok == .rpar {
                p.next()
                if p.tok == .semicolon {
                    p.next()
                }
                break
            }
        } else if p.tok == .rpar {
            p.next()
            if p.tok == .semicolon {
                p.next()
            }
            break
        } else {
            p.next()
            if !is_grouped {
                break
            }
        }
    }
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .const_decl
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) enum_decl() flat.NodeId {
    p.next() // skip 'enum'
    name := p.expect(.name)
    // `as` type
    if p.tok == .key_as {
        p.next()
        p.parse_type_name()
    }
    p.check(.lcbr)
    mut ids := []flat.NodeId{}
    for p.tok != .rcbr && p.tok != .eof {
        if p.tok == .semicolon {
            p.next()
            continue
        }
        // attributes on enum fields — skip
        if p.tok == .attribute || p.tok == .lsbr {
            p.skip_attrs()
            continue
        }
        field_name := p.expect_name_or_keyword()
        if p.tok == .assign {
            p.next()
            val_id := p.expr(.lowest)
            vstart := p.add_child(val_id)
            ids << p.a.add_node(flat.Node{
                kind:           .enum_field
                value:          field_name
                children_start: vstart
                children_count: 1
            })
        } else {
            ids << p.a.add_node(flat.Node{
                kind:  .enum_field
                value: field_name
            })
        }
        if p.tok == .semicolon {
            p.next()
        }
    }
    p.check(.rcbr)
    start := p.add_children(ids)
    mut typ := ''
    if p.pending_flag {
        typ = 'flag'
        p.pending_flag = false
    }
    return p.a.add_node(flat.Node{
        kind:           .enum_decl
        value:          name
        typ:            typ
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) type_decl() flat.NodeId {
    p.next() // skip 'type'
    // C. or JS. prefix
    if p.tok == .name && (p.lit == 'C' || p.lit == 'JS') {
        p.next()
        if p.tok == .dot {
            p.next()
        }
    }
    name := p.expect_name()
    // generic params
    mut generic_params := []string{}
    if p.tok == .lsbr {
        generic_params = p.parse_generic_param_names()
    }
    p.expect(.assign)
    first_type := p.parse_type_name()
    // check for sum type: type T = A | B | C
    // skip auto-semicolon before pipe
    if p.tok == .pipe || (p.tok == .semicolon && p.peek_is(token.Token.pipe)) {
        mut variants := []flat.NodeId{}
        variants << p.a.add_val(.ident, first_type)
        for p.tok == .pipe || (p.tok == .semicolon && p.peek_is(token.Token.pipe)) {
            if p.tok == .semicolon {
                p.next()
            }
            p.next() // skip |
            variant_type := p.parse_type_name()
            variants << p.a.add_val(.ident, variant_type)
        }
        if p.tok == .semicolon {
            p.next()
        }
        start := p.add_children(variants)
        return p.a.add_node(flat.Node{
            kind:           .type_decl
            value:          name
            generic_params: generic_params
            children_start: start
            children_count: flat.child_count(variants.len)
        })
    }
    if p.tok == .semicolon {
        p.next()
    }
    // type alias
    return p.a.add_node(flat.Node{
        kind:           .type_decl
        value:          name
        typ:            first_type
        generic_params: generic_params
    })
}

fn (mut p Parser) interface_decl() flat.NodeId {
    p.next() // skip 'interface'
    mut name := p.expect(.name)
    for p.tok == .dot {
        p.next()
        name += '.' + p.expect(.name)
    }
    // generic params
    mut generic_params := []string{}
    if p.tok == .lsbr {
        generic_params = p.parse_generic_param_names()
    }
    p.check(.lcbr)
    mut ids := []flat.NodeId{}
    for p.tok != .rcbr && p.tok != .eof {
        if p.tok == .key_mut {
            p.next()
            if p.tok == .colon {
                p.next()
            }
            continue
        }
        if p.tok == .semicolon {
            p.next()
            continue
        }
        field_name := p.expect_name_or_keyword()
        if p.tok == .lpar {
            // method: name(params) ret_type
            p.next() // skip (
            mut params := []flat.NodeId{}
            for p.tok != .rpar && p.tok != .eof {
                if p.tok == .key_mut {
                    p.next()
                }
                // Interface method params may be named (e.g. `seed_data []u32`,
                // `node &ast.Node`) or type-only (`[]u32`). When the current token
                // is a plain identifier and the next token starts a type, that
                // identifier is the param name; consume it first so the array/pointer
                // prefix of the real type is not mis-parsed onto the name
                // (e.g. `seed_data[]`). `map`/`chan` are type heads, not names.
                if p.tok == .name && p.lit != 'map' && p.lit != 'chan' {
                    nt := p.peek()
                    if nt == .name || nt == .amp || nt == .question || nt == .not
                        || nt == .key_fn || nt == .ellipsis
                        || (nt == .lsbr && p.peek_lbr_starts_array_type()) {
                        p.next()
                    }
                }
                ptype := p.parse_type_name()
                params << p.a.add_node(flat.Node{
                    kind: .param
                    typ:  ptype
                })
                if p.tok == .comma {
                    p.next()
                }
            }
            p.check(.rpar) // skip )
            mut ret_type := ''
            if p.tok != .semicolon && p.tok != .rcbr && p.tok != .eof {
                ret_type = p.parse_type_name()
            }
            start := p.add_children(params)
            ids << p.a.add_node(flat.Node{
                kind:           .interface_field
                op:             .dot
                value:          field_name
                typ:            ret_type
                children_start: start
                children_count: flat.child_count(params.len)
            })
        } else if p.tok == .semicolon || p.tok == .rcbr {
            // embedded type or field without explicit type
            ids << p.a.add_node(flat.Node{
                kind:  .interface_field
                value: field_name
            })
        } else {
            // field: name type
            ftype := p.parse_type_name()
            ids << p.a.add_node(flat.Node{
                kind:  .interface_field
                value: field_name
                typ:   ftype
            })
        }
        if p.tok == .semicolon {
            p.next()
        }
    }
    p.check(.rcbr)
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .interface_decl
        value:          name
        generic_params: generic_params
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) import_stmt() flat.NodeId {
    p.next() // skip 'import'
    mut name := p.expect_name()
    mut alias := name
    mut selective_ids := []flat.NodeId{}
    for p.tok == .dot {
        p.next()
        alias = p.expect_name()
        name += '.' + alias
    }
    if p.tok == .key_as {
        p.next()
        alias = p.expect_name()
    }
    // selective import: import mod { sym1, sym2 }
    if p.tok == .lcbr {
        p.next()
        for p.tok != .rcbr && p.tok != .eof {
            sym := p.expect_name_or_keyword()
            selective_ids << p.a.add_node(flat.Node{
                kind:  .ident
                value: sym
            })
            if p.tok == .comma {
                p.next()
            }
        }
        p.check(.rcbr)
    }
    if p.tok == .semicolon {
        p.next()
    }
    return p.a.add_node(flat.Node{
        kind:           .import_decl
        value:          name
        typ:            alias
        children_start: p.add_children(selective_ids)
        children_count: flat.child_count(selective_ids.len)
    })
}

fn (mut p Parser) module_stmt() flat.NodeId {
    p.next() // skip 'module'
    name := p.expect_name()
    if p.tok == .semicolon {
        p.next()
    }
    return p.a.add_node(flat.Node{
        kind:  .module_decl
        value: name
    })
}

fn (mut p Parser) directive() flat.NodeId {
    mut full := p.lit
    p.next() // skip '#' (lit already contains the full line)
    if full.starts_with('#') {
        full = full[1..]
    }
    mut name := full
    mut value := ''
    space_idx := full.index_u8(` `)
    if space_idx > 0 {
        name = full[..space_idx]
        value = full[space_idx + 1..].trim_space()
    }
    if p.tok == .semicolon {
        p.next()
    }
    return p.a.add_node(flat.Node{
        kind:  .directive
        value: name
        typ:   value
    })
}

fn (mut p Parser) skip_attrs() {
    if p.tok == .attribute {
        p.next()
        if p.tok == .key_if {
            p.next()
            mut cond := strings.new_builder(32)
            for p.tok != .rsbr && p.tok != .eof {
                tok_str := p.comptime_cond_token_text()
                if cond.len > 0 && tok_str != '?' {
                    cond.write_string(' ')
                }
                cond.write_string(tok_str)
                p.next()
            }
            if !eval_comptime_cond(p.prefs, cond.str()) {
                p.skip_next_decl = true
            }
        }
        for p.tok != .rsbr && p.tok != .eof {
            if p.tok == .name {
                if p.lit == 'flag' {
                    p.pending_flag = true
                } else if p.lit == 'params' {
                    p.pending_params = true
                } else if p.lit == 'export' {
                    p.try_parse_export_attr()
                    continue
                }
            }
            p.next()
        }
        p.check(.rsbr)
        return
    }
    if p.tok == .lsbr {
        mut depth := 1
        p.next()
        for depth > 0 && p.tok != .eof {
            if depth == 1 && p.tok == .name {
                if p.lit == 'flag' {
                    p.pending_flag = true
                } else if p.lit == 'params' {
                    p.pending_params = true
                } else if p.lit == 'export' {
                    p.try_parse_export_attr()
                    continue
                }
            }
            if p.tok == .lsbr {
                depth++
            } else if p.tok == .rsbr {
                depth--
            }
            p.next()
        }
    }
}

fn (mut p Parser) try_parse_export_attr() {
    p.next()
    if p.tok != .colon {
        return
    }
    p.next()
    if int(p.tok) != int(token.Token.string) {
        return
    }
    p.pending_export = strip_quotes(p.lit)
    p.next()
}

fn (mut p Parser) skip_top_level_stmt() {
    // A newline after the attribute group (`@[if flag ?]`) yields an auto-inserted
    // semicolon before the declaration; skip it (and any further attributes) so the
    // declaration itself — not just the empty statement — is skipped.
    for p.tok == .attribute || p.tok == .lsbr || p.tok == .semicolon {
        if p.tok == .semicolon {
            p.next()
            continue
        }
        p.skip_attrs()
    }
    if p.tok == .key_pub {
        p.next()
    }
    match p.tok {
        .key_fn {
            p.next()
            for p.tok != .lcbr && p.tok != .semicolon && p.tok != .eof {
                p.next()
            }
            if p.tok == .lcbr {
                p.skip_block()
            } else if p.tok == .semicolon {
                p.next()
            }
        }
        .key_struct, .key_union, .key_enum, .key_interface, .key_const, .key_global {
            for p.tok != .lcbr && p.tok != .semicolon && p.tok != .eof {
                p.next()
            }
            if p.tok == .lcbr {
                p.skip_block()
            } else if p.tok == .semicolon {
                p.next()
            }
        }
        else {
            for p.tok != .semicolon && p.tok != .eof {
                p.next()
            }
            if p.tok == .semicolon {
                p.next()
            }
        }
    }
}

fn (mut p Parser) parse_comptime_if() flat.NodeId {
    p.next() // skip $
    if p.tok != .key_if {
        // $for or other comptime — skip
        if p.tok == .key_for {
            p.next()
            for p.tok != .lcbr && p.tok != .eof {
                p.next()
            }
            p.skip_block()
        } else {
            for p.tok != .semicolon && p.tok != .eof {
                p.next()
            }
            if p.tok == .semicolon {
                p.next()
            }
        }
        return flat.empty_node
    }
    p.next() // skip 'if'
    cond := p.parse_comptime_cond()
    if comptime_cond_has_type_test(cond) {
        then_block := p.block_stmt()
        else_block := p.parse_comptime_else()
        return p.comptime_if_node(cond, then_block, else_block)
    }
    taken := eval_comptime_cond(p.prefs, cond)
    if taken {
        result := p.block_stmt()
        p.skip_comptime_else()
        return result
    } else {
        p.skip_block()
        return p.parse_comptime_else()
    }
}

fn (mut p Parser) parse_top_level_comptime_if() flat.NodeId {
    p.next() // skip $
    if p.tok != .key_if {
        // $for or other comptime - skip
        if p.tok == .key_for {
            p.next()
            for p.tok != .lcbr && p.tok != .eof {
                p.next()
            }
            p.skip_block()
        } else {
            for p.tok != .semicolon && p.tok != .eof {
                p.next()
            }
            if p.tok == .semicolon {
                p.next()
            }
        }
        return flat.empty_node
    }
    p.next() // skip 'if'
    cond := p.parse_comptime_cond()
    if comptime_cond_has_type_test(cond) {
        then_block := p.top_level_block_stmt()
        else_block := p.parse_top_level_comptime_else()
        return p.comptime_if_node(cond, then_block, else_block)
    }
    taken := eval_comptime_cond(p.prefs, cond)
    if taken {
        result := p.top_level_block_stmt()
        p.skip_comptime_else()
        return result
    }
    p.skip_block()
    return p.parse_top_level_comptime_else()
}

fn (mut p Parser) comptime_if_node(cond string, then_block flat.NodeId, else_block flat.NodeId) flat.NodeId {
    mut ids := []flat.NodeId{cap: 2}
    if int(then_block) >= 0 {
        ids << then_block
    }
    if int(else_block) >= 0 {
        ids << else_block
    }
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .comptime_if
        value:          cond
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) top_level_block_stmt() flat.NodeId {
    ids := p.parse_top_level_block_body()
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .block
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) parse_top_level_block_body() []flat.NodeId {
    p.check(.lcbr)
    mut ids := []flat.NodeId{}
    for p.tok != .rcbr && p.tok != .eof {
        if p.tok == .semicolon {
            p.next()
            continue
        }
        id := p.top_level_stmt()
        if int(id) >= 0 {
            ids << id
        }
    }
    p.check(.rcbr)
    return ids
}

fn (mut p Parser) parse_comptime_cond() string {
    mut cond := strings.new_builder(64)
    mut prev_tok_str := ''
    for p.tok != .lcbr && p.tok != .eof {
        tok_str := p.comptime_cond_token_text()
        if cond.len > 0 && comptime_cond_needs_space(prev_tok_str, tok_str) {
            cond.write_string(' ')
        }
        cond.write_string(tok_str)
        prev_tok_str = tok_str
        p.next()
    }
    return cond.str()
}

fn (p &Parser) comptime_cond_token_text() string {
    if p.s.pos >= 0 && p.s.pos < p.s.src.len {
        c := p.s.src[p.s.pos]
        if c == `&` && p.s.pos + 1 < p.s.src.len && p.s.src[p.s.pos + 1] == `&` {
            return '&&'
        }
        if c == `|` && p.s.pos + 1 < p.s.src.len && p.s.src[p.s.pos + 1] == `|` {
            return '||'
        }
        if c == `!` && p.s.pos + 2 < p.s.src.len && p.s.src[p.s.pos + 1] == `i`
            && p.s.src[p.s.pos + 2] == `s` {
            return '!is'
        }
        if c == `!` {
            return '!'
        }
        if c == `?` {
            return '?'
        }
    }
    tok := p.tok
    if tok == .and {
        return '&&'
    }
    if tok == .logical_or {
        return '||'
    }
    if tok == .not {
        return '!'
    }
    if tok == .lpar {
        return '('
    }
    if tok == .rpar {
        return ')'
    }
    if tok == .key_is {
        return 'is'
    }
    if tok == .not_is {
        return '!is'
    }
    if tok == .dollar {
        return '$'
    }
    if tok == .lsbr {
        return '['
    }
    if tok == .rsbr {
        return ']'
    }
    if tok == .dot {
        return '.'
    }
    if tok == .comma {
        return ','
    }
    if tok == .question {
        return '?'
    }
    if tok == .key_true {
        return 'true'
    }
    if tok == .key_false {
        return 'false'
    }
    if p.lit.len > 0 {
        return p.lit
    }
    return ''
}

fn comptime_cond_needs_space(prev string, cur string) bool {
    if prev == 'is' || prev == '!is' {
        return true
    }
    if prev == '?' || prev == '!' {
        return false
    }
    if cur == '?' || cur == ']' || cur == '[' || cur == '.' || cur == ',' {
        return false
    }
    if prev == '$' || prev == '[' || prev == ']' || prev == '.' {
        return false
    }
    return true
}

fn comptime_cond_has_type_test(cond string) bool {
    return cond.contains(' is ') || cond.contains(' !is ')
}

fn (mut p Parser) skip_comptime_else() {
    for {
        if p.tok == .semicolon {
            p.next()
        }
        if p.tok != .dollar || p.peek() != .key_else {
            return
        }
        p.next() // skip $
        p.next() // skip else
        if p.tok == .semicolon {
            p.next()
        }
        if p.tok != .dollar || p.peek() != .key_if {
            p.skip_block()
            return
        }
        p.next() // skip $
        p.next() // skip if
        for p.tok != .lcbr && p.tok != .eof {
            p.next()
        }
        p.skip_block()
    }
}

fn (mut p Parser) parse_comptime_else() flat.NodeId {
    // Skip auto-semicolons before $else
    if p.tok == .semicolon && p.peek() == .dollar {
        p.next()
    }
    if p.tok != .dollar {
        return flat.empty_node
    }
    if p.peek() != .key_else {
        return flat.empty_node
    }
    p.next() // skip $
    p.next() // skip else
    // $else $if — recurse
    if p.tok == .dollar || (p.tok == .semicolon && p.peek() == .dollar) {
        if p.tok == .semicolon {
            p.next()
        }
        return p.parse_comptime_if()
    }
    return p.block_stmt()
}

fn (mut p Parser) parse_top_level_comptime_else() flat.NodeId {
    // Skip auto-semicolons before $else
    if p.tok == .semicolon && p.peek() == .dollar {
        p.next()
    }
    if p.tok != .dollar {
        return flat.empty_node
    }
    if p.peek() != .key_else {
        return flat.empty_node
    }
    p.next() // skip $
    p.next() // skip else
    // $else $if - recurse
    if p.tok == .dollar || (p.tok == .semicolon && p.peek() == .dollar) {
        if p.tok == .semicolon {
            p.next()
        }
        return p.parse_top_level_comptime_if()
    }
    return p.top_level_block_stmt()
}

fn eval_comptime_cond(prefs &pref.Preferences, cond string) bool {
    c := comptime_cond_strip_outer_parens(cond.trim_space())
    left_or, right_or, has_or := comptime_cond_split_top_level(c, '||')
    if has_or {
        return eval_comptime_cond(prefs, left_or) || eval_comptime_cond(prefs, right_or)
    }
    left_and, right_and, has_and := comptime_cond_split_top_level(c, '&&')
    if has_and {
        return eval_comptime_cond(prefs, left_and) && eval_comptime_cond(prefs, right_and)
    }
    if c.starts_with('!') {
        return !eval_comptime_cond(prefs, c[1..])
    }
    if c == 'true' {
        return true
    }
    if c == 'false' {
        return false
    }
    if c.starts_with('pkgconfig') {
        return eval_pkgconfig_cond(c)
    }
    flag := c.trim_space().trim_right('? ')
    return pref.comptime_flag_value(prefs, flag)
}

fn comptime_cond_strip_outer_parens(cond string) string {
    mut c := cond
    for c.len >= 2 && c[0] == `(` && c[c.len - 1] == `)` {
        mut depth := 0
        mut quote := u8(0)
        mut wraps := true
        for i in 0 .. c.len {
            ch := c[i]
            if quote != 0 {
                if ch == quote {
                    quote = 0
                }
                continue
            }
            if ch == `'` || ch == `"` {
                quote = ch
                continue
            }
            if ch == `(` {
                depth++
            } else if ch == `)` {
                depth--
                if depth == 0 && i != c.len - 1 {
                    wraps = false
                    break
                }
            }
        }
        if !wraps {
            break
        }
        c = c[1..c.len - 1].trim_space()
    }
    return c
}

fn comptime_cond_split_top_level(cond string, op string) (string, string, bool) {
    mut depth := 0
    mut quote := u8(0)
    mut i := 0
    for i < cond.len {
        ch := cond[i]
        if quote != 0 {
            if ch == quote {
                quote = 0
            }
            i++
            continue
        }
        if ch == `'` || ch == `"` {
            quote = ch
            i++
            continue
        }
        if ch == `(` {
            depth++
        } else if ch == `)` && depth > 0 {
            depth--
        }
        if depth == 0 && i + op.len <= cond.len && cond[i..i + op.len] == op {
            return cond[..i], cond[i + op.len..], true
        }
        i++
    }
    return '', '', false
}

fn eval_pkgconfig_cond(cond string) bool {
    name := pkgconfig_name_from_cond(cond)
    if !is_safe_pkgconfig_name(name) {
        return false
    }
    return os.system('pkg-config --exists ${name}') == 0
}

fn is_safe_pkgconfig_name(name string) bool {
    if name.len == 0 || !pkgconfig_name_char_is_alnum(name[0]) {
        return false
    }
    for ch in name {
        if pkgconfig_name_char_is_alnum(ch) || ch == `_` || ch == `-` || ch == `.` || ch == `+` {
            continue
        }
        return false
    }
    return true
}

fn pkgconfig_name_char_is_alnum(ch u8) bool {
    return (ch >= `a` && ch <= `z`) || (ch >= `A` && ch <= `Z`) || (ch >= `0` && ch <= `9`)
}

fn pkgconfig_name_from_cond(cond string) string {
    quote1 := cond.index_u8(`'`)
    if quote1 >= 0 {
        rest := cond[quote1 + 1..]
        end := rest.index_u8(`'`)
        if end >= 0 {
            return rest[..end]
        }
    }
    quote2 := cond.index_u8(`"`)
    if quote2 >= 0 {
        rest := cond[quote2 + 1..]
        end := rest.index_u8(`"`)
        if end >= 0 {
            return rest[..end]
        }
    }
    open := cond.index_u8(`(`)
    close := cond.last_index_u8(`)`)
    if open < 0 || close < 0 {
        return ''
    }
    if close <= open {
        return ''
    }
    return cond[open + 1..close].trim_space().trim('\'"')
}

fn (mut p Parser) skip_block() {
    if p.tok != .lcbr {
        return
    }
    mut depth := 1
    p.next()
    for depth > 0 && p.tok != .eof {
        if p.tok == .lcbr {
            depth++
        } else if p.tok == .rcbr {
            depth--
        }
        p.next()
    }
}

fn (mut p Parser) skip_brackets() {
    if p.tok != .lsbr {
        return
    }
    mut depth := 1
    p.next()
    for depth > 0 && p.tok != .eof {
        if p.tok == .lsbr {
            depth++
        } else if p.tok == .rsbr {
            depth--
        }
        p.next()
    }
}

fn (mut p Parser) parse_generic_param_names() []string {
    mut names := []string{}
    if p.tok != .lsbr {
        return names
    }
    mut depth := 1
    mut expect_name := true
    p.next()
    for depth > 0 && p.tok != .eof {
        if p.tok == .lsbr {
            depth++
            expect_name = false
        } else if p.tok == .rsbr {
            depth--
            if depth == 0 {
                p.next()
                break
            }
        } else if depth == 1 {
            if p.tok == .comma {
                expect_name = true
            } else if expect_name && p.tok == .name {
                names << p.lit
                expect_name = false
            } else {
                expect_name = false
            }
        }
        p.next()
    }
    return names
}

fn (mut p Parser) skip_parens() {
    if p.tok != .lpar {
        return
    }
    mut depth := 1
    p.next()
    for depth > 0 && p.tok != .eof {
        if p.tok == .lpar {
            depth++
        } else if p.tok == .rpar {
            depth--
        }
        p.next()
    }
}

fn (mut p Parser) parse_comptime_expr() flat.NodeId {
    if p.peek() == .key_for {
        return p.parse_comptime_if()
    }
    p.next() // skip $
    if p.tok == .key_if || (p.tok == .name && p.lit == 'if') {
        return p.parse_comptime_if_expr_after_if()
    }
    if p.tok == .name && p.lit == 'd' {
        p.next()
        if p.tok != .lpar {
            return flat.empty_node
        }
        p.next()
        // First argument is the compile-time define name. v3 currently only
        // uses the default expression, so consume the name expression.
        if p.tok != .comma && p.tok != .rpar && p.tok != .eof {
            p.expr(.lowest)
        }
        if p.tok == .comma {
            p.next()
            default_expr := p.expr(.lowest)
            for p.tok != .rpar && p.tok != .eof {
                p.next()
            }
            p.check(.rpar)
            return default_expr
        }
        p.check(.rpar)
        return flat.empty_node
    }
    if p.tok == .name && p.lit == 'res' {
        p.next()
        if p.tok == .lpar {
            p.skip_parens()
        }
        return p.a.add_val_id(3, 'false')
    }
    if p.tok == .name && p.lit == 'env' {
        // $env('NAME') evaluates an environment variable at compile time and
        // becomes a plain string literal (empty when the variable is unset).
        p.next() // skip 'env'
        mut env_val := ''
        if p.tok == .lpar {
            p.next() // skip (
            if p.tok == .string {
                env_val = os.getenv(strip_quotes(p.lit))
                p.next()
            }
            for p.tok != .rpar && p.tok != .eof {
                p.next()
            }
            p.check(.rpar)
        }
        return p.a.add_val_id(5, env_val)
    }
    for p.tok != .semicolon && p.tok != .eof {
        p.next()
    }
    // Unknown comptime expression: return an empty string literal rather than
    // `empty_node`, so consumers (e.g. const initializers) never store an
    // invalid (-1) child node.
    return p.a.add_val_id(5, '')
}

fn (mut p Parser) parse_comptime_if_expr() flat.NodeId {
    p.next() // skip $
    if p.tok != .key_if && !(p.tok == .name && p.lit == 'if') {
        return flat.empty_node
    }
    return p.parse_comptime_if_expr_after_if()
}

fn (mut p Parser) parse_comptime_if_expr_after_if() flat.NodeId {
    p.next() // skip if
    cond := p.parse_comptime_cond()
    taken := eval_comptime_cond(p.prefs, cond)
    if taken {
        result := p.parse_comptime_expr_block()
        p.skip_comptime_else()
        return result
    }
    p.skip_block()
    return p.parse_comptime_else_expr()
}

fn (mut p Parser) parse_comptime_else_expr() flat.NodeId {
    if p.tok == .semicolon && p.peek() == .dollar {
        p.next()
    }
    if p.tok != .dollar || p.peek() != .key_else {
        return flat.empty_node
    }
    p.next() // skip $
    p.next() // skip else
    if p.tok == .semicolon && p.peek() == .dollar {
        p.next()
    }
    if p.tok == .dollar {
        return p.parse_comptime_if_expr()
    }
    return p.parse_comptime_expr_block()
}

fn (mut p Parser) parse_comptime_expr_block() flat.NodeId {
    if p.tok != .lcbr {
        return flat.empty_node
    }
    p.next()
    if p.tok == .rcbr {
        p.next()
        return flat.empty_node
    }
    result := p.expr(.lowest)
    for p.tok != .rcbr && p.tok != .eof {
        p.next()
    }
    if p.tok == .rcbr {
        p.next()
    }
    return result
}

// ==================== statements ====================

fn (mut p Parser) stmt() flat.NodeId {
    match p.tok {
        .key_return {
            return p.return_stmt()
        }
        .key_if {
            return p.if_stmt()
        }
        .key_for {
            return p.for_stmt()
        }
        .key_fn {
            return p.fn_decl()
        }
        .key_match {
            return p.match_stmt()
        }
        .key_break {
            p.next()
            mut label := ''
            if p.tok == .name {
                label = p.lit
                p.next()
            }
            if p.tok == .semicolon {
                p.next()
            }
            return p.a.add_val(.break_stmt, label)
        }
        .key_continue {
            p.next()
            mut label := ''
            if p.tok == .name {
                label = p.lit
                p.next()
            }
            if p.tok == .semicolon {
                p.next()
            }
            return p.a.add_val(.continue_stmt, label)
        }
        .key_mut {
            p.next()
            if p.tok == .key_static {
                return p.static_decl_stmt()
            }
            return p.assign_or_expr_stmt()
        }
        .key_static {
            return p.static_decl_stmt()
        }
        .key_pub {
            p.next()
            if p.tok == .key_fn {
                return p.fn_decl()
            }
            return p.assign_or_expr_stmt()
        }
        .attribute {
            p.skip_attrs()
            return p.stmt()
        }
        .key_unsafe {
            p.next()
            return p.block_stmt()
        }
        .key_defer {
            return p.defer_stmt()
        }
        .key_assert {
            return p.assert_stmt()
        }
        .key_goto {
            return p.goto_stmt()
        }
        .key_go, .key_spawn {
            p.next()
            spawn_expr := p.expr(.lowest)
            if p.tok == .semicolon {
                p.next()
            }
            sstart := p.add_child(spawn_expr)
            return p.a.add_node(flat.Node{
                kind:           .expr_stmt
                children_start: sstart
                children_count: 1
            })
        }
        .key_asm {
            return p.asm_stmt()
        }
        .dollar {
            return p.parse_comptime_if()
        }
        .hash {
            return p.directive()
        }
        .lcbr {
            return p.block_stmt()
        }
        .semicolon {
            p.next()
            return flat.empty_node
        }
        .name {
            // label: name followed by ':'
            if p.peek() == .colon {
                label_name := p.lit
                p.next() // skip name
                p.next() // skip :
                if p.tok == .semicolon {
                    p.next()
                }
                return p.a.add_val(.label_stmt, label_name)
            }
            return p.assign_or_expr_stmt()
        }
        else {
            return p.assign_or_expr_stmt()
        }
    }
}

fn (mut p Parser) static_decl_stmt() flat.NodeId {
    p.next() // skip `static`
    if p.tok == .key_mut {
        p.next()
    }
    lhs := p.expr(.lowest)
    if p.tok == .decl_assign {
        p.next()
        rhs := p.expr(.lowest)
        if p.tok == .semicolon {
            p.next()
        }
        istart := p.add_children2(lhs, rhs)
        return p.a.add_node(flat.Node{
            kind:           .decl_assign
            op:             .assign
            value:          'static'
            children_start: istart
            children_count: 2
        })
    }
    if p.tok == .semicolon {
        p.next()
    }
    estart := p.add_child(lhs)
    return p.a.add_node(flat.Node{
        kind:           .expr_stmt
        children_start: estart
        children_count: 1
    })
}

fn (mut p Parser) return_stmt() flat.NodeId {
    p.next() // skip 'return'
    mut ids := []flat.NodeId{}
    if p.tok != .semicolon && p.tok != .rcbr && p.tok != .eof {
        ids << p.expr(.lowest)
        for p.tok == .comma {
            p.next()
            ids << p.expr(.lowest)
        }
    }
    if p.tok == .semicolon {
        p.next()
    }
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .return_stmt
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) if_stmt() flat.NodeId {
    p.next() // skip 'if'
    cond := p.expr(.lowest)

    // if-guard: if a, b := expr { ... } or if val := expr { ... }
    mut guard_cond := cond
    if p.tok == .comma || p.tok == .decl_assign {
        // Simple if-guard; treat as regular condition for flat AST
        if p.tok == .decl_assign {
            p.next()
            rhs := p.expr(.lowest)
            istart := p.add_children2(guard_cond, rhs)
            guard_cond = p.a.add_node(flat.Node{
                kind:           .decl_assign
                op:             .assign
                children_start: istart
                children_count: 2
            })
        } else {
            // comma case: if a, b := expr
            mut lhs_ids := []flat.NodeId{}
            lhs_ids << guard_cond
            for p.tok == .comma {
                p.next()
                lhs_ids << p.expr(.lowest)
            }
            if p.tok == .decl_assign {
                p.next()
                rhs := p.expr(.lowest)
                mut all_ids := []flat.NodeId{cap: lhs_ids.len + 1}
                all_ids << lhs_ids[0]
                all_ids << rhs
                for i in 1 .. lhs_ids.len {
                    all_ids << lhs_ids[i]
                }
                istart := p.add_children(all_ids)
                guard_cond = p.a.add_node(flat.Node{
                    kind:           .decl_assign
                    op:             .assign
                    children_start: istart
                    children_count: flat.child_count(all_ids.len)
                })
            }
        }
    }

    // skip auto-semicolon before {
    if p.tok == .semicolon && p.peek() == .lcbr {
        p.next()
    }
    body := p.block_stmt()
    mut ids := []flat.NodeId{}
    ids << guard_cond
    ids << body

    // skip auto-semicolon between } and else
    if p.tok == .semicolon && p.peek() == .key_else {
        p.next()
    }
    if p.tok == .key_else {
        p.next()
        if p.tok == .key_if {
            ids << p.if_stmt()
        } else {
            ids << p.block_stmt()
        }
    }
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .if_expr
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) for_stmt() flat.NodeId {
    p.next() // skip 'for'
    if p.tok == .lcbr {
        // infinite loop: for { ... }
        body_ids := p.parse_block_body()
        empty1 := p.a.add(flat.NodeKind.empty)
        empty2 := p.a.add(flat.NodeKind.empty)
        empty3 := p.a.add(flat.NodeKind.empty)
        mut ids := []flat.NodeId{}
        ids << empty1
        ids << empty2
        ids << empty3
        for id in body_ids {
            ids << id
        }
        start := p.add_children(ids)
        return p.a.add_node(flat.Node{
            kind:           .for_stmt
            children_start: start
            children_count: flat.child_count(ids.len)
        })
    }

    // Check for for-in: `for x in ...` or `for i, x in ...` or `for mut x in ...`
    if p.tok == .name && (p.peek() == .key_in || p.peek() == .comma) {
        first_expr := p.expr(.bit_or)
        return p.for_in(first_expr, false)
    }
    if p.tok == .key_mut {
        p.next()
        mut first_expr := flat.empty_node
        if p.tok == .name {
            ident := p.a.add_val(.ident, p.expect_name())
            if p.tok == .key_in || p.tok == .comma {
                first_expr = ident
            } else {
                first_expr = p.expr_with_lhs(ident, .lowest)
            }
        } else {
            first_expr = p.expr(.lowest)
        }
        if p.tok == .key_in || p.tok == .comma {
            return p.for_in(first_expr, true)
        }
        if p.tok == .lcbr {
            body_ids := p.parse_block_body()
            init_empty := p.a.add(flat.NodeKind.empty)
            post_empty := p.a.add(flat.NodeKind.empty)
            mut ids := []flat.NodeId{}
            ids << init_empty
            ids << first_expr
            ids << post_empty
            for id in body_ids {
                ids << id
            }
            start := p.add_children(ids)
            return p.a.add_node(flat.Node{
                kind:           .for_stmt
                children_start: start
                children_count: flat.child_count(ids.len)
            })
        }
    }

    if p.tok == .semicolon {
        p.next()
        cond := if p.tok == .semicolon {
            p.a.add(flat.NodeKind.empty)
        } else {
            p.expr(.lowest)
        }
        if p.tok == .semicolon {
            p.next()
        }
        post := if p.tok != .lcbr && p.tok != .eof {
            p.assign_or_expr_inline()
        } else {
            p.a.add(flat.NodeKind.empty)
        }
        body_ids := p.parse_block_body()
        mut ids := []flat.NodeId{}
        ids << p.a.add(flat.NodeKind.empty)
        ids << cond
        ids << post
        for id in body_ids {
            ids << id
        }
        start := p.add_children(ids)
        return p.a.add_node(flat.Node{
            kind:           .for_stmt
            children_start: start
            children_count: flat.child_count(ids.len)
        })
    }

    first_expr := p.expr(.lowest)

    // for-in: `for x in expr` or `for i, x in expr`
    if p.tok == .key_in || p.tok == .comma {
        return p.for_in(first_expr, false)
    }

    // C-style: `for i := 0; ...`
    if p.tok == .decl_assign || token_is_assignment(p.tok) {
        return p.for_c_style(first_expr)
    }

    if p.tok == .semicolon {
        // could be C-style with expression init, or just a separator
        // peek to check
        pk := p.peek()
        if pk == .semicolon || pk == .lcbr {
            // condition-only: `for cond { }`
            // fall through
        } else if pk != .rcbr && pk != .eof {
            // might be C-style: `for expr; cond; post`
            p.next() // skip ;
            cond := p.expr(.lowest)
            if p.tok == .semicolon {
                p.next()
            }
            post := if p.tok != .lcbr && p.tok != .eof {
                p.assign_or_expr_inline()
            } else {
                p.a.add(flat.NodeKind.empty)
            }
            body_ids := p.parse_block_body()
            // first_expr becomes init as expr_stmt
            init_start := p.add_child(first_expr)
            init_id := p.a.add_node(flat.Node{
                kind:           .expr_stmt
                children_start: init_start
                children_count: 1
            })
            mut ids := []flat.NodeId{}
            ids << init_id
            ids << cond
            ids << post
            for id in body_ids {
                ids << id
            }
            start := p.add_children(ids)
            return p.a.add_node(flat.Node{
                kind:           .for_stmt
                children_start: start
                children_count: flat.child_count(ids.len)
            })
        }
    }

    // condition-only: `for cond { ... }`
    if p.tok == .lcbr {
        body_ids := p.parse_block_body()
        init_empty := p.a.add(flat.NodeKind.empty)
        post_empty := p.a.add(flat.NodeKind.empty)
        mut ids := []flat.NodeId{}
        ids << init_empty
        ids << first_expr
        ids << post_empty
        for id in body_ids {
            ids << id
        }
        start := p.add_children(ids)
        return p.a.add_node(flat.Node{
            kind:           .for_stmt
            children_start: start
            children_count: flat.child_count(ids.len)
        })
    }

    return flat.empty_node
}

fn (mut p Parser) for_c_style(lhs_expr flat.NodeId) flat.NodeId {
    op_id := int(p.tok)
    p.next()
    rhs := p.expr(.lowest)

    mut init_id := flat.empty_node
    if op_id == 12 {
        istart := p.add_children2(lhs_expr, rhs)
        init_id = p.a.add_node(flat.Node{
            kind:           .decl_assign
            op:             .assign
            children_start: istart
            children_count: 2
        })
    } else {
        istart := p.add_children2(lhs_expr, rhs)
        init_id = p.a.add_node(flat.Node{
            kind:           .assign
            op:             token_id_to_op(op_id)
            children_start: istart
            children_count: 2
        })
    }

    if p.tok == .semicolon {
        p.next()
    }

    cond := p.expr(.lowest)
    if p.tok == .semicolon {
        p.next()
    }

    post := if p.tok != .lcbr && p.tok != .eof {
        p.assign_or_expr_inline()
    } else {
        p.a.add(flat.NodeKind.empty)
    }

    body_ids := p.parse_block_body()

    mut ids := []flat.NodeId{}
    ids << init_id
    ids << cond
    ids << post
    for id in body_ids {
        ids << id
    }
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .for_stmt
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) for_in(first_expr flat.NodeId, first_is_mut bool) flat.NodeId {
    // first_expr is either the key var or the only var
    mut key_id := first_expr
    mut val_id := flat.empty_node
    mut value_is_mut := first_is_mut

    if p.tok == .comma {
        p.next()
        // second variable
        if p.tok == .key_mut {
            p.next()
            value_is_mut = true
        }
        val_id = p.a.add_val(.ident, p.expect_name())
    }

    p.check(.key_in)
    was_in_for_container := p.in_for_container
    p.in_for_container = true
    container := p.expr(.lowest)
    p.in_for_container = was_in_for_container

    // optional range: `for i in 0 .. n`
    mut range_end := flat.empty_node
    if p.tok == .dotdot {
        p.next()
        range_end = p.expr(.lowest)
    }

    body_ids := p.parse_block_body()

    mut ids := []flat.NodeId{cap: 4 + body_ids.len}
    ids << key_id
    ids << val_id
    ids << container
    if int(range_end) >= 0 {
        ids << range_end
    }
    for id in body_ids {
        ids << id
    }
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .for_in_stmt
        children_start: start
        children_count: flat.child_count(ids.len)
        // value field stores the count of header elements (key, val, container, [range_end])
        // so gen knows where body starts
        value: if int(range_end) >= 0 { '4' } else { '3' }
        op:    if value_is_mut { .amp } else { .none }
    })
}

fn (mut p Parser) match_stmt() flat.NodeId {
    p.next() // skip 'match'
    match_expr := p.expr(.lowest)
    p.check(.lcbr)

    mut ids := []flat.NodeId{cap: 8}
    ids << match_expr

    for p.tok != .rcbr && p.tok != .eof {
        if p.tok == .semicolon {
            p.next()
            continue
        }
        ids << p.match_branch()
    }
    p.check(.rcbr)

    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .match_stmt
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) match_branch_cond() flat.NodeId {
    if p.tok == .lsbr && p.peek() == .rsbr {
        typ := p.parse_type_name()
        elem_type := if typ.starts_with('[]') { typ[2..] } else { typ }
        return p.a.add_node(flat.Node{
            kind:  .array_init
            value: elem_type
            typ:   typ
        })
    }
    if p.tok == .name && p.peek() == .dot {
        mod_name := p.lit
        p.next()
        p.next()
        if p.tok == .name && p.lit.len > 0 && p.lit[0] >= `A` && p.lit[0] <= `Z` {
            type_name := p.lit
            p.next()
            mod_id := p.a.add_val(.ident, mod_name)
            start := p.add_child(mod_id)
            return p.a.add_node(flat.Node{
                kind:           .selector
                value:          type_name
                children_start: start
                children_count: 1
            })
        }
        base_id := p.a.add_val(.ident, mod_name)
        start := p.add_child(base_id)
        sel := p.a.add_node(flat.Node{
            kind:           .selector
            value:          p.lit
            children_start: start
            children_count: 1
        })
        if p.tok == .name {
            p.next()
        }
        if p.tok != .lcbr && p.tok != .comma {
            return p.expr_with_lhs(sel, .lowest)
        }
        return sel
    }
    if p.tok == .name && p.lit.len > 0 && p.lit[0] >= `A` && p.lit[0] <= `Z` {
        name := p.lit
        p.next()
        return p.a.add_val(.ident, name)
    }
    if p.tok == .name && is_builtin_type(p.lit) && p.peek() == .lcbr {
        name := p.lit
        p.next()
        return p.a.add_val(.ident, name)
    }
    cond := p.expr(.lowest)
    if p.tok == .ellipsis {
        p.next()
        rhs := p.expr(.lowest)
        rstart := p.add_children2(cond, rhs)
        return p.a.add_node(flat.Node{
            kind:           .range
            children_start: rstart
            children_count: 2
        })
    }
    return cond
}

fn (mut p Parser) match_branch() flat.NodeId {
    mut branch_ids := []flat.NodeId{}
    mut is_else := false
    mut n_conds := 0

    if p.tok == .key_else {
        is_else = true
        p.next()
    } else {
        branch_ids << p.match_branch_cond()
        n_conds = 1
        for p.tok == .comma {
            p.next()
            branch_ids << p.match_branch_cond()
            n_conds++
        }
    }

    p.check(.lcbr)
    for p.tok != .rcbr && p.tok != .eof {
        if p.looks_like_match_branch_start() {
            break
        }
        id := p.stmt()
        if int(id) >= 0 {
            branch_ids << id
        }
    }
    p.check(.rcbr)

    bstart := p.add_children(branch_ids)
    return p.a.add_node(flat.Node{
        kind:           .match_branch
        value:          if is_else { 'else' } else { '${n_conds}' }
        children_start: bstart
        children_count: flat.child_count(branch_ids.len)
    })
}

fn (p &Parser) looks_like_match_branch_start() bool {
    if p.tok == .key_else {
        return true
    }
    return false
}

fn (mut p Parser) block_stmt() flat.NodeId {
    ids := p.parse_block_body()
    start := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .block
        children_start: start
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) parse_block_body() []flat.NodeId {
    p.check(.lcbr)
    mut ids := []flat.NodeId{}
    for p.tok != .rcbr && p.tok != .eof {
        id := p.stmt()
        if int(id) >= 0 {
            ids << id
        }
    }
    p.check(.rcbr)
    return ids
}

fn (mut p Parser) assign_or_expr_stmt() flat.NodeId {
    lhs := p.expr(.lowest)

    // multi-assign: a, b := expr1, expr2
    if p.tok == .comma {
        mut lhs_ids := []flat.NodeId{}
        lhs_ids << lhs
        for p.tok == .comma {
            p.next()
            if p.tok == .key_mut {
                p.next()
            }
            lhs_ids << p.expr(.lowest)
        }
        if p.tok == .decl_assign || token_is_assignment(p.tok) {
            op_id := int(p.tok)
            p.next()
            mut rhs_ids := []flat.NodeId{}
            rhs_ids << p.expr(.lowest)
            for p.tok == .comma {
                p.next()
                rhs_ids << p.expr(.lowest)
            }
            if p.tok == .semicolon {
                p.next()
            }
            mut all_ids := []flat.NodeId{cap: lhs_ids.len * 2}
            for i in 0 .. lhs_ids.len {
                all_ids << lhs_ids[i]
                if i < rhs_ids.len {
                    all_ids << rhs_ids[i]
                }
            }
            istart := p.add_children(all_ids)
            return p.a.add_node(flat.Node{
                kind:           if op_id == 12 {
                    flat.NodeKind.decl_assign
                } else {
                    flat.NodeKind.assign
                }
                op:             token_id_to_op(op_id)
                children_start: istart
                children_count: flat.child_count(all_ids.len)
            })
        }
        if p.tok == .semicolon {
            p.next()
        }
        mut stmt_ids := []flat.NodeId{cap: lhs_ids.len}
        for expr_id in lhs_ids {
            estart := p.add_child(expr_id)
            stmt_ids << p.a.add_node(flat.Node{
                kind:           .expr_stmt
                children_start: estart
                children_count: 1
            })
        }
        bstart := p.add_children(stmt_ids)
        return p.a.add_node(flat.Node{
            kind:           .block
            children_start: bstart
            children_count: flat.child_count(stmt_ids.len)
        })
    }

    if p.tok == .decl_assign {
        p.next()
        rhs := p.expr(.lowest)
        if p.tok == .semicolon {
            p.next()
        }
        istart := p.add_children2(lhs, rhs)
        return p.a.add_node(flat.Node{
            kind:           .decl_assign
            op:             .assign
            children_start: istart
            children_count: 2
        })
    }

    if token_is_assignment(p.tok) {
        op_id := int(p.tok)
        p.next()
        rhs := p.expr(.lowest)
        if p.tok == .semicolon {
            p.next()
        }
        lhs_node := p.a.nodes[int(lhs)]
        kind := if lhs_node.kind == .selector {
            flat.NodeKind.selector_assign
        } else if lhs_node.kind == .index {
            flat.NodeKind.index_assign
        } else {
            flat.NodeKind.assign
        }
        istart := p.add_children2(lhs, rhs)
        return p.a.add_node(flat.Node{
            kind:           kind
            op:             token_id_to_op(op_id)
            children_start: istart
            children_count: 2
        })
    }

    if p.tok == .semicolon {
        p.next()
    }

    estart := p.add_child(lhs)
    return p.a.add_node(flat.Node{
        kind:           .expr_stmt
        children_start: estart
        children_count: 1
    })
}

fn (mut p Parser) assign_or_expr_inline() flat.NodeId {
    lhs := p.expr(.lowest)

    if token_is_assignment(p.tok) {
        op_id := int(p.tok)
        p.next()
        rhs := p.expr(.lowest)
        lhs_node := p.a.nodes[int(lhs)]
        kind := if lhs_node.kind == .selector {
            flat.NodeKind.selector_assign
        } else if lhs_node.kind == .index {
            flat.NodeKind.index_assign
        } else {
            flat.NodeKind.assign
        }
        istart := p.add_children2(lhs, rhs)
        return p.a.add_node(flat.Node{
            kind:           kind
            op:             token_id_to_op(op_id)
            children_start: istart
            children_count: 2
        })
    }

    estart := p.add_child(lhs)
    return p.a.add_node(flat.Node{
        kind:           .expr_stmt
        children_start: estart
        children_count: 1
    })
}

fn (mut p Parser) defer_stmt() flat.NodeId {
    p.next() // skip 'defer'
    mut mode := ''
    if p.tok == .lpar {
        p.next()
        if p.tok == .key_fn {
            mode = 'function'
            p.next()
        }
        p.check(.rpar)
    }
    body := p.block_stmt()
    dstart := p.add_child(body)
    return p.a.add_node(flat.Node{
        kind:           .defer_stmt
        children_start: dstart
        children_count: 1
        value:          mode
    })
}

fn (mut p Parser) assert_stmt() flat.NodeId {
    p.next() // skip 'assert'
    cond := p.expr(.lowest)
    mut ids := []flat.NodeId{}
    ids << cond
    // optional message: assert cond, 'message'
    if p.tok == .comma {
        p.next()
        ids << p.expr(.lowest)
    }
    if p.tok == .semicolon {
        p.next()
    }
    astart := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .assert_stmt
        children_start: astart
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) goto_stmt() flat.NodeId {
    p.next() // skip 'goto'
    label := p.expect_name()
    if p.tok == .semicolon {
        p.next()
    }
    return p.a.add_val(.goto_stmt, label)
}

fn (mut p Parser) asm_stmt() flat.NodeId {
    p.next() // skip 'asm'
    // consume optional volatile keyword
    if p.tok == .name && p.lit == 'volatile' {
        p.next()
    }
    // consume the asm block
    if p.tok == .lcbr {
        p.skip_block()
    }
    if p.tok == .semicolon {
        p.next()
    }
    return p.a.add(flat.NodeKind.asm_stmt)
}

// ==================== expressions (Pratt parser) ====================

fn (mut p Parser) expr(min_bp token.BindingPower) flat.NodeId {
    lhs := p.prefix_expr()
    return p.expr_with_lhs(lhs, min_bp)
}

fn (mut p Parser) expr_with_lhs(first flat.NodeId, min_bp token.BindingPower) flat.NodeId {
    mut lhs := first
    for {
        // selector / method call
        if p.tok == .dot {
            lhs = p.selector_or_method(lhs)
            continue
        }
        // module-qualified struct init: module.Type{} or module.Type{field: val, ...}
        if p.tok == .lcbr {
            lhs_node := p.a.nodes[int(lhs)]
            if lhs_node.kind == .index {
                if full_name := p.generic_struct_init_type_name(lhs) {
                    lhs = p.struct_init(full_name)
                    continue
                }
            }
            if lhs_node.kind == .selector && lhs_node.value.len > 0 {
                base := p.a.child_node(&lhs_node, 0)
                is_c_struct := base.kind == .ident && base.value == 'C'
                    && !is_all_upper_ident(lhs_node.value)
                    && (p.peek() == .rcbr || p.peek() == .name
                    || p.peek() == .ellipsis)
                is_v_struct := base.kind == .ident && base.value != 'C' && lhs_node.value[0] >= `A`
                    && lhs_node.value[0] <= `Z`
                if is_c_struct || is_v_struct {
                    full_name := '${base.value}.${lhs_node.value}'
                    lhs = p.struct_init(full_name)
                    continue
                }
            }
        }
        // function call
        if p.tok == .lpar {
            lhs_node := p.a.nodes[int(lhs)]
            if lhs_node.kind == .selector && lhs_node.children_count > 0 && lhs_node.value.len > 0
                && lhs_node.value[0] >= `A` && lhs_node.value[0] <= `Z` {
                base := p.a.child_node(&lhs_node, 0)
                if base.kind == .ident && base.value != 'C' {
                    full_name := '${base.value}.${lhs_node.value}'
                    p.next() // skip (
                    inner := p.expr(.lowest)
                    p.check(.rpar)
                    cstart := p.add_child(inner)
                    lhs = p.a.add_node(flat.Node{
                        kind:           .cast_expr
                        value:          full_name
                        children_start: cstart
                        children_count: 1
                    })
                    continue
                }
            }
            lhs = p.call_args(lhs)
            continue
        }
        // index / generic
        if p.tok == .lsbr {
            lhs = p.index_expr(lhs)
            continue
        }
        // postfix: ++ -- ? !
        if token_is_postfix(p.tok) {
            op_id := int(p.tok)
            p.next()
            pstart := p.add_child(lhs)
            lhs = p.a.add_node(flat.Node{
                kind:           .postfix
                op:             token_id_to_op(op_id)
                children_start: pstart
                children_count: 1
            })
            continue
        }
        // postfix `!` error propagation: expr!
        if p.tok == .not {
            p.next()
            ostart := p.add_children2(lhs, p.a.add(flat.NodeKind.empty))
            lhs = p.a.add_node(flat.Node{
                kind:           .or_expr
                value:          '!'
                children_start: ostart
                children_count: 2
            })
            continue
        }
        // postfix `?` optional propagation: expr?
        if p.tok == .question {
            p.next()
            ostart := p.add_children2(lhs, p.a.add(flat.NodeKind.empty))
            lhs = p.a.add_node(flat.Node{
                kind:           .or_expr
                value:          '?'
                children_start: ostart
                children_count: 2
            })
            continue
        }
        // `as` cast: expr as Type
        if p.tok == .key_as {
            p.next()
            type_name := p.parse_type_name()
            astart := p.add_child(lhs)
            lhs = p.a.add_node(flat.Node{
                kind:           .as_expr
                value:          type_name
                children_start: astart
                children_count: 1
            })
            continue
        }
        // `or` block: expr or { ... }
        if p.tok == .key_or {
            p.next()
            or_body := p.block_stmt()
            ostart := p.add_children2(lhs, or_body)
            lhs = p.a.add_node(flat.Node{
                kind:           .or_expr
                children_start: ostart
                children_count: 2
            })
            continue
        }
        // range: expr .. expr
        if p.tok == .dotdot {
            if int(min_bp) > int(token.BindingPower.lowest) {
                break
            }
            p.next()
            rhs := p.expr(.lowest)
            rstart := p.add_children2(lhs, rhs)
            lhs = p.a.add_node(flat.Node{
                kind:           .range
                children_start: rstart
                children_count: 2
            })
            continue
        }
        // `is` / `!is` / `not_is` type check
        if p.tok == .key_is || p.tok == .not_is {
            bp := token.BindingPower.compare
            if int(bp) < int(min_bp) {
                break
            }
            is_negated := p.tok == .not_is
            p.next()
            type_name := p.parse_type_name()
            istart := p.add_child(lhs)
            is_node := p.a.add_node(flat.Node{
                kind:           .is_expr
                value:          type_name
                children_start: istart
                children_count: 1
            })
            if is_negated {
                nstart := p.add_child(is_node)
                lhs = p.a.add_node(flat.Node{
                    kind:           .prefix
                    op:             .not
                    children_start: nstart
                    children_count: 1
                })
            } else {
                lhs = is_node
            }
            continue
        }
        if p.tok == .not && p.peek() == .key_is {
            bp := token.BindingPower.compare
            if int(bp) < int(min_bp) {
                break
            }
            p.next() // skip !
            p.next() // skip is
            type_name := p.parse_type_name()
            istart := p.add_child(lhs)
            is_node := p.a.add_node(flat.Node{
                kind:           .is_expr
                value:          type_name
                children_start: istart
                children_count: 1
            })
            nstart := p.add_child(is_node)
            lhs = p.a.add_node(flat.Node{
                kind:           .prefix
                op:             .not
                children_start: nstart
                children_count: 1
            })
            continue
        }
        // `in` / `!in` / `not_in`
        if p.tok == .key_in || p.tok == .not_in {
            is_negated := p.tok == .not_in
            bp := token.BindingPower.compare
            if int(bp) < int(min_bp) {
                break
            }
            p.next()
            mut rhs := p.expr(token.BindingPower.bit_or)
            if p.tok == .dotdot {
                p.next()
                range_rhs := p.expr(.lowest)
                rstart := p.add_children2(rhs, range_rhs)
                rhs = p.a.add_node(flat.Node{
                    kind:           .range
                    children_start: rstart
                    children_count: 2
                })
            }
            istart := p.add_children2(lhs, rhs)
            in_node := p.a.add_node(flat.Node{
                kind:           .in_expr
                children_start: istart
                children_count: 2
            })
            if is_negated {
                nstart := p.add_child(in_node)
                lhs = p.a.add_node(flat.Node{
                    kind:           .prefix
                    op:             .not
                    children_start: nstart
                    children_count: 1
                })
            } else {
                lhs = in_node
            }
            continue
        }
        if p.tok == .not && p.peek() == .key_in {
            bp := token.BindingPower.compare
            if int(bp) < int(min_bp) {
                break
            }
            p.next() // skip !
            p.next() // skip in
            mut rhs := p.expr(token.BindingPower.bit_or)
            if p.tok == .dotdot {
                p.next()
                range_rhs := p.expr(.lowest)
                rstart := p.add_children2(rhs, range_rhs)
                rhs = p.a.add_node(flat.Node{
                    kind:           .range
                    children_start: rstart
                    children_count: 2
                })
            }
            istart := p.add_children2(lhs, rhs)
            in_node := p.a.add_node(flat.Node{
                kind:           .in_expr
                children_start: istart
                children_count: 2
            })
            nstart := p.add_child(in_node)
            lhs = p.a.add_node(flat.Node{
                kind:           .prefix
                op:             .not
                children_start: nstart
                children_count: 1
            })
            continue
        }
        // skip auto-semicolons before infix operators (multi-line expressions)
        if p.tok == .semicolon {
            peek_tok := p.peek()
            if token_is_infix(peek_tok) && int(peek_tok) != 85 && int(peek_tok) != 0 {
                p.next()
            }
        }
        if token_is_assignment(p.tok) {
            break
        }
        // infix operators
        if !token_is_infix(p.tok) {
            break
        }
        op_id := int(p.tok)
        bp := token_id_left_binding_power(op_id)
        if int(bp) < int(min_bp) {
            break
        }
        p.next()
        rhs := p.expr(token_id_right_binding_power(op_id))
        istart := p.add_children2(lhs, rhs)
        lhs = p.a.add_node(flat.Node{
            kind:           .infix
            op:             token_id_to_op(op_id)
            children_start: istart
            children_count: 2
        })
    }

    return lhs
}

fn (mut p Parser) sql_expr() flat.NodeId {
    db_expr := if p.tok != .lcbr && p.tok != .eof {
        p.expr(.lowest)
    } else {
        flat.empty_node
    }
    tokens := p.sql_block_tokens()
    typ := sql_result_type(tokens)
    mut children_start := 0
    mut children_count := 0
    if int(db_expr) >= 0 {
        children_start = p.add_child(db_expr)
        children_count = 1
    }
    return p.a.add_node(flat.Node{
        kind:           .sql_expr
        value:          tokens.join(' ')
        typ:            typ
        children_start: children_start
        children_count: flat.child_count(children_count)
    })
}

fn (mut p Parser) starts_sql_expr() bool {
    if p.tok != .name {
        return false
    }
    saved_s := p.s
    saved_tok := p.tok
    saved_lit := p.lit
    saved_tok_pos := p.tok_pos
    saved_prev_tok := p.prev_tok
    saved_peek_tok := p.peek_tok
    saved_peek_lit := p.peek_lit
    saved_peek_pos := p.peek_pos
    saved_has_peek := p.has_peek
    p.next()
    for p.tok == .dot {
        p.next()
        if p.tok != .name && !p.tok.is_keyword() {
            break
        }
        p.next()
    }
    ok := p.tok == .lcbr
    p.s = saved_s
    p.tok = saved_tok
    p.lit = saved_lit
    p.tok_pos = saved_tok_pos
    p.prev_tok = saved_prev_tok
    p.peek_tok = saved_peek_tok
    p.peek_lit = saved_peek_lit
    p.peek_pos = saved_peek_pos
    p.has_peek = saved_has_peek
    return ok
}

fn (mut p Parser) sql_block_tokens() []string {
    mut tokens := []string{}
    if p.tok != .lcbr {
        return tokens
    }
    mut depth := 1
    p.next()
    for depth > 0 && p.tok != .eof {
        if p.tok == .lcbr {
            depth++
        } else if p.tok == .rcbr {
            depth--
            if depth == 0 {
                p.next()
                break
            }
        }
        if depth > 0 {
            text := p.sql_token_text()
            if text.len > 0 {
                tokens << text
            }
            p.next()
        }
    }
    return tokens
}

fn (p &Parser) sql_token_text() string {
    if p.lit.len > 0 {
        return p.lit
    }
    return match p.tok {
        .key_select { 'select' }
        .key_in { 'in' }
        .key_or { 'or' }
        .key_as { 'as' }
        .key_true { 'true' }
        .key_false { 'false' }
        else { '' }
    }
}

fn sql_result_type(tokens []string) string {
    if tokens.len == 0 {
        return '!void'
    }
    if tokens[0] != 'select' {
        return '!void'
    }
    if tokens.len > 1 && tokens[1] == 'count' {
        return '!int'
    }
    for i, tok in tokens {
        if tok == 'from' && i + 1 < tokens.len {
            table := sql_type_name(tokens[i + 1])
            if table.len > 0 {
                return '![]${table}'
            }
        }
    }
    return '![]int'
}

fn sql_type_name(raw string) string {
    mut out := strings.new_builder(raw.len)
    for ch in raw {
        if (ch >= `a` && ch <= `z`) || (ch >= `A` && ch <= `Z`)
            || (ch >= `0` && ch <= `9`) || ch == `_` || ch == `.` {
            out.write_u8(ch)
        } else {
            break
        }
    }
    return out.str()
}

fn is_float_number_literal(val string) bool {
    if val.len > 2 && val[0] == `0` {
        second := val[1]
        if second == `x` || second == `X` || second == `b` || second == `B` || second == `o`
            || second == `O` {
            return false
        }
    }
    return val.contains('.') || val.contains('e') || val.contains('E')
}

fn (mut p Parser) prefix_expr() flat.NodeId {
    tok_id := int(p.tok)
    if tok_id == 92 {
        val := p.lit
        p.next()
        kind_id := if is_float_number_literal(val) {
            2
        } else {
            1
        }
        return p.a.add_val_id(kind_id, val)
    }
    if tok_id == 107 {
        return p.string_literal()
    }
    if tok_id == 7 {
        val := p.lit
        p.next()
        return p.a.add_val_id(4, val)
    }
    if tok_id == 66 {
        p.next()
        return p.a.add_val_id(3, 'true')
    }
    if tok_id == 36 {
        p.next()
        return p.a.add_val_id(3, 'false')
    }
    if tok_id == 53 {
        p.next()
        return p.a.add_id(28)
    }
    if tok_id == 54 {
        p.next()
        return p.a.add_id(29)
    }
    if tok_id == 3 {
        p.next()
        inner := p.expr(.highest)
        return p.a.add_node(flat.Node{
            kind:           .prefix
            op:             .arrow
            children_start: p.add_child(inner)
            children_count: 1
        })
    }
    if tok_id == 6 || tok_id == 81 || tok_id == 85 || tok_id == 89 {
        p.next()
        operand := p.expr(.highest)
        pstart := p.add_child(operand)
        return p.a.add_node(flat.Node{
            kind:           .prefix
            op:             token_id_to_op(tok_id)
            children_start: pstart
            children_count: 1
        })
    }
    match p.tok {
        .number {
            val := p.lit
            p.next()
            kind_id := if is_float_number_literal(val) {
                2
            } else {
                1
            }
            return p.a.add_val_id(kind_id, val)
        }
        .string {
            return p.string_literal()
        }
        .char {
            val := p.lit
            p.next()
            return p.a.add_val_id(4, val)
        }
        .key_true {
            p.next()
            return p.a.add_val_id(3, 'true')
        }
        .key_false {
            p.next()
            return p.a.add_val_id(3, 'false')
        }
        .key_nil {
            p.next()
            return p.a.add_id(28)
        }
        .key_none {
            p.next()
            return p.a.add_id(29)
        }
        .arrow {
            p.next()
            inner := p.expr(.highest)
            return p.a.add_node(flat.Node{
                kind:           .prefix
                op:             .arrow
                children_start: p.add_child(inner)
                children_count: 1
            })
        }
        .key_mut, .key_shared {
            p.next()
            return p.prefix_expr()
        }
        .name, .key_module {
            name := p.lit
            p.next()
            if name == 'sql' && p.starts_sql_expr() {
                return p.sql_expr()
            }
            if name == '@FILE' {
                return p.a.add_val_id(5, p.cur_file)
            }
            if name == '@VMODROOT' {
                return p.a.add_val_id(5, vmod_root_for_file(p.cur_file))
            }
            if name == '@VEXEROOT' {
                return p.a.add_val_id(5, p.prefs.vroot)
            }
            if name == '@VEXE' {
                return p.a.add_val_id(5, p.prefs.vroot + '/v')
            }
            if name == '@LINE' {
                return p.a.add_val_id(1, '0')
            }
            if name == '@FN' || name == '@METHOD' {
                return p.a.add_val_id(5, p.cur_fn)
            }
            if name == '@LOCATION' {
                return p.a.add_val_id(5, '${p.cur_file}:0: ${p.cur_fn}')
            }
            if name == '@VCURRENTHASH' || name == '@VHASH' {
                return p.a.add_val_id(5, '')
            }
            if name == 'chan' && p.can_start_type_name() {
                elem_type := p.parse_type_name()
                chan_type := 'chan ${elem_type}'
                if p.tok == .lcbr {
                    return p.struct_init(chan_type)
                }
                return p.a.add_val(.ident, chan_type)
            }
            // map init: map[K]V{} or map[K]V{k1: v1, ...}
            if name == 'map' && p.tok == .lsbr {
                p.next() // skip [
                key_type := p.parse_type_name()
                p.check(.rsbr)
                val_type := p.parse_type_name()
                map_type := 'map[${key_type}]${val_type}'
                if p.tok == .lcbr {
                    p.next() // skip {
                    mut ids := []flat.NodeId{}
                    for p.tok != .rcbr && p.tok != .eof {
                        if p.tok == .semicolon {
                            p.next()
                            continue
                        }
                        k := p.expr(.lowest)
                        p.check(.colon)
                        v := p.expr(.lowest)
                        ids << k
                        ids << v
                        if p.tok == .comma || p.tok == .semicolon {
                            p.next()
                        }
                    }
                    p.check(.rcbr)
                    if ids.len > 0 {
                        istart := p.add_children(ids)
                        return p.a.add_node(flat.Node{
                            kind:           .map_init
                            value:          map_type
                            children_start: istart
                            children_count: flat.child_count(ids.len)
                        })
                    }
                }
                return p.a.add_val(.map_init, map_type)
            }
            // struct init: Name{...}; vlib/builtin also uses concrete lowercase
            // runtime structs like array{} and string{}.
            if !p.in_for_container && p.tok == .lcbr && name.len > 0
                && ((name[0] >= `A` && name[0] <= `Z`)
                || name in ['array', 'string', 'map', 'mapnode', '_result', '_option']) {
                return p.struct_init(name)
            }
            // type cast: TypeName(expr) or builtin_type(expr)
            if p.tok == .lpar && name.len > 0 && ((name[0] >= `A` && name[0] <= `Z`)
                || is_builtin_type(name)) {
                p.next() // skip (
                inner := p.expr(.lowest)
                p.check(.rpar)
                cstart := p.add_child(inner)
                return p.a.add_node(flat.Node{
                    kind:           .cast_expr
                    value:          name
                    children_start: cstart
                    children_count: 1
                })
            }
            return p.a.add_val(.ident, name)
        }
        .lpar {
            p.next()
            inner := p.expr(.lowest)
            p.check(.rpar)
            pstart := p.add_child(inner)
            return p.a.add_node(flat.Node{
                kind:           .paren
                children_start: pstart
                children_count: 1
            })
        }
        .lcbr {
            p.next()
            mut ids := []flat.NodeId{}
            for p.tok != .rcbr && p.tok != .eof {
                if p.tok == .semicolon || p.tok == .comma {
                    p.next()
                    continue
                }
                k := p.expr(.lowest)
                p.check(.colon)
                v := p.expr(.lowest)
                ids << k
                ids << v
                if p.tok == .comma || p.tok == .semicolon {
                    p.next()
                }
            }
            p.check(.rcbr)
            start := p.add_children(ids)
            return p.a.add_node(flat.Node{
                kind:           .map_init
                children_start: start
                children_count: flat.child_count(ids.len)
            })
        }
        .amp {
            p.next()
            if p.tok == .amp {
                p.next()
                if p.tok == .name && is_builtin_type(p.lit) {
                    type_name := '&&${p.lit}'
                    p.next()
                    if p.tok == .lpar {
                        p.next()
                        inner := p.expr(.lowest)
                        p.check(.rpar)
                        cstart := p.add_child(inner)
                        return p.a.add_node(flat.Node{
                            kind:           .cast_expr
                            value:          type_name
                            children_start: cstart
                            children_count: 1
                        })
                    }
                    id := p.a.add_val(.ident, type_name[2..])
                    first := p.a.add_node(flat.Node{
                        kind:           .prefix
                        op:             .amp
                        children_start: p.add_child(id)
                        children_count: 1
                    })
                    return p.a.add_node(flat.Node{
                        kind:           .prefix
                        op:             .amp
                        children_start: p.add_child(first)
                        children_count: 1
                    })
                }
            } else if p.tok == .name && is_builtin_type(p.lit) {
                name := p.lit
                type_name := '&${name}'
                p.next()
                if p.tok == .lpar {
                    p.next()
                    inner := p.expr(.lowest)
                    p.check(.rpar)
                    cstart := p.add_child(inner)
                    return p.a.add_node(flat.Node{
                        kind:           .cast_expr
                        value:          type_name
                        children_start: cstart
                        children_count: 1
                    })
                }
                if p.tok == .lcbr {
                    inner := p.struct_init(name)
                    return p.a.add_node(flat.Node{
                        kind:           .prefix
                        op:             .amp
                        children_start: p.add_child(inner)
                        children_count: 1
                    })
                }
                id := p.a.add_val(.ident, name)
                return p.a.add_node(flat.Node{
                    kind:           .prefix
                    op:             .amp
                    children_start: p.add_child(id)
                    children_count: 1
                })
            } else if p.tok == .lsbr && p.peek() == .rsbr {
                type_name := '&' + p.parse_type_name()
                if p.tok == .lpar {
                    p.next()
                    inner := p.expr(.lowest)
                    p.check(.rpar)
                    cstart := p.add_child(inner)
                    return p.a.add_node(flat.Node{
                        kind:           .cast_expr
                        value:          type_name
                        children_start: cstart
                        children_count: 1
                    })
                }
            }
            operand := p.expr(.highest)
            pstart := p.add_child(operand)
            return p.a.add_node(flat.Node{
                kind:           .prefix
                op:             .amp
                children_start: pstart
                children_count: 1
            })
        }
        .and {
            p.next()
            if p.tok == .name && is_builtin_type(p.lit) {
                type_name := '&&${p.lit}'
                p.next()
                if p.tok == .lpar {
                    p.next()
                    inner := p.expr(.lowest)
                    p.check(.rpar)
                    cstart := p.add_child(inner)
                    return p.a.add_node(flat.Node{
                        kind:           .cast_expr
                        value:          type_name
                        children_start: cstart
                        children_count: 1
                    })
                }
            }
            return p.a.add(.empty)
        }
        .minus, .not, .bit_not, .mul {
            op_id := int(p.tok)
            p.next()
            operand := p.expr(.highest)
            pstart := p.add_child(operand)
            return p.a.add_node(flat.Node{
                kind:           .prefix
                op:             token_id_to_op(op_id)
                children_start: pstart
                children_count: 1
            })
        }
        .question {
            p.next()
            inner_type := p.parse_type_name()
            type_name := if inner_type.len > 0 { '?${inner_type}' } else { '?' }
            if p.tok == .lpar {
                p.next()
                inner := p.expr(.lowest)
                p.check(.rpar)
                cstart := p.add_child(inner)
                return p.a.add_node(flat.Node{
                    kind:           .cast_expr
                    value:          type_name
                    children_start: cstart
                    children_count: 1
                })
            }
            return p.a.add(flat.NodeKind.empty)
        }
        .key_if {
            return p.if_stmt()
        }
        .key_match {
            return p.match_stmt()
        }
        .key_fn {
            return p.fn_literal()
        }
        .key_go, .key_spawn {
            p.next()
            inner := p.expr(.lowest)
            sstart := p.add_child(inner)
            return p.a.add_node(flat.Node{
                kind:           .spawn_expr
                children_start: sstart
                children_count: 1
            })
        }
        .key_lock, .key_rlock {
            return p.lock_expr()
        }
        .key_select {
            if p.peek() == .lpar {
                p.next()
                return p.a.add_val(.ident, 'select')
            }
            return p.select_expr()
        }
        .key_sizeof {
            return p.sizeof_expr()
        }
        .key_typeof {
            return p.typeof_expr()
        }
        .key_offsetof {
            return p.offsetof_expr()
        }
        .key_dump {
            return p.dump_expr()
        }
        .key_likely, .key_unlikely {
            p.next()
            p.check(.lpar)
            inner := p.expr(.lowest)
            p.check(.rpar)
            return inner
        }
        .key_isreftype {
            p.next()
            p.check(.lpar)
            p.parse_type_name()
            p.check(.rpar)
            return p.a.add_val_id(3, 'false')
        }
        .dot {
            // enum value: .member
            p.next()
            member := p.expect_name_or_keyword()
            return p.a.add_val(.enum_val, member)
        }
        .lsbr {
            return p.array_literal()
        }
        .key_unsafe {
            p.next()
            return p.block_stmt()
        }
        .ellipsis {
            // spread: ...expr
            p.next()
            inner := p.expr(.lowest)
            pstart := p.add_child(inner)
            return p.a.add_node(flat.Node{
                kind:           .prefix
                op:             .none
                value:          '...'
                children_start: pstart
                children_count: 1
            })
        }
        .dollar {
            return p.parse_comptime_expr()
        }
        else {
            p.next()
            return p.a.add(flat.NodeKind.empty)
        }
    }
}

fn (mut p Parser) selector_or_method(lhs flat.NodeId) flat.NodeId {
    p.next() // skip '.'
    field_name := p.expect_name_or_keyword()
    sel_start := p.add_child(lhs)
    sel := p.a.add_node(flat.Node{
        kind:           .selector
        value:          field_name
        children_start: sel_start
        children_count: 1
    })
    if p.tok == .lpar {
        lhs_node := p.a.nodes[int(lhs)]
        if lhs_node.kind == .ident && lhs_node.value != 'C' && field_name.len > 0
            && field_name[0] >= `A` && field_name[0] <= `Z` {
            full_name := '${lhs_node.value}.${field_name}'
            p.next() // skip (
            inner := p.expr(.lowest)
            p.check(.rpar)
            cstart := p.add_child(inner)
            return p.a.add_node(flat.Node{
                kind:           .cast_expr
                value:          full_name
                children_start: cstart
                children_count: 1
            })
        }
        return p.call_args(sel)
    }
    return sel
}

fn (mut p Parser) call_args(fn_expr flat.NodeId) flat.NodeId {
    p.check(.lpar)
    mut ids := []flat.NodeId{}
    ids << fn_expr
    for p.tok != .rpar && p.tok != .eof {
        prev_offset := p.s.offset
        prev_tok := p.tok
        if p.tok == .key_mut || p.tok == .key_shared {
            p.next()
        }
        // vararg spread: ...expr
        if p.tok == .ellipsis {
            p.next()
            inner := p.expr(.lowest)
            sstart := p.add_child(inner)
            ids << p.a.add_node(flat.Node{
                kind:           .prefix
                op:             .none
                value:          '...'
                children_start: sstart
                children_count: 1
            })
        } else if p.tok == .logical_or {
            // lambda no args: || expr
            p.next()
            lambda_body := p.expr(.lowest)
            lstart := p.add_child(lambda_body)
            ids << p.a.add_node(flat.Node{
                kind:           .lambda_expr
                children_start: lstart
                children_count: 1
            })
        } else if p.tok == .pipe {
            // lambda with args: |a, b| expr
            p.next()
            mut lambda_params := []flat.NodeId{}
            lambda_params << p.a.add_val(.ident, p.expect_name())
            for p.tok == .comma {
                p.next()
                lambda_params << p.a.add_val(.ident, p.expect_name())
            }
            p.check(.pipe)
            lambda_body := p.expr(.lowest)
            mut lids := lambda_params.clone()
            lids << lambda_body
            lstart := p.add_children(lids)
            ids << p.a.add_node(flat.Node{
                kind:           .lambda_expr
                children_start: lstart
                children_count: flat.child_count(lids.len)
            })
        } else {
            arg := p.expr(.lowest)
            // struct config syntax: name: value
            if p.tok == .colon {
                p.next()
                val := p.expr(.lowest)
                arg_node := p.a.nodes[int(arg)]
                vstart := p.add_child(val)
                ids << p.a.add_node(flat.Node{
                    kind:           .field_init
                    value:          arg_node.value
                    children_start: vstart
                    children_count: 1
                })
                if p.tok == .semicolon {
                    p.next()
                }
            } else {
                ids << arg
            }
        }
        if p.tok == .comma {
            p.next()
        }
        if p.s.offset == prev_offset && p.tok == prev_tok {
            p.next()
        }
    }
    p.check(.rpar)
    cstart := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .call
        children_start: cstart
        children_count: flat.child_count(ids.len)
    })
}

fn (mut p Parser) index_expr(lhs flat.NodeId) flat.NodeId {
    p.check(.lsbr)
    // range index: arr[..b]
    if p.tok == .dotdot {
        p.next()
        mut end_id := flat.empty_node
        if p.tok != .rsbr {
            end_id = p.expr(.lowest)
        }
        p.check(.rsbr)
        start_id := p.a.add(flat.NodeKind.empty)
        mut ids := []flat.NodeId{}
        ids << lhs
        ids << start_id
        if int(end_id) >= 0 {
            ids << end_id
        }
        istart := p.add_children(ids)
        return p.a.add_node(flat.Node{
            kind:           .index
            value:          'range'
            children_start: istart
            children_count: flat.child_count(ids.len)
        })
    }
    idx := p.expr(.logical_or)
    // fast path for the common simple index `arr[i]`: avoid the children array
    if p.tok == .rsbr {
        p.next()
        istart := p.add_children2(lhs, idx)
        return p.a.add_node(flat.Node{
            kind:           .index
            children_start: istart
            children_count: 2
        })
    }
    mut ids := []flat.NodeId{}
    ids << lhs
    ids << idx
    for p.tok == .comma {
        p.next()
        ids << p.expr(.logical_or)
    }
    // range index: arr[a..b]
    if p.tok == .dotdot {
        p.next()
        mut end_id := flat.empty_node
        if p.tok != .rsbr {
            end_id = p.expr(.lowest)
        }
        p.check(.rsbr)
        mut range_ids := []flat.NodeId{}
        range_ids << lhs
        range_ids << idx
        if int(end_id) >= 0 {
            range_ids << end_id
        }
        istart := p.add_children(range_ids)
        return p.a.add_node(flat.Node{
            kind:           .index
            value:          'range'
            children_start: istart
            children_count: flat.child_count(range_ids.len)
        })
    }
    p.check(.rsbr)
    istart := p.add_children(ids)
    return p.a.add_node(flat.Node{
        kind:           .index
        children_start: istart
        children_count: flat.child_count(ids.len)
    })
}

fn (p &Parser) generic_struct_init_type_name(id flat.NodeId) ?string {
    type_name := p.type_expr_name(id)
    if !generic_type_name_can_init(type_name) {
        return none
    }
    return type_name
}

fn (p &Parser) type_expr_name(id flat.NodeId) string {
    if int(id) < 0 {
        return ''
    }
    node := p.a.nodes[int(id)]
    match node.kind {
        .ident {
            return node.value
        }
        .selector {
            if node.children_count == 0 {
                return node.value
            }
            base := p.type_expr_name(p.a.child(&node, 0))
            if base.len == 0 {
                return node.value
            }
            return '${base}.${node.value}'
        }
        .index {
            if node.children_count < 2 || node.value == 'range' {
                return ''
            }
            base := p.type_expr_name(p.a.child(&node, 0))
            if base.len == 0 {
                return ''
            }
            mut args := []string{}
            for i in 1 .. node.children_count {
                arg := p.type_expr_name(p.a.child(&node, i))
                if arg.len == 0 {
                    return ''
                }
                args << arg
            }
            return '${base}[${args.join(', ')}]'
        }
        .array_init {
            if node.value.len == 0 {
                return ''
            }
            return '[]${node.value}'
        }
        .prefix {
            if node.children_count == 0 {
                return ''
            }
            child := p.type_expr_name(p.a.child(&node, 0))
            if child.len == 0 {
                return ''
            }
            if node.op == .amp {
                return '&${child}'
            }
            return child
        }
        else {
            return ''
        }
    }
}

fn generic_type_name_can_init(type_name string) bool {
    if !type_name.contains('[') {
        return false
    }
    base := type_name.all_before('[')
    short := if base.contains('.') { base.all_after_last('.') } else { base }
    return short.len > 0 && short[0] >= `A` && short[0] <= `Z`
}

fn (mut p Parser) struct_init(name string) flat.NodeId {
    p.check(.lcbr)
    mut ids := []flat.NodeId{}
    // assoc syntax: Type{...base, field: val}
    if p.tok == .ellipsis {
        p.next()
        base_expr := p.expr(.lowest)
        if p.tok == .comma || p.tok == .semicolon {
            p.next()
        }
        mut field_ids := []flat.NodeId{}
        field_ids << base_expr
        for p.tok != .rcbr && p.tok != .eof {
            if p.tok == .comma {
                p.next()
            }
            fname := p.expect_name_or_keyword()
            p.check(.colon)
            val := p.expr(.lowest)
            vstart := p.add_child(val)
            field_ids << p.a.add_node(flat.Node{
                kind:           .field_init