// Copyright (c) 2020-2024 Joe Conigliaro. All rights reserved.
// Use of this source code is governed by an MIT license
// that can be found in the LICENSE file.
module types

import sync
import time
import strconv
import v2.ast
import v2.errors
import v2.pref
import v2.token

const embed_file_helper_type_name = '__V2EmbedFileData'
const max_checker_expr_depth = 40

pub struct Environment {
pub mut:
    // errors with no default value
    scopes shared map[string]&Scope = map[string]&Scope{}
    // Function scopes - stores the scope for each function by qualified name (module__fn_name)
    // This allows later passes (transformer, codegen) to look up local variable types
    fn_scopes shared map[string]&Scope = map[string]&Scope{}
    // types map[int]Type
    // methods - shared for parallel type checking
    methods           shared map[string][]&Fn = map[string][]&Fn{}
    generic_types     map[string][]map[string]Type
    cur_generic_types []map[string]Type
    // Expression types keyed by token.Pos.id. Positive IDs come from the parser;
    // negative IDs come from transformer's synthesized nodes. This must stay sparse:
    // parser position IDs are not dense enough to use as direct array indexes in
    // large self-host builds.
    expr_types     map[int]Type
    selector_names map[int]string
    // Drop-codegen handoff: per-fn list of bindings whose `drop(mut self)`
    // method must be called at the fn's natural exit, in declaration order.
    // Populated by `ownership_snapshot_drops_at_fn_exit` after each fn body
    // is checked (with moves removed), read by the cleanc backend to emit
    // `Type__drop(&var)` calls before the fn's closing brace. Only populated
    // when the checker runs with `-d ownership`; empty under plain V.
    drop_at_fn_exit map[string][]DropEntry
    // Drop-codegen handoff for early returns: per-fn list of per-return-stmt
    // drop snapshots, in source order. The cleanc backend walks the fn body
    // in the same order and maintains a parallel counter to match each
    // ReturnStmt to its snapshot. Each inner []DropEntry is the set of
    // bindings that must be dropped just BEFORE the corresponding return.
    // Bindings that are themselves being returned (and thus moved out) are
    // excluded by the checker — the return moves them. Only populated when
    // the checker runs with `-d ownership`; empty under plain V.
    drop_at_returns map[string][][]DropEntry
    // Shared C-language scope. Phase 1 workers register C struct decls into
    // here under c_scope_mu; phase 2 (sequential) registers C fn signatures.
    // All checkers point their per-checker `c_scope` field at this instance
    // so that the `C` Module pasted into each module scope resolves uniformly.
    c_scope    &Scope      = unsafe { nil }
    c_scope_mu &sync.Mutex = unsafe { nil }
}

pub fn Environment.new() &Environment {
    return Environment.new_with_capacity(0, 0)
}

// Environment.new_with_capacity returns a new checker environment with the hot
// expression metadata maps pre-sized for large flat-AST builds.
pub fn Environment.new_with_capacity(expr_types_cap int, selector_names_cap int) &Environment {
    mut env := &Environment{
        expr_types:     map[int]Type{}
        selector_names: map[int]string{}
        c_scope:        new_scope(unsafe { nil })
        c_scope_mu:     sync.new_mutex()
    }
    if expr_types_cap > 0 {
        env.expr_types.reserve(u32(expr_types_cap))
    }
    if selector_names_cap > 0 {
        env.selector_names.reserve(u32(selector_names_cap))
    }
    return env
}

// set_expr_type stores the computed type for an expression by its unique ID.
pub fn (mut e Environment) set_expr_type(id int, typ Type) {
    e.expr_types[id] = typ
}

// get_expr_type retrieves the computed type for an expression by its unique ID.
pub fn (e &Environment) get_expr_type(id int) ?Type {
    typ := e.expr_types[id] or { return none }
    if typ is Void || type_has_null_data(typ) {
        return none
    }
    return typ
}

// has_expr_type reports whether an expression has a stored type. Unlike
// get_expr_type, it treats an explicit `void` type as present.
pub fn (e &Environment) has_expr_type(id int) bool {
    typ := e.expr_types[id] or { return false }
    if typ is Void {
        return u8(typ) != 1
    }
    return !type_has_null_data(typ)
}

pub fn (e &Environment) expr_type_count() int {
    return e.expr_types.len
}

pub fn (e &Environment) all_expr_types() []Type {
    mut out := []Type{cap: e.expr_types.len}
    for _, typ in e.expr_types {
        out << typ
    }
    return out
}

// release_expr_type_cache_after_ssa releases expression-position metadata once
// SSA has consumed it. Native MIR/codegen keeps type IDs in SSA/MIR values and
// does not need these maps on the ARM64 path.
pub fn (mut e Environment) release_expr_type_cache_after_ssa() {
    unsafe {
        e.expr_types.free()
        e.selector_names.free()
    }
    e.expr_types = map[int]Type{}
    e.selector_names = map[int]string{}
}

// type_has_null_data checks if a Type sumtype has a missing payload.
// Some Type variants are stored inline and legitimately have a zero data word;
// larger variants need a non-null payload pointer.
fn type_has_null_data(t Type) bool {
    return !type_has_valid_payload(t)
}

fn expr_call_payload_ref(expr ast.Expr) ?&ast.CallExpr {
    slot0 := unsafe { (&u64(&expr))[0] }
    slot1 := unsafe { (&u64(&expr))[1] }
    tag := sumtype_tag_slot(slot0, slot1)
    if !is_ast_expr_call_expr_tag(tag) {
        return none
    }
    data := sumtype_payload_slot(slot0, slot1)
    if data == 0 {
        return none
    }
    return unsafe { &ast.CallExpr(voidptr(data)) }
}

fn expr_ident_payload(expr ast.Expr) ?ast.Ident {
    slot0 := unsafe { (&u64(&expr))[0] }
    slot1 := unsafe { (&u64(&expr))[1] }
    tag := sumtype_tag_slot(slot0, slot1)
    if tag == u64(13) {
        data := sumtype_payload_slot(slot0, slot1)
        if data == 0 {
            return none
        }
        return unsafe { *&ast.Ident(voidptr(data)) }
    }

    match expr {
        ast.Ident {
            return expr
        }
        else {}
    }

    return none
}

fn ast_expr_call_expr_tag() u64 {
    expr := ast.Expr(ast.CallExpr{})
    slot0 := unsafe { (&u64(&expr))[0] }
    slot1 := unsafe { (&u64(&expr))[1] }
    return sumtype_tag_slot(slot0, slot1)
}

fn is_ast_expr_call_expr_tag(tag u64) bool {
    return tag == ast_expr_call_expr_tag() || tag == u64(4) || tag == u64(118)
}

fn ast_expr_ident_tag() u64 {
    expr := ast.Expr(ast.Ident{})
    slot0 := unsafe { (&u64(&expr))[0] }
    slot1 := unsafe { (&u64(&expr))[1] }
    return sumtype_tag_slot(slot0, slot1)
}

fn is_ast_expr_ident_tag(tag u64) bool {
    return tag == ast_expr_ident_tag() || tag == u64(13) || tag == u64(117)
}

fn stmt_for_in_payload(stmt ast.Stmt) ?ast.ForInStmt {
    match stmt {
        ast.ForInStmt {
            return stmt
        }
        else {}
    }

    slot0 := unsafe { (&u64(&stmt))[0] }
    slot1 := unsafe { (&u64(&stmt))[1] }
    tag := sumtype_tag_slot(slot0, slot1)
    if !is_ast_stmt_for_in_stmt_tag(tag) {
        return none
    }
    data := sumtype_payload_slot(slot0, slot1)
    if data == 0 {
        return none
    }
    return unsafe { *&ast.ForInStmt(voidptr(data)) }
}

fn ast_stmt_for_in_stmt_tag() u64 {
    stmt := ast.Stmt(ast.ForInStmt{})
    slot0 := unsafe { (&u64(&stmt))[0] }
    slot1 := unsafe { (&u64(&stmt))[1] }
    return sumtype_tag_slot(slot0, slot1)
}

fn is_ast_stmt_for_in_stmt_tag(tag u64) bool {
    return tag == ast_stmt_for_in_stmt_tag() || tag == u64(13) || tag == u64(116)
}

fn sumtype_tag_slot(slot0 u64, slot1 u64) u64 {
    if sumtype_slot_is_payload(slot0) {
        return slot1
    }
    return slot0
}

fn sumtype_payload_slot(slot0 u64, slot1 u64) u64 {
    if sumtype_slot_is_payload(slot0) {
        return slot0
    }
    if sumtype_slot_is_payload(slot1) {
        return slot1
    }
    return 0
}

fn sumtype_slot_is_payload(slot u64) bool {
    return slot >= 4096 && slot < 281474976710656
}

fn checker_string_has_valid_data(s string) bool {
    if s.len == 0 {
        return true
    }
    if s.len < 0 || s.len > 1024 {
        return false
    }
    ptr := unsafe { u64(s.str) }
    return ptr >= 4096 && ptr < 281474976710656
}

fn embed_file_helper_type() Type {
    string_fn := Type(fn_with_return_type(empty_fn_type(), Type(string_)))
    bytes_fn := Type(fn_with_return_type(empty_fn_type(), Type(Array{
        elem_type: Type(u8_)
    })))
    data_fn := Type(fn_with_return_type(empty_fn_type(), Type(Pointer{
        base_type: Type(u8_)
    })))
    void_fn := Type(fn_with_return_type(empty_fn_type(), Type(void_)))
    return Type(Struct{
        name:   embed_file_helper_type_name
        fields: [
            Field{
                name: '_data'
                typ:  Type(string_)
            },
            Field{
                name: 'len'
                typ:  Type(int_)
            },
            Field{
                name: 'path'
                typ:  Type(string_)
            },
            Field{
                name: 'apath'
                typ:  Type(string_)
            },
            Field{
                name: 'to_string'
                typ:  string_fn
            },
            Field{
                name: 'str'
                typ:  string_fn
            },
            Field{
                name: 'to_bytes'
                typ:  bytes_fn
            },
            Field{
                name: 'data'
                typ:  data_fn
            },
            Field{
                name: 'free'
                typ:  void_fn
            },
        ]
    })
}

fn is_embed_file_call_expr(expr ast.Expr) bool {
    return match expr {
        ast.CallExpr {
            expr.lhs is ast.Ident && expr.lhs.name == 'embed_file'
        }
        ast.CallOrCastExpr {
            expr.lhs is ast.Ident && expr.lhs.name == 'embed_file'
        }
        else {
            false
        }
    }
}

fn is_comptime_res_call_expr(expr ast.Expr) bool {
    return match expr {
        ast.CallExpr {
            expr.lhs is ast.Ident && expr.lhs.name == 'res'
        }
        ast.CallOrCastExpr {
            expr.lhs is ast.Ident && expr.lhs.name == 'res'
        }
        else {
            false
        }
    }
}

fn is_comptime_env_call_expr(expr ast.Expr) bool {
    return match expr {
        ast.CallExpr {
            expr.lhs is ast.Ident && expr.lhs.name == 'env'
        }
        ast.CallOrCastExpr {
            expr.lhs is ast.Ident && expr.lhs.name == 'env'
        }
        else {
            false
        }
    }
}

fn (mut c Checker) register_method_type(type_name string, method_name string, fn_type FnType) {
    mut methods_for_type := []&Fn{}
    lock c.env.methods {
        if type_name in c.env.methods {
            methods_for_type = unsafe { c.env.methods[type_name] }
            for method in methods_for_type {
                if method.name == method_name {
                    return
                }
            }
        }
        mut obj := &Fn{
            name: method_name
            typ:  Type(fn_type)
        }
        methods_for_type << obj
        c.env.methods[type_name] = methods_for_type
    }
}

fn (mut c Checker) register_flag_enum_methods(enum_type Enum) {
    enum_typ := Type(enum_type)
    enum_param := Parameter{
        name: 'value'
        typ:  enum_typ
    }
    for method_name in ['has', 'all'] {
        c.register_method_type(enum_type.name, method_name, FnType{
            params:      [enum_param]
            return_type: Type(bool_)
        })
    }
    for method_name in ['set', 'clear'] {
        c.register_method_type(enum_type.name, method_name, FnType{
            params:      [enum_param]
            return_type: Type(void_)
        })
    }
    c.register_method_type(enum_type.name, 'zero', FnType{
        return_type: enum_typ
    })
}

fn (mut c Checker) register_enum_methods(enum_type Enum) {
    c.register_method_type(enum_type.name, 'str', FnType{
        return_type: Type(string_)
    })
    if enum_type.is_flag {
        c.register_flag_enum_methods(enum_type)
    }
}

// lookup_method looks up a method by receiver type name and method name
// Returns the method's FnType if found
pub fn (e &Environment) lookup_method(type_name string, method_name string) ?FnType {
    mut methods := []&Fn{}
    rlock e.methods {
        if type_name in e.methods {
            methods = unsafe { e.methods[type_name] }
        }
    }
    for method in methods {
        if method.get_name() == method_name {
            typ := method.get_typ()
            if typ is FnType {
                return typ
            }
        }
    }
    return none
}

// lookup_fn looks up a function by module and name in the environment's scopes
// Returns the function's FnType if found
pub fn (e &Environment) lookup_fn(module_name string, fn_name string) ?FnType {
    mut scope := &Scope(unsafe { nil })
    mut found_scope := false
    lock e.scopes {
        if module_name in e.scopes {
            scope = unsafe { e.scopes[module_name] }
            found_scope = true
        }
    }
    if !found_scope {
        return none
    }
    if obj := scope.lookup_parent(fn_name, 0) {
        if obj is Fn {
            typ := obj.get_typ()
            if typ is FnType {
                return typ
            }
        }
    }
    return none
}

// lookup_local_var looks up a local variable by name in the given scope.
// Walks up the scope chain to find the variable and returns its type.
pub fn (e &Environment) lookup_local_var(scope &Scope, name string) ?Type {
    mut s := unsafe { scope }
    if obj := s.lookup_parent(name, 0) {
        return obj.typ()
    }
    return none
}

// set_fn_scope stores the scope for a function by its qualified name
pub fn (mut e Environment) set_fn_scope(module_name string, fn_name string, scope &Scope) {
    key := if module_name == '' { fn_name } else { '${module_name}__${fn_name}' }
    lock e.fn_scopes {
        e.fn_scopes[key] = scope
    }
}

// get_fn_scope retrieves the scope for a function by its qualified name
pub fn (e &Environment) get_fn_scope(module_name string, fn_name string) ?&Scope {
    key := if module_name == '' { fn_name } else { '${module_name}__${fn_name}' }
    mut scope := &Scope(unsafe { nil })
    mut found_scope := false
    lock e.fn_scopes {
        if key in e.fn_scopes {
            scope = unsafe { e.fn_scopes[key] }
            found_scope = true
        }
    }
    if !found_scope {
        return none
    }
    return scope
}

// get_scope retrieves a module scope by exact module name.
pub fn (e &Environment) get_scope(module_name string) ?&Scope {
    mut scope := &Scope(unsafe { nil })
    mut found_scope := false
    lock e.scopes {
        if module_name in e.scopes {
            scope = unsafe { e.scopes[module_name] }
            found_scope = true
        }
    }
    if !found_scope {
        return none
    }
    return scope
}

// get_fn_scope_by_key retrieves a function scope by its fully-qualified key.
pub fn (e &Environment) get_fn_scope_by_key(key string) ?&Scope {
    mut scope := &Scope(unsafe { nil })
    mut found_scope := false
    lock e.fn_scopes {
        if key in e.fn_scopes {
            scope = unsafe { e.fn_scopes[key] }
            found_scope = true
        }
    }
    if !found_scope {
        return none
    }
    return scope
}

// snapshot_scopes returns a non-shared copy of the scopes map.
pub fn (e &Environment) snapshot_scopes() map[string]&Scope {
    mut result := map[string]&Scope{}
    lock e.scopes {
        // Use .keys() + index lookup instead of `for k, v in` to avoid
        // ARM64 chained-access bug with shared map iteration.
        scope_keys := e.scopes.keys()
        for k in scope_keys {
            v := e.scopes[k] or { continue }
            result[k] = v
        }
    }
    return result
}

// snapshot_methods returns a non-shared copy of the methods map.
pub fn (e &Environment) snapshot_methods() map[string][]&Fn {
    mut result := map[string][]&Fn{}
    lock e.methods {
        method_keys := e.methods.keys()
        for k in method_keys {
            v := e.methods[k] or { continue }
            result[k] = v
        }
    }
    return result
}

// snapshot_fn_scopes returns a non-shared copy of the fn_scopes map.
pub fn (e &Environment) snapshot_fn_scopes() map[string]&Scope {
    mut result := map[string]&Scope{}
    lock e.fn_scopes {
        fn_scope_keys := e.fn_scopes.keys()
        for k in fn_scope_keys {
            v := e.fn_scopes[k] or { continue }
            result[k] = v
        }
    }
    return result
}

pub enum DeferredKind {
    fn_decl
    fn_decl_generic
    struct_decl
    const_decl
}

pub struct Deferred {
pub:
    kind  DeferredKind
    func  fn () = unsafe { nil }
    scope &Scope
}

struct PendingConstField {
    scope &Scope
    field ast.FieldInit
}

struct PendingInterfaceDecl {
    scope &Scope
    decl  ast.InterfaceDecl
}

struct PendingStructDecl {
    scope       &Scope
    module_name string
    decl        ast.StructDecl
}

struct FieldAccessInfo {
    field                    Field
    owner_struct             string
    module_mut_fields        []Field
    module_mut_owner_structs []string
}

struct PendingTypeDecl {
    scope &Scope
    decl  ast.TypeDecl
}

struct PendingFnBody {
    scope         &Scope
    decl          ast.FnDecl
    typ           FnType
    scope_fn_name string
    module_name   string
    flat          &ast.FlatAst   = unsafe { nil }
    flat_decl_id  ast.FlatNodeId = -1
}

struct Checker {
    pref &pref.Preferences
    // info Info
    // TODO: mod
    mod &Module = new_module('main', '')
mut:
    env           &Environment = &Environment{}
    file_set      &token.FileSet
    scope         &Scope = new_scope(unsafe { nil })
    c_scope       &Scope = new_scope(unsafe { nil })
    expected_type ?Type
    // Current file's module name (for saving function scopes)
    cur_file_module string
    // Function root scope - used to flatten local variable types for transformer lookup
    fn_root_scope          &Scope = unsafe { nil }
    fallback_vars          map[string]Type
    receiver_generic_types map[string]map[string]Type
    generic_type_params    map[string][]string
    // when true, function declarations only register signatures and queue body checking
    collect_fn_signatures_only bool
    pending_fn_body_flat       &ast.FlatAst   = unsafe { nil }
    pending_fn_body_flat_id    ast.FlatNodeId = -1
    pending_const_fields       []PendingConstField
    pending_interface_decls    []PendingInterfaceDecl
    pending_struct_decls       []PendingStructDecl
    pending_type_decls         []PendingTypeDecl
    pending_fn_bodies          []PendingFnBody

    generic_params []string
    // TODO: remove once fields/methods with same name
    // are no longer allowed & removed.
    expecting_method bool
    // Temporary recursion guard for debugging expression cycles.
    expr_depth int
    expr_stack []string
    // Whether we are inside an unsafe{} block
    inside_unsafe bool
    // Whether the currently checked expression is directly inside a return
    // statement. Used for result error propagation in `or {}` fallbacks.
    inside_return_stmt bool
    // Ownership tracking: variables that hold owned values
    // (from `.to_owned()` for strings, or any non-Copy value for other types).
    owned_vars map[string]token.Pos // var name -> position where it became owned
    // Display name of each owned variable's type, used in move diagnostics.
    owned_var_types map[string]string // var name -> type display name
    // Variables that have been moved (assigned to another variable)
    moved_vars map[string]MovedVar // var name -> info about the move
    // Functions that return owned values (detected from return statements)
    ownership_fns map[string]bool // fn name -> returns ownership
    // Function parameters that received owned values at call sites
    ownership_fn_params map[string]bool // "fn_name__param_N" -> true
    // Functions that return a specific parameter (index stored, -1 = not set)
    ownership_fn_returns_param map[string]int // fn_name -> parameter index
    // Current function name for ownership tracking
    ownership_cur_fn string
    // Borrow tracking: variables currently borrowed via &
    borrowed_vars map[string][]BorrowInfo // var name -> list of active borrows
    // Drop schedule: per-function list of owned bindings implementing the
    // `Drop` interface. Each entry is the destructor call codegen must emit
    // before the binding's owning scope exits. Populated as `Drop`-typed
    // values are bound; pruned (via the `moved_vars` view) when they are
    // moved or returned. Exposed so the transformer / backends can lower it.
    drop_schedule map[string][]DropEntry
    // Per-fn list of per-return drop snapshots collected during checking,
    // in source order. Reset at fn entry, published to
    // `env.drop_at_returns[publish_key]` at fn exit. Transient — not used
    // outside of fn body checking.
    pending_return_drops [][]DropEntry
    // Source positions for `implements Drop` struct declarations, indexed
    // by struct name. Used to point the "missing drop method" diagnostic at
    // the struct decl rather than at an unrelated use site.
    ownership_drop_decl_positions map[string]token.Pos
    // Consuming-self method registry: `${short_type}__${method_name}` -> true
    // when the method has a by-value receiver (no `&`, no `mut`). Populated
    // by `ownership_prescan_value_receivers` once all method signatures are
    // visible, consulted at every call site to move the receiver of an owned
    // var. See checker_ownership.v.
    ownership_value_receiver_methods map[string]bool
    // Owned-global registry: `global_name` -> display type name. Populated by
    // `ownership_prescan_owned_globals` from `__global` decls whose declared
    // type implements `Owned` (or is an Rc/Arc wrapper). Used to reject moves
    // out of program-wide mutable state, where the compiler can't see across
    // function boundaries to know who else might still hold the binding.
    ownership_owned_globals map[string]string
    // Pass-through fn registry: `fn_name` -> list of parameter indices that
    // the fn returns directly (`return param_i`). Populated by
    // `escape_prescan_passthrough_fns` over opt-in (`[^a]`) fn decls, consulted
    // at every escape site to catch inter-procedural leaks like
    // `return passthrough(&local)`. See checker_escape.v.
    escape_passthrough_fns map[string][]int
}

pub fn Checker.new(prefs &pref.Preferences, file_set &token.FileSet, env &Environment) &Checker {
    mut c_scope := env.c_scope
    if isnil(c_scope) {
        c_scope = new_scope(unsafe { nil })
    }
    return &Checker{
        pref:          unsafe { prefs }
        file_set:      unsafe { file_set }
        env:           unsafe { env }
        c_scope:       c_scope
        expected_type: none
    }
}

// qualify_type_name returns the fully qualified type name with module prefix.
// e.g., "File" in module "ast" becomes "ast__File".
// Builtin types and main module types are not prefixed.
fn (c &Checker) qualify_type_name(name string) string {
    // Don't qualify builtin or main module types
    if c.cur_file_module == 'builtin' || c.cur_file_module == '' || c.cur_file_module == 'main' {
        return name
    }
    return '${c.cur_file_module}__${name}'
}

fn (c &Checker) type_ref_name(expr ast.Expr) string {
    match expr {
        ast.Ident {
            return c.qualify_type_name(expr.name)
        }
        ast.LifetimeExpr {
            return '^' + expr.name
        }
        ast.SelectorExpr {
            return expr.name().replace('.', '__')
        }
        ast.Type {
            if expr is ast.PointerType {
                return c.type_ref_name(expr.base_type)
            }
            return expr.name().replace('.', '__')
        }
        else {
            return expr.name().replace('.', '__')
        }
    }
}

fn (mut c Checker) decl_field_type(expr ast.Expr) Type {
    match expr {
        ast.Ident {
            if typ := builtin_type(expr.name) {
                return typ
            }
            if obj := universe.lookup_parent(expr.name, 0) {
                if typ := object_as_type(obj) {
                    return typ
                }
            }
            qualified_name := c.qualify_type_name(expr.name)
            if typ := c.lookup_type_by_name(qualified_name) {
                return typ
            }
            if typ := c.lookup_type_by_name(expr.name) {
                return typ
            }
        }
        ast.SelectorExpr {
            if typ := c.lookup_type_by_name(expr.name().replace('.', '__')) {
                return typ
            }
        }
        else {}
    }

    return c.type_expr(expr)
}

fn to_optional_type(typ Type) ?Type {
    return typ
}

fn unwrap_map_type(typ Type) ?Map {
    mut cur := typ
    for {
        if type_data_ptr_is_nil(cur) {
            break
        }
        if cur is Pointer {
            cur = (cur as Pointer).base_type
            continue
        }
        if cur is Alias {
            cur = (cur as Alias).base_type
            continue
        }
        if cur is OptionType {
            cur = (cur as OptionType).base_type
            continue
        }
        if cur is ResultType {
            cur = (cur as ResultType).base_type
            continue
        }
        break
    }
    if cur is Map {
        return cur as Map
    }
    return none
}

fn object_from_type(typ Type) Object {
    return TypeObject{
        typ: typ
    }
}

fn object_as_type(obj Object) ?Type {
    if obj is Type {
        return obj
    }
    if obj is TypeObject {
        return obj.typ
    }
    return none
}

fn value_object_from_type(name string, typ Type) Object {
    mut obj := Global{
        name: name
        typ:  Type(void_)
    }
    obj.typ = typ
    return obj
}

fn global_decl_field_is_c_extern(decl ast.GlobalDecl, field ast.FieldDecl) bool {
    return field.name.starts_with('C.') || decl.attributes.has('c_extern')
        || field.attributes.has('c_extern')
}

fn module_storage_object(module_name string, decl ast.GlobalDecl, field ast.FieldDecl, typ Type) Global {
    storage_module := if global_decl_field_is_c_extern(decl, field) { '' } else { module_name }
    mut obj := Global{
        name:      field.name
        mod:       storage_module
        is_public: field.is_public
        is_mut:    field.is_mut
        typ:       Type(void_)
    }
    obj.typ = typ
    return obj
}

fn (mut c Checker) module_storage_predecl_type(field ast.FieldDecl) Type {
    if field.typ !is ast.EmptyExpr {
        if typ := c.module_storage_predecl_type_expr(field.typ) {
            return typ
        }
        return c.type_expr(field.typ)
    }
    match field.value {
        ast.BasicLiteral, ast.StringLiteral {
            return c.expr(field.value)
        }
        else {}
    }

    return Type(int_)
}

fn (mut c Checker) module_storage_predecl_type_expr(expr ast.Expr) ?Type {
    match expr {
        ast.Ident {
            if typ := builtin_type(expr.name) {
                return typ
            }
            if obj := universe.lookup_parent(expr.name, 0) {
                if typ := object_as_type(obj) {
                    return typ
                }
            }
            if typ := c.lookup_type_in_scope_chain(expr.name) {
                return typ
            }
            if typ := c.lookup_type_in_imported_modules(expr.name) {
                return typ
            }
            return Type(NamedType(c.qualify_type_name(expr.name)))
        }
        ast.SelectorExpr {
            parts := selector_expr_parts(expr)
            if parts.len >= 2 {
                module_alias := parts[parts.len - 2]
                tname := parts[parts.len - 1]
                if typ := c.lookup_type_in_module(module_alias, tname) {
                    return typ
                }
            }
            return Type(NamedType(expr.name().replace('.', '__')))
        }
        ast.Type {
            if expr is ast.ArrayType {
                if elem_type := c.module_storage_predecl_type_expr(expr.elem_type) {
                    return Type(Array{
                        elem_type: elem_type
                    })
                }
            }
            if expr is ast.ArrayFixedType {
                if elem_type := c.module_storage_predecl_type_expr(expr.elem_type) {
                    mut len := 0
                    if expr.len is ast.BasicLiteral {
                        if expr.len.kind == .number {
                            len = int(strconv.parse_int(expr.len.value, 0, 64) or { 0 })
                        }
                    } else if expr.len is ast.Ident {
                        if obj := c.scope.lookup_parent(expr.len.name, 0) {
                            if obj is Const {
                                len = obj.int_val
                            }
                        }
                    }
                    return Type(ArrayFixed{
                        len:       len
                        elem_type: elem_type
                    })
                }
            }
            if expr is ast.MapType {
                if key_type := c.module_storage_predecl_type_expr(expr.key_type) {
                    if value_type := c.module_storage_predecl_type_expr(expr.value_type) {
                        return Type(Map{
                            key_type:   key_type
                            value_type: value_type
                        })
                    }
                }
            }
            if expr is ast.OptionType {
                if base_type := c.module_storage_predecl_type_expr(expr.base_type) {
                    return Type(OptionType{
                        base_type: base_type
                    })
                }
            }
            if expr is ast.PointerType {
                if base_type := c.module_storage_predecl_type_expr(expr.base_type) {
                    return Type(Pointer{
                        base_type: base_type
                        lifetime:  expr.lifetime
                    })
                }
            }
            if expr is ast.ResultType {
                if base_type := c.module_storage_predecl_type_expr(expr.base_type) {
                    return Type(ResultType{
                        base_type: base_type
                    })
                }
            }
        }
        else {}
    }

    return none
}

fn (mut c Checker) preregister_module_storage_decl(decl ast.GlobalDecl) {
    for field in decl.fields {
        field_type := c.module_storage_predecl_type(field)
        obj := module_storage_object(c.cur_file_module, decl, field, field_type)
        c.scope.insert(field.name, obj)
    }
}

fn (obj Global) is_module_storage() bool {
    return obj.mod != ''
}

fn (obj Global) requires_explicit_module_storage_mut() bool {
    _ = obj
    // This V2 palier keeps legacy `__global name` mutable on purpose, so
    // existing V2/runtime sources do not need syntax that the V1 parser/vfmt
    // still rejects. `is_mut` remains source metadata for the explicit spelling.
    return false
}

fn (mut c Checker) module_storage_for_lhs(expr ast.Expr) ?Global {
    unwrapped := c.unwrap_expr(expr)
    match unwrapped {
        ast.Ident {
            if obj := c.scope.lookup_parent(unwrapped.name, 0) {
                if obj is Global && obj.is_module_storage() {
                    return obj
                }
            }
        }
        ast.SelectorExpr {
            if unwrapped.lhs is ast.Ident {
                lhs_ident := unwrapped.lhs as ast.Ident
                if lhs_obj := c.scope.lookup_parent(lhs_ident.name, 0) {
                    if lhs_obj is Module {
                        if rhs_obj := lhs_obj.scope.lookup_parent(unwrapped.rhs.name, 0) {
                            if rhs_obj is Global && rhs_obj.is_module_storage() {
                                declaring_mod := if rhs_obj.mod != '' {
                                    rhs_obj.mod
                                } else {
                                    lhs_obj.name
                                }
                                if declaring_mod != c.cur_file_module && !rhs_obj.is_public {
                                    c.error_with_pos('module global `${lhs_ident.name}.${unwrapped.rhs.name}` is private',
                                        unwrapped.pos)
                                    return none
                                }
                                return rhs_obj
                            }
                        }
                    }
                    if lhs_obj is Global && lhs_obj.is_module_storage() {
                        return lhs_obj
                    }
                }
            }
            if storage := c.module_storage_for_lhs(unwrapped.lhs) {
                return storage
            }
        }
        ast.IndexExpr {
            if storage := c.module_storage_for_lhs(unwrapped.lhs) {
                return storage
            }
        }
        else {}
    }

    return none
}

fn (mut c Checker) check_module_storage_assignment(lhs ast.Expr, op token.Token, pos token.Pos) {
    if op == .decl_assign {
        return
    }
    if storage := c.module_storage_for_lhs(lhs) {
        if storage.requires_explicit_module_storage_mut() && !storage.is_mut {
            mut display_name := storage.name
            if storage.mod != '' && !storage.name.starts_with('${storage.mod}.') {
                display_name = '${storage.mod}.${storage.name}'
            }
            c.error_with_pos('cannot assign to immutable module global `${display_name}`; declare it with `__global mut`',
                pos)
        }
    }
}

fn field_owner_module(field Field, owner_struct string) string {
    if field.owner_module != '' {
        return field.owner_module
    }
    if owner_struct.contains('__') {
        return owner_struct.all_before_last('__')
    }
    return ''
}

fn field_access_display(info FieldAccessInfo) string {
    owner_module := field_owner_module(info.field, info.owner_struct)
    struct_name := if info.owner_struct.contains('__') {
        info.owner_struct.all_after_last('__')
    } else {
        info.owner_struct
    }
    if owner_module != '' && struct_name != '' {
        return '${owner_module}.${struct_name}.${info.field.name}'
    }
    if struct_name != '' {
        return '${struct_name}.${info.field.name}'
    }
    return info.field.name
}

fn (mut c Checker) find_field_info(t Type, raw_name string) ?FieldAccessInfo {
    name := if raw_name.len > 0 && raw_name[0] == `@` { raw_name[1..] } else { raw_name }
    match t {
        Alias {
            al := t as Alias
            mut base_type := al.base_type
            if base_type.name() == '' {
                live_base_type := c.resolve_stale_alias(al.name)
                if live_base_type.name() != '' {
                    base_type = live_base_type
                }
            }
            if base_type.name() != '' && base_type.name() != al.name {
                return c.find_field_info(base_type, name)
            }
        }
        Pointer {
            pt := t as Pointer
            return c.find_field_info(pt.base_type, name)
        }
        OptionType {
            ot := t as OptionType
            return c.find_field_info(ot.base_type, name)
        }
        ResultType {
            rt := t as ResultType
            return c.find_field_info(rt.base_type, name)
        }
        NamedType {
            nt := t as NamedType
            concrete_types := c.resolve_active_generic_named_types(nt)
            if concrete_types.len == 1 {
                return c.find_field_info(concrete_types[0], name)
            }
            if concrete_types.len > 1 {
                mut prev_info := FieldAccessInfo{}
                mut found_info := false
                mut has_missing_field := false
                mut has_mismatched_field_type := false
                mut module_mut_fields := []Field{}
                mut module_mut_owner_structs := []string{}
                for concrete_type in concrete_types {
                    info := c.find_field_info(concrete_type, name) or {
                        has_missing_field = true
                        continue
                    }
                    if found_info && info.field.typ.name() != prev_info.field.typ.name() {
                        has_mismatched_field_type = true
                    }
                    if info.module_mut_fields.len > 0 {
                        for i, module_mut_field in info.module_mut_fields {
                            module_mut_fields << module_mut_field
                            if i < info.module_mut_owner_structs.len {
                                module_mut_owner_structs << info.module_mut_owner_structs[i]
                            } else {
                                module_mut_owner_structs << info.owner_struct
                            }
                        }
                    } else if info.field.is_module_mut {
                        module_mut_fields << info.field
                        module_mut_owner_structs << info.owner_struct
                    }
                    prev_info = info
                    found_info = true
                }
                if found_info {
                    if (has_missing_field || has_mismatched_field_type)
                        && module_mut_fields.len == 0 {
                        return none
                    }
                    return FieldAccessInfo{
                        field:                    prev_info.field
                        owner_struct:             prev_info.owner_struct
                        module_mut_fields:        module_mut_fields
                        module_mut_owner_structs: module_mut_owner_structs
                    }
                }
            }
        }
        Struct {
            st := t as Struct
            if st.fields.len == 0 && st.embedded.len == 0 && st.name != '' {
                if obj := c.lookup_type_by_name(st.name) {
                    if obj is Struct {
                        if obj.fields.len > 0 || obj.embedded.len > 0 || obj.name != st.name {
                            if info := c.find_field_info(obj, name) {
                                return info
                            }
                        }
                    }
                }
            }
            for field in st.fields {
                if field.name == name {
                    return FieldAccessInfo{
                        field:        field
                        owner_struct: st.name
                    }
                }
            }
            for embedded_type in st.embedded {
                mut live_type := Type(embedded_type)
                if obj := c.lookup_type_by_name(embedded_type.name) {
                    live_type = obj
                }
                if info := c.find_field_info(live_type, name) {
                    return info
                }
            }
        }
        SumType {
            smt := c.live_sumtype(t as SumType)
            mut prev_info := FieldAccessInfo{}
            mut found_info := false
            mut module_mut_fields := []Field{}
            mut module_mut_owner_structs := []string{}
            for variant in smt.variants {
                mut variant_type := resolve_alias(variant)
                if live_variant := c.lookup_type_by_name(variant_type.name()) {
                    variant_type = resolve_alias(live_variant)
                }
                info := c.find_field_info(variant_type, name) or { return none }
                if found_info && info.field.typ.name() != prev_info.field.typ.name() {
                    return none
                }
                if info.module_mut_fields.len > 0 {
                    for i, module_mut_field in info.module_mut_fields {
                        module_mut_fields << module_mut_field
                        if i < info.module_mut_owner_structs.len {
                            module_mut_owner_structs << info.module_mut_owner_structs[i]
                        } else {
                            module_mut_owner_structs << info.owner_struct
                        }
                    }
                } else if info.field.is_module_mut {
                    module_mut_fields << info.field
                    module_mut_owner_structs << info.owner_struct
                }
                prev_info = info
                found_info = true
            }
            if found_info {
                return FieldAccessInfo{
                    field:                    prev_info.field
                    owner_struct:             prev_info.owner_struct
                    module_mut_fields:        module_mut_fields
                    module_mut_owner_structs: module_mut_owner_structs
                }
            }
        }
        else {}
    }

    return none
}

fn module_mut_field_access_is_external(info FieldAccessInfo, cur_file_module string) bool {
    if _ := module_mut_field_access_external_info(info, cur_file_module) {
        return true
    }
    return false
}

fn module_mut_field_access_has_module_mut(info FieldAccessInfo) bool {
    return info.field.is_module_mut || info.module_mut_fields.len > 0
}

fn module_mut_field_access_external_info(info FieldAccessInfo, cur_file_module string) ?FieldAccessInfo {
    if info.module_mut_fields.len > 0 {
        for i, module_mut_field in info.module_mut_fields {
            owner_struct := if i < info.module_mut_owner_structs.len {
                info.module_mut_owner_structs[i]
            } else {
                info.owner_struct
            }
            variant_info := FieldAccessInfo{
                field:        module_mut_field
                owner_struct: owner_struct
            }
            owner_module := field_owner_module(variant_info.field, variant_info.owner_struct)
            if owner_module != '' && owner_module != cur_file_module {
                return variant_info
            }
        }
        return none
    }
    owner_module := field_owner_module(info.field, info.owner_struct)
    if info.field.is_module_mut && owner_module != '' && owner_module != cur_file_module {
        return info
    }
    return none
}

fn (mut c Checker) check_module_mut_method_value_extraction(lhs ast.Expr, method_type Type, pos token.Pos) {
    if c.expecting_method {
        return
    }
    if method_type is FnType && method_type.is_mut_receiver {
        c.check_module_mut_field_mutation(lhs, pos)
    }
}

fn (mut c Checker) module_mut_field_access_in_expr(expr ast.Expr) ?FieldAccessInfo {
    match expr {
        ast.AsCastExpr {
            return c.module_mut_field_access_in_expr(expr.expr)
        }
        ast.CastExpr {
            return c.module_mut_field_access_in_expr(expr.expr)
        }
        ast.PrefixExpr {
            if expr.op == .mul {
                return c.module_mut_field_access_in_expr(expr.expr)
            }
        }
        else {}
    }

    unwrapped := c.unwrap_expr(expr)
    match unwrapped {
        ast.AsCastExpr {
            return c.module_mut_field_access_in_expr(unwrapped.expr)
        }
        ast.CastExpr {
            return c.module_mut_field_access_in_expr(unwrapped.expr)
        }
        ast.IndexExpr {
            return c.module_mut_field_access_in_expr(unwrapped.lhs)
        }
        ast.SelectorExpr {
            mut lhs_module_mut_info := FieldAccessInfo{}
            mut has_lhs_module_mut_info := false
            if info := c.module_mut_field_access_in_expr(unwrapped.lhs) {
                if module_mut_field_access_is_external(info, c.cur_file_module) {
                    return info
                }
                lhs_module_mut_info = info
                has_lhs_module_mut_info = true
            }
            rhs_name := c.selector_rhs_name(unwrapped)
            if lhs_type := c.expr_type_without_field_smartcast(unwrapped.lhs) {
                if info := c.find_field_info(lhs_type, rhs_name) {
                    if module_mut_field_access_has_module_mut(info) {
                        return info
                    }
                }
            }
            smartcast_lhs_type := c.expr(unwrapped.lhs)
            if info := c.find_field_info(smartcast_lhs_type, rhs_name) {
                if module_mut_field_access_has_module_mut(info) {
                    return info
                }
            }
            if has_lhs_module_mut_info {
                return lhs_module_mut_info
            }
        }
        else {}
    }

    return none
}

fn (mut c Checker) check_module_mut_field_mutation(expr ast.Expr, pos token.Pos) {
    if info := c.module_mut_field_access_in_expr(expr) {
        if external_info := module_mut_field_access_external_info(info, c.cur_file_module) {
            owner_module := field_owner_module(external_info.field, external_info.owner_struct)
            c.error_with_pos('cannot mutate module-mutable field `${field_access_display(external_info)}` outside module `${owner_module}`',
                pos)
        }
    }
}

fn (mut c Checker) check_module_mut_field_mut_arg(expr ast.Expr, pos token.Pos) {
    if info := c.module_mut_field_access_in_expr(expr) {
        if external_info := module_mut_field_access_external_info(info, c.cur_file_module) {
            owner_module := field_owner_module(external_info.field, external_info.owner_struct)
            c.error_with_pos('cannot pass module-mutable field `${field_access_display(external_info)}` as mut outside module `${owner_module}`',
                pos)
        }
    }
}

fn (mut c Checker) check_module_mut_field_mut_ref(expr ast.Expr, pos token.Pos) {
    if info := c.module_mut_field_access_in_expr(expr) {
        if external_info := module_mut_field_access_external_info(info, c.cur_file_module) {
            owner_module := field_owner_module(external_info.field, external_info.owner_struct)
            c.error_with_pos('cannot take mutable reference to module-mutable field `${field_access_display(external_info)}` outside module `${owner_module}`',
                pos)
        }
    }
}

fn (mut c Checker) check_module_mut_call_arg(arg ast.Expr) {
    if arg is ast.ModifierExpr && arg.kind == .key_mut {
        c.check_module_mut_field_mut_arg(arg.expr, arg.pos)
    }
}

fn is_empty_expr(e ast.Expr) bool {
    return e is ast.EmptyExpr
}

fn with_generic_params(fn_type FnType, params []string) FnType {
    return FnType{
        generic_params:  params
        params:          fn_type.params
        return_type:     fn_type.return_type
        is_variadic:     fn_type.is_variadic
        is_mut_receiver: fn_type.is_mut_receiver
        attributes:      fn_type.attributes
        generic_types:   fn_type.generic_types
    }
}

fn empty_channel() Channel {
    return Channel{
        elem_type: none
    }
}

fn empty_fn_type() FnType {
    return FnType{
        return_type: none
    }
}

fn empty_thread() Thread {
    return Thread{
        elem_type: none
    }
}

fn comptime_method_info_type() Type {
    return Type(Struct{
        name:   '__method_info'
        fields: [
            Field{
                name: 'name'
                typ:  Type(string_)
            },
            Field{
                name: 'attrs'
                typ:  Type(Array{
                    elem_type: Type(string_)
                })
            },
            Field{
                name: 'args'
                typ:  Type(Array{
                    elem_type: comptime_function_param_info_type()
                })
            },
            Field{
                name: 'location'
                typ:  Type(string_)
            },
            Field{
                name: 'return_type'
                typ:  comptime_type_info_type()
            },
        ]
    })
}

fn comptime_function_param_info_type() Type {
    return Type(Struct{
        name:   '__function_param_info'
        fields: [
            Field{
                name: 'name'
                typ:  Type(string_)
            },
            Field{
                name: 'typ'
                typ:  comptime_type_info_type()
            },
        ]
    })
}

fn comptime_type_info_ref_type() Type {
    return Type(Struct{
        name: '__type_info'
    })
}

fn comptime_type_info_type() Type {
    return Type(Struct{
        name:   '__type_info'
        fields: [
            Field{
                name: 'name'
                typ:  Type(string_)
            },
            Field{
                name: 'idx'
                typ:  Type(int_)
            },
            Field{
                name: 'typ'
                typ:  comptime_type_info_ref_type()
            },
            Field{
                name: 'unaliased_typ'
                typ:  comptime_type_info_ref_type()
            },
            Field{
                name: 'indirections'
                typ:  Type(u8_)
            },
        ]
    })
}

fn comptime_field_info_type() Type {
    return Type(Struct{
        name:   '__field_info'
        fields: [
            Field{
                name: 'name'
                typ:  Type(string_)
            },
            Field{
                name: 'typ'
                typ:  comptime_type_info_type()
            },
            Field{
                name: 'unaliased_typ'
                typ:  comptime_type_info_type()
            },
            Field{
                name: 'attrs'
                typ:  Type(Array{
                    elem_type: Type(string_)
                })
            },
            Field{
                name: 'is_pub'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_mut'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_embed'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_shared'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_atomic'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_option'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_array'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_map'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_chan'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_enum'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_struct'
                typ:  Type(bool_)
            },
            Field{
                name: 'is_alias'
                typ:  Type(bool_)
            },
            Field{
                name: 'indirections'
                typ:  Type(u8_)
            },
        ]
    })
}

fn comptime_enum_value_info_type() Type {
    return Type(Struct{
        name:   '__enum_value_info'
        fields: [
            Field{
                name: 'name'
                typ:  Type(string_)
            },
            Field{
                name: 'value'
                typ:  Type(int_)
            },
            Field{
                name: 'attrs'
                typ:  Type(Array{
                    elem_type: Type(string_)
                })
            },
        ]
    })
}

fn comptime_type_metadata_selector_type(name string) ?Type {
    return match name {
        'name' {
            Type(string_)
        }
        'idx' {
            Type(int_)
        }
        'typ', 'unaliased_typ' {
            comptime_type_info_type()
        }
        'indirections' {
            Type(u8_)
        }
        'fields' {
            Type(Array{
                elem_type: comptime_field_info_type()
            })
        }
        'methods' {
            Type(Array{
                elem_type: comptime_method_info_type()
            })
        }
        'variants' {
            Type(Array{
                elem_type: comptime_type_info_type()
            })
        }
        'values' {
            Type(Array{
                elem_type: comptime_enum_value_info_type()
            })
        }
        else {
            none
        }
    }
}

fn (c &Checker) is_comptime_type_selector_lhs_ident(name string) bool {
    if name in c.generic_params {
        return true
    }
    for generic_types in c.env.cur_generic_types {
        if name in generic_types {
            return true
        }
    }
    if _ := c.lookup_type_by_name(name) {
        return true
    }
    if _ := c.lookup_type_by_name(c.qualify_type_name(name)) {
        return true
    }
    return false
}

fn fn_with_return_type(fn_type FnType, return_type Type) FnType {
    return FnType{
        generic_params:  fn_type.generic_params
        params:          fn_type.params
        return_type:     to_optional_type(return_type)
        is_variadic:     fn_type.is_variadic
        is_mut_receiver: fn_type.is_mut_receiver
        attributes:      fn_type.attributes
        generic_types:   fn_type.generic_types
    }
}

pub fn (mut c Checker) get_module_scope(module_name string, parent &Scope) &Scope {
    mut scope := &Scope(unsafe { nil })
    lock c.env.scopes {
        if module_name in c.env.scopes {
            scope = unsafe { c.env.scopes[module_name] }
        } else {
            scope = new_scope(parent)
            c.env.scopes[module_name] = scope
        }
    }
    return scope
}

// check_flat is the Phase 2 consumer entry point: accepts a FlatAst directly
// rather than []ast.File. Top-level passes walk the FlatAst and decode only
// the legacy nodes they still need internally.
pub fn (mut c Checker) check_flat(flat &ast.FlatAst) {
    c.register_selector_names_from_flat(flat)
    c.preregister_all_scopes_from_flat(flat)
    c.preregister_all_types_from_flat(flat)
    c.register_imported_symbols_from_flat(flat)
    c.collect_fn_signatures_only = true
    c.preregister_all_fn_signatures_from_flat(flat)
    c.collect_fn_signatures_only = false
    c.register_imported_symbols_from_flat(flat)
    for ff in flat.files {
        c.check_file_from_flat(flat, ff)
    }
    c.process_pending_const_fields()
    $if ownership ? {
        c.ownership_prescan_fn_bodies()
        c.ownership_validate_drop_impls()
        c.lifetime_validate_files_from_flat(flat)
        c.escape_validate_files_from_flat(flat)
    }
    c.process_pending_fn_bodies()
    c.check_struct_field_defaults_from_flat(flat)
    c.check_enum_field_values_from_flat(flat)
}

// register_selector_names_from_flat reads selector_names directly from
// FlatFile entries without rehydrating to legacy ast.File. First example of
// a Phase 2 consumer reading the flat representation in place.
fn (mut c Checker) register_selector_names_from_flat(flat &ast.FlatAst) {
    for ff in flat.files {
        for id, name in ff.selector_names {
            c.env.selector_names[id] = name
        }
    }
}

// register_imported_symbols_from_flat mirrors register_imported_symbols but
// pulls each file's mod + imports through the FlatAst readers.
fn (mut c Checker) register_imported_symbols_from_flat(flat &ast.FlatAst) {
    builtin_scope := c.get_module_scope('builtin', universe)
    for ff in flat.files {
        mod := flat.file_mod(ff)
        mut file_scope := c.get_module_scope(mod, builtin_scope)
        for imp in c.active_file_imports_from_flat(flat, ff) {
            if imp.symbols.len == 0 {
                continue
            }
            import_mod := if imp.is_aliased {
                imp.name.all_after_last('.')
            } else {
                imp.alias
            }
            mut import_scope := c.get_module_scope(import_mod, builtin_scope)
            for symbol in imp.symbols {
                if symbol is ast.Ident {
                    if sym_obj := import_scope.lookup_parent(symbol.name, 0) {
                        if sym_obj is Global && sym_obj.is_module_storage() {
                            continue
                        }
                        file_scope.insert(symbol.name, sym_obj)
                    }
                }
            }
        }
    }
}

// active_file_imports_from_flat returns the import statements declared in a
// FlatFile, including those guarded by comptime `$if` blocks whose condition
// currently evaluates true.
fn (mut c Checker) active_file_imports_from_flat(flat &ast.FlatAst, ff ast.FlatFile) []ast.ImportStmt {
    // s258: walk the file's top-level statement cursors instead of decoding the
    // entire file via top-level statement decoding. This runs per file (preregister_scopes +
    // register_imported_symbols), so the full legacy-AST decode was pure churn;
    // the cursor walk only decodes the tiny comptime `$if` conditions. Mirrors the
    // builder's s253 cursor-native import collection. Removes a legacy-AST decode
    // site (toward dropping the old AST) and cuts flat-path memory.
    file_node := ast.Cursor{
        flat: unsafe { flat }
        id:   ff.file_id
    }
    mut imports := file_node.list_at(1).import_stmts()
    c.collect_active_imports_from_stmts_cursor(file_node.list_at(2), mut imports)
    return imports
}

// collect_active_imports_from_stmts_cursor is the cursor-native mirror of
// collect_active_imports_from_stmts: it appends top-level `import` statements and
// the imports of active comptime `$if` branches, walking the FlatAst directly.
fn (c &Checker) collect_active_imports_from_stmts_cursor(stmts ast.CursorList, mut imports []ast.ImportStmt) {
    for i in 0 .. stmts.len() {
        c.collect_active_imports_from_stmt_cursor(stmts.at(i), mut imports)
    }
}

fn (c &Checker) collect_active_imports_from_stmt_cursor(s ast.Cursor, mut imports []ast.ImportStmt) {
    match s.kind() {
        .stmt_import {
            imports << s.import_stmt()
        }
        .stmt_expr {
            inner := s.edge(0)
            if inner.kind() == .expr_comptime {
                cif := inner.edge(0)
                if cif.kind() == .expr_if {
                    c.collect_active_imports_from_if_cursor(cif, mut imports)
                }
            }
        }
        else {}
    }
}

// collect_active_imports_from_if_cursor mirrors collect_active_imports_from_if_expr.
// expr_if layout: edge0 = cond, edge1 = else_expr, edge2.. = then-branch stmts.
fn (c &Checker) collect_active_imports_from_if_cursor(if_c ast.Cursor, mut imports []ast.ImportStmt) {
    if c.eval_comptime_cond_cursor(if_c.edge(0)) {
        for i in 2 .. if_c.edge_count() {
            c.collect_active_imports_from_stmt_cursor(if_c.edge(i), mut imports)
        }
        return
    }
    else_c := if_c.edge(1)
    if else_c.kind() == .expr_if {
        if else_c.edge(0).kind() == .expr_empty {
            for i in 2 .. else_c.edge_count() {
                c.collect_active_imports_from_stmt_cursor(else_c.edge(i), mut imports)
            }
        } else {
            c.collect_active_imports_from_if_cursor(else_c, mut imports)
        }
    }
}

fn (c &Checker) eval_comptime_cond_cursor(cond ast.Cursor) bool {
    if !cond.is_valid() {
        return false
    }
    match cond.kind() {
        .expr_ident {
            return c.eval_comptime_flag(cond.name())
        }
        .expr_prefix {
            op := unsafe { token.Token(int(cond.aux())) }
            if op == .not {
                return !c.eval_comptime_cond_cursor(cond.edge(0))
            }
        }
        .expr_infix {
            op := unsafe { token.Token(int(cond.aux())) }
            if op == .and {
                return c.eval_comptime_cond_cursor(cond.edge(0))
                    && c.eval_comptime_cond_cursor(cond.edge(1))
            }
            if op == .logical_or {
                return c.eval_comptime_cond_cursor(cond.edge(0))
                    || c.eval_comptime_cond_cursor(cond.edge(1))
            }
        }
        .expr_postfix {
            op := unsafe { token.Token(int(cond.aux())) }
            inner := cond.edge(0)
            if op == .question && inner.kind() == .expr_ident {
                return pref.comptime_optional_flag_value(c.pref, inner.name())
            }
        }
        .expr_paren {
            return c.eval_comptime_cond_cursor(cond.edge(0))
        }
        else {}
    }

    return false
}

// preregister_all_scopes_from_flat mirrors preregister_all_scopes but pulls
// each file's mod + imports through the FlatAst readers, no []ast.File hop.
fn (mut c Checker) preregister_all_scopes_from_flat(flat &ast.FlatAst) {
    for ff in flat.files {
        c.preregister_scopes_from_flat(flat, ff)
    }
}

fn (mut c Checker) preregister_scopes_from_flat(flat &ast.FlatAst, ff ast.FlatFile) {
    builtin_scope := c.get_module_scope('builtin', universe)
    mod := flat.file_mod(ff)
    mod_scope := c.get_module_scope(mod, builtin_scope)
    c.scope = mod_scope
    // add self (own module) for constants. can use own module prefix inside module
    c.scope.insert(mod, Module{
        name:  mod
        scope: c.get_module_scope(mod, builtin_scope)
    })
    // add imports (including comptime-conditional)
    for imp in c.active_file_imports_from_flat(flat, ff) {
        import_mod := if imp.is_aliased { imp.name.all_after_last('.') } else { imp.alias }
        c.scope.insert(imp.alias, Module{
            name:  import_mod
            scope: c.get_module_scope(import_mod, builtin_scope)
        })
    }
    // add C
    c.scope.insert('C', Module{ name: 'C', scope: c.c_scope })
}

// preregister_all_types_from_flat mirrors preregister_all_types but reads
// each file's mod + top-level stmts directly from the FlatAst.
fn (mut c Checker) preregister_all_types_from_flat(flat &ast.FlatAst) {
    for ff in flat.files {
        c.preregister_types_from_flat(flat, ff)
    }
    c.register_imported_symbols_from_flat(flat)
    c.process_pending_struct_decls()
    c.process_pending_type_decls()
    c.process_pending_interface_decls()
}

fn (mut c Checker) preregister_types_from_flat(flat &ast.FlatAst, ff ast.FlatFile) {
    mod := flat.file_mod(ff)
    c.cur_file_module = mod
    mut mod_scope := &Scope(unsafe { nil })
    lock c.env.scopes {
        if mod in c.env.scopes {
            mod_scope = unsafe { c.env.scopes[mod] }
        } else {
            eprintln('warning: scope not found for mod: ${mod}, skipping')
            return
        }
    }
    c.scope = mod_scope
    decls := ast.Cursor{
        flat: unsafe { flat }
        id:   ff.file_id
    }.list_at(2)
    for di in 0 .. decls.len() {
        c.preregister_decl_stmt_from_flat(decls.at(di), true, false)
    }
}

// preregister_all_fn_signatures_from_flat mirrors preregister_all_fn_signatures
// but walks each file's top-level stmt cursors directly from the FlatAst.
fn (mut c Checker) preregister_all_fn_signatures_from_flat(flat &ast.FlatAst) {
    for ff in flat.files {
        c.preregister_fn_signatures_from_flat(flat, ff)
    }
}

fn (mut c Checker) preregister_fn_signatures_from_flat(flat &ast.FlatAst, ff ast.FlatFile) {
    mod := flat.file_mod(ff)
    c.cur_file_module = mod
    mut mod_scope := &Scope(unsafe { nil })
    lock c.env.scopes {
        if mod in c.env.scopes {
            mod_scope = unsafe { c.env.scopes[mod] }
        } else {
            eprintln('warning: scope not found for mod: ${mod}, skipping')
            return
        }
    }
    c.scope = mod_scope
    prev_collect := c.collect_fn_signatures_only
    c.collect_fn_signatures_only = true
    decls := ast.Cursor{
        flat: unsafe { flat }
        id:   ff.file_id
    }.list_at(2)
    for i in 0 .. decls.len() {
        c.preregister_decl_stmt_from_flat(decls.at(i), false, true)
    }
    c.collect_fn_signatures_only = prev_collect
}

fn (mut c Checker) module_storage_predecl_type_from_flat_field(field_c ast.Cursor) Type {
    typ_c := field_c.edge(0)
    if typ_c.is_valid() && typ_c.kind() != .expr_empty {
        typ_expr := typ_c.type_expr()
        if typ := c.module_storage_predecl_type_expr(typ_expr) {
            return typ
        }
        return c.type_expr(typ_expr)
    }
    value_c := field_c.edge(1)
    if typ := c.literal_expr_type_from_cursor(value_c) {
        return typ
    }
    if value_c.kind() in [.expr_basic_literal, .expr_string] {
        return c.expr(value_c.attribute_expr())
    }

    return Type(int_)
}

fn (c &Checker) literal_expr_type_from_cursor(expr ast.Cursor) ?Type {
    if !expr.is_valid() {
        return none
    }
    match expr.kind() {
        .expr_basic_literal {
            kind := unsafe { token.Token(int(expr.aux())) }
            match kind {
                .char {
                    return Type(rune_)
                }
                .key_false, .key_true {
                    return bool_
                }
                .number {
                    if expr.name().contains('.') {
                        return float_literal_
                    }
                    return int_literal_
                }
                else {
                    return none
                }
            }
        }
        .expr_string {
            kind := unsafe { ast.StringLiteralKind(int(expr.aux())) }
            if kind == .c {
                return charptr_
            }
            return Type(string_)
        }
        .expr_paren, .expr_modifier {
            return c.literal_expr_type_from_cursor(expr.edge(0))
        }
        else {}
    }

    return none
}

fn (mut c Checker) register_literal_expr_type_from_cursor(expr ast.Cursor) ?Type {
    typ := c.literal_expr_type_from_cursor(expr) or { return none }
    pos := expr.pos()
    if pos.id > 0 {
        c.env.set_expr_type(pos.id, typ)
    }
    return typ
}

fn match_branch_from_flat_cursor(c ast.Cursor) ast.MatchBranch {
    conds := c.list_at(0)
    mut cond := []ast.Expr{cap: conds.len()}
    for i in 0 .. conds.len() {
        cond << conds.at(i).expr()
    }
    stmt_list := c.list_at(1)
    mut stmts := []ast.Stmt{cap: stmt_list.len()}
    for i in 0 .. stmt_list.len() {
        stmts << stmt_list.at(i).stmt()
    }
    return ast.MatchBranch{
        cond:  cond
        stmts: stmts
        pos:   c.pos()
    }
}

fn match_expr_from_flat_cursor(c ast.Cursor) ast.MatchExpr {
    mut branches := []ast.MatchBranch{cap: c.edge_count() - 1}
    for i in 1 .. c.edge_count() {
        branches << match_branch_from_flat_cursor(c.edge(i))
    }
    return ast.MatchExpr{
        expr:     c.edge(0).expr()
        branches: branches
        pos:      c.pos()
    }
}

fn (mut c Checker) preregister_module_storage_decl_from_flat(stmt_c ast.Cursor) {
    decl := stmt_c.global_decl(false)
    fields := stmt_c.list_at(1)
    for i in 0 .. fields.len() {
        field := fields.at(i)
        field_decl := field.field_decl(false)
        field_type := c.module_storage_predecl_type_from_flat_field(field)
        obj := module_storage_object(c.cur_file_module, decl, field_decl, field_type)
        c.scope.insert(field_decl.name, obj)
    }
}

fn (mut c Checker) check_global_decl_from_flat(stmt_c ast.Cursor) {
    decl := stmt_c.global_decl(false)
    fields := stmt_c.list_at(1)
    for i in 0 .. fields.len() {
        field := fields.at(i)
        field_decl := field.field_decl(false)
        field_typ := field.edge(0).type_expr()
        field_type := if field_typ !is ast.EmptyExpr {
            c.type_expr(field_typ)
        } else {
            value_c := field.edge(1)
            if typ := c.register_literal_expr_type_from_cursor(value_c) {
                typ
            } else {
                c.expr(value_c.expr())
            }
        }
        obj := module_storage_object(c.cur_file_module, decl, field_decl, field_type)
        c.scope.insert_or_update(field_decl.name, obj)
    }
}

fn (mut c Checker) check_expr_stmt_from_flat(stmt_c ast.Cursor) {
    expr_c := stmt_c.edge(0)
    if expr_c.kind() == .expr_match {
        c.match_expr(match_expr_from_flat_cursor(expr_c), false)
        return
    }
    if _ := c.register_literal_expr_type_from_cursor(expr_c) {
        return
    }
    c.expr(expr_c.expr())
}

fn (mut c Checker) check_assert_stmt_from_flat(stmt_c ast.Cursor) {
    expr_c := stmt_c.edge(0)
    if _ := c.register_literal_expr_type_from_cursor(expr_c) {
        // Literal-only asserts do not need legacy expression materialization.
    } else {
        c.expr(expr_c.expr())
    }
    extra := stmt_c.edge(1)
    if extra.is_valid() && extra.kind() != .expr_empty {
        if _ := c.register_literal_expr_type_from_cursor(extra) {
            return
        }
        c.expr(extra.expr())
    }
}

fn (mut c Checker) preregister_decl_stmt_from_flat(stmt_c ast.Cursor, want_types bool, want_fns bool) {
    match stmt_c.kind() {
        .stmt_const_decl {
            if want_types {
                c.decl(ast.Stmt(stmt_c.const_decl()))
            }
        }
        .stmt_enum_decl {
            if want_types {
                c.decl(ast.Stmt(stmt_c.enum_decl(false)))
            }
        }
        .stmt_fn_decl {
            if want_fns {
                decl := stmt_c.fn_decl_signature()
                prev_flat := c.pending_fn_body_flat
                prev_flat_id := c.pending_fn_body_flat_id
                c.pending_fn_body_flat = stmt_c.flat
                c.pending_fn_body_flat_id = stmt_c.id
                c.preregister_fn_signature_stmt(ast.Stmt(decl))
                c.pending_fn_body_flat = prev_flat
                c.pending_fn_body_flat_id = prev_flat_id
            }
        }
        .stmt_global_decl {
            if want_types {
                c.preregister_module_storage_decl_from_flat(stmt_c)
            }
        }
        .stmt_interface_decl {
            if want_types {
                c.decl(ast.Stmt(stmt_c.interface_decl()))
            }
        }
        .stmt_struct_decl {
            if want_types {
                c.decl(ast.Stmt(stmt_c.struct_decl()))
            }
        }
        .stmt_type_decl {
            if want_types {
                c.decl(ast.Stmt(stmt_c.type_decl()))
            }
        }
        .stmt_expr {
            c.preregister_active_comptime_decl_stmt_from_flat(stmt_c, want_types, want_fns)
        }
        else {}
    }
}

fn (mut c Checker) preregister_active_comptime_decl_stmt_from_flat(stmt_c ast.Cursor, want_types bool, want_fns bool) {
    if stmt_c.kind() != .stmt_expr {
        return
    }
    inner := stmt_c.edge(0)
    if inner.kind() != .expr_comptime {
        return
    }
    if_c := inner.edge(0)
    if if_c.kind() != .expr_if {
        return
    }
    c.preregister_active_if_decl_stmts_from_flat(if_c, want_types, want_fns)
}

fn (mut c Checker) preregister_active_if_decl_stmts_from_flat(if_c ast.Cursor, want_types bool, want_fns bool) {
    if c.eval_comptime_cond_cursor(if_c.edge(0)) {
        for i in 2 .. if_c.edge_count() {
            c.preregister_decl_stmt_from_flat(if_c.edge(i), want_types, want_fns)
        }
        return
    }
    else_c := if_c.edge(1)
    if else_c.kind() == .expr_if {
        if else_c.edge(0).kind() == .expr_empty {
            for i in 2 .. else_c.edge_count() {
                c.preregister_decl_stmt_from_flat(else_c.edge(i), want_types, want_fns)
            }
        } else {
            c.preregister_active_if_decl_stmts_from_flat(else_c, want_types, want_fns)
        }
    }
}

// check_file_from_flat mirrors check_file but pulls mod + stmts straight
// from the FlatAst, so the heavy per-file pass no longer needs a rehydrated
// ast.File.
pub fn (mut c Checker) check_file_from_flat(flat &ast.FlatAst, ff ast.FlatFile) {
    mod := flat.file_mod(ff)
    mut sw := time.StopWatch{}
    if c.pref.verbose {
        sw = time.new_stopwatch()
    }
    c.cur_file_module = mod
    mut mod_scope := &Scope(unsafe { nil })
    lock c.env.scopes {
        if mod in c.env.scopes {
            mod_scope = unsafe { c.env.scopes[mod] }
        } else {
            panic('not found for mod: ${mod}')
        }
    }
    c.scope = mod_scope
    decls := ast.Cursor{
        flat: unsafe { flat }
        id:   ff.file_id
    }.list_at(2)
    for di in 0 .. decls.len() {
        dc := decls.at(di)
        match dc.kind() {
            .stmt_const_decl, .stmt_directive, .stmt_empty, .stmt_enum_decl, .stmt_fn_decl,
            .stmt_import, .stmt_interface_decl, .stmt_module, .stmt_struct_decl, .stmt_type_decl,
            .stmt_attributes {
                // Declarations/imports/modules were handled by preregistration, and
                // c.stmt has no extra work for them.
            }
            .stmt_global_decl {
                c.check_global_decl_from_flat(dc)
            }
            .stmt_expr {
                c.check_expr_stmt_from_flat(dc)
            }
            .stmt_assert {
                c.check_assert_stmt_from_flat(dc)
            }
            else {
                c.stmt(dc.stmt())
            }
        }
    }
    if c.pref.verbose {
        check_time := sw.elapsed()
        println('type check ${flat.file_name(ff)}: ${check_time.milliseconds()}ms (${check_time.microseconds()}µs)')
    }
}

// check_struct_field_defaults_from_flat visits struct field default value
// expressions across every FlatFile without rehydrating ast.File.
fn (mut c Checker) check_struct_field_defaults_from_flat(flat &ast.FlatAst) {
    for ff in flat.files {
        mod := flat.file_mod(ff)
        mut mod_scope := &Scope(unsafe { nil })
        lock c.env.scopes {
            if mod in c.env.scopes {
                mod_scope = unsafe { c.env.scopes[mod] }
            } else {
                continue
            }
        }
        c.scope = mod_scope
        c.cur_file_module = mod
        // Walk struct fields directly from the flat decl; only the field type/value
        // expressions that actually need checking are materialized.
        decls := ast.Cursor{
            flat: unsafe { flat }
            id:   ff.file_id
        }.list_at(2)
        for di in 0 .. decls.len() {
            dc := decls.at(di)
            if dc.kind() != .stmt_struct_decl {
                continue
            }
            fields := dc.list_at(4)
            for fi in 0 .. fields.len() {
                field := fields.at(fi)
                value_c := field.edge(1)
                if !value_c.is_valid() || value_c.kind() == .expr_empty {
                    continue
                }
                field_typ := c.type_expr(field.edge(0).type_expr())
                prev_expected := c.expected_type
                c.expected_type = to_optional_type(field_typ)
                if _ := c.register_literal_expr_type_from_cursor(value_c) {
                    c.expected_type = prev_expected
                    continue
                }
                field_value := value_c.expr()
                c.expr(field_value)
                $if ownership ? {
                    c.ownership_consume_expr(field_value, field_value.pos(), 'struct field')
                }
                c.expected_type = prev_expected
            }
        }
    }
}

// check_enum_field_values_from_flat visits enum field value expressions
// across every FlatFile without rehydrating ast.File.
fn (mut c Checker) check_enum_field_values_from_flat(flat &ast.FlatAst) {
    for ff in flat.files {
        mod := flat.file_mod(ff)
        mut mod_scope := &Scope(unsafe { nil })
        lock c.env.scopes {
            if mod in c.env.scopes {
                mod_scope = unsafe { c.env.scopes[mod] }
            } else {
                continue
            }
        }
        c.scope = mod_scope
        c.cur_file_module = mod
        // Walk enum fields directly from the flat decl; only non-empty value
        // expressions are materialized.
        decls := ast.Cursor{
            flat: unsafe { flat }
            id:   ff.file_id
        }.list_at(2)
        for di in 0 .. decls.len() {
            dc := decls.at(di)
            if dc.kind() != .stmt_enum_decl {
                continue
            }
            fields := dc.list_at(2)
            for fi in 0 .. fields.len() {
                field := fields.at(fi)
                value_c := field.edge(1)
                if value_c.is_valid() && value_c.kind() != .expr_empty {
                    if _ := c.register_literal_expr_type_from_cursor(value_c) {
                        continue
                    }
                    c.expr(value_c.expr())
                }
            }
        }
    }
}

pub fn (mut c Checker) check_files(files []ast.File) {
    // c.file_set = unsafe { file_set }
    for file in files {
        for id, name in file.selector_names {
            c.env.selector_names[id] = name
        }
    }
    c.preregister_all_scopes(files)
    c.preregister_all_types(files)
    c.register_imported_symbols(files)
    c.collect_fn_signatures_only = true
    c.preregister_all_fn_signatures(files)
    c.collect_fn_signatures_only = false
    // Re-run symbol imports after function signatures are registered so
    // `import mod { fn_name }` can bind imported functions as well as types.
    c.register_imported_symbols(files)
    for file in files {
        c.check_file(file)
    }
    c.process_pending_const_fields()
    $if ownership ? {
        c.ownership_prescan_fn_bodies()
        c.ownership_validate_drop_impls()
        c.lifetime_validate_files(files)
        c.escape_validate_files(files)
    }
    c.process_pending_fn_bodies()
    c.check_final_default_exprs(files)
}

fn (mut c Checker) register_imported_symbols(files []ast.File) {
    builtin_scope := c.get_module_scope('builtin', universe)
    for file in files {
        mut file_scope := c.get_module_scope(file.mod, builtin_scope)
        for imp in c.active_file_imports(file) {
            if imp.symbols.len == 0 {
                continue
            }
            import_mod := if imp.is_aliased {
                imp.name.all_after_last('.')
            } else {
                imp.alias
            }
            mut import_scope := c.get_module_scope(import_mod, builtin_scope)
            for symbol in imp.symbols {
                if symbol is ast.Ident {
                    if sym_obj := import_scope.lookup_parent(symbol.name, 0) {
                        if sym_obj is Global && sym_obj.is_module_storage() {
                            continue
                        }
                        file_scope.insert(symbol.name, sym_obj)
                    }
                }
            }
        }
    }
}

fn (mut c Checker) active_file_imports(file ast.File) []ast.ImportStmt {
    mut imports := file.imports.clone()
    c.collect_active_imports_from_stmts(file.stmts, mut imports)
    return imports
}

fn (mut c Checker) collect_active_imports_from_stmts(stmts []ast.Stmt, mut imports []ast.ImportStmt) {
    for stmt in stmts {
        match stmt {
            ast.ImportStmt {
                imports << stmt
            }
            ast.ExprStmt {
                if stmt.expr is ast.ComptimeExpr && stmt.expr.expr is ast.IfExpr {
                    c.collect_active_imports_from_if_expr(stmt.expr.expr, mut imports)
                }
            }
            else {}
        }
    }
}

fn (mut c Checker) collect_active_imports_from_if_expr(node ast.IfExpr, mut imports []ast.ImportStmt) {
    if c.eval_comptime_cond(node.cond) {
        c.collect_active_imports_from_stmts(node.stmts, mut imports)
        return
    }
    match node.else_expr {
        ast.IfExpr {
            if node.else_expr.cond is ast.EmptyExpr {
                c.collect_active_imports_from_stmts(node.else_expr.stmts, mut imports)
            } else {
                c.collect_active_imports_from_if_expr(node.else_expr, mut imports)
            }
        }
        else {}
    }
}

pub fn (mut c Checker) check_file(file ast.File) {
    if !c.pref.verbose {
        unsafe {
            goto start_no_time
        }
    }
    mut sw := time.new_stopwatch()
    start_no_time:
    // Track current file's module for function scope saving
    c.cur_file_module = file.mod
    // file_scope := new_scope(c.mod.scope)
    // mut mod_scope := new_scope(c.mod.scope)
    // c.env.scopes[file.mod] = mod_scope
    mut mod_scope := &Scope(unsafe { nil })
    lock c.env.scopes {
        if file.mod in c.env.scopes {
            mod_scope = unsafe { c.env.scopes[file.mod] }
        } else {
            panic('not found for mod: ${file.mod}')
        }
    }
    c.scope = mod_scope
    // mut mod_scope := c.env.scopes[file.mod] or {
    //     panic('scope should exist')
    // }
    // c.scope = mod_scope
    for stmt in file.stmts {
        match stmt {
            // Types and constants are pre-registered in preregister_all_types
            ast.ConstDecl, ast.EnumDecl, ast.InterfaceDecl, ast.StructDecl, ast.TypeDecl {
                continue
            }
            // Functions are pre-registered in preregister_all_fn_signatures
            ast.FnDecl {
                continue
            }
            else {
                c.decl(stmt)
            }
        }
    }
    for stmt in file.stmts {
        c.stmt(stmt)
    }
    if c.pref.verbose {
        check_time := sw.elapsed()
        println('type check ${file.name}: ${check_time.milliseconds()}ms (${check_time.microseconds()}µs)')
    }
}

pub fn (mut c Checker) preregister_scopes(file ast.File) {
    builtin_scope := c.get_module_scope('builtin', universe)

    mod_scope := c.get_module_scope(file.mod, builtin_scope)
    c.scope = mod_scope
    // add self (own module) for constants. can use own module prefix inside module
    c.scope.insert(file.mod, Module{
        name:  file.mod
        scope: c.get_module_scope(file.mod, builtin_scope)
    })
    // add imports
    for imp in c.active_file_imports(file) {
        mod := if imp.is_aliased { imp.name.all_after_last('.') } else { imp.alias }
        c.scope.insert(imp.alias, Module{ name: mod, scope: c.get_module_scope(mod, builtin_scope) })
    }
    // add C
    c.scope.insert('C', Module{ name: 'C', scope: c.c_scope })
}

fn (mut c Checker) preregister_all_scopes(files []ast.File) {
    // builtin_scope := c.get_module_scope('builtin', universe)
    // preregister scopes & imports
    for file in files {
        c.preregister_scopes(file)
        // mod_scope := c.get_module_scope(file.mod, builtin_scope)
        // c.scope = mod_scope
        // // add self (own module) for constants
        // c.scope.insert(file.mod, Module{scope: c.get_module_scope(file.mod, builtin_scope)})
        // // add imports
        // for imp in file.imports {
        //     mod :=  if imp.is_aliased { imp.name.all_after_last('.') } else { imp.alias }
        //     c.scope.insert(imp.alias, Module{scope: c.get_module_scope(mod, builtin_scope)})
        // }
        // // add C
        // c.scope.insert('C', Module{scope: c.c_scope})
    }
}

pub fn (mut c Checker) preregister_types(file ast.File) {
    c.cur_file_module = file.mod
    mut mod_scope := &Scope(unsafe { nil })
    lock c.env.scopes {
        if file.mod in c.env.scopes {
            mod_scope = unsafe { c.env.scopes[file.mod] }
        } else {
            eprintln('warning: scope not found for mod: ${file.mod}, skipping')
            return
        }
    }
    c.scope = mod_scope
    for stmt in file.stmts {
        c.preregister_type_stmt(stmt)
    }
}

fn (mut c Checker) preregister_all_types(files []ast.File) {
    for file in files {
        c.preregister_types(file)
    }
    c.register_imported_symbols(files)
    c.process_pending_struct_decls()
    c.process_pending_type_decls()
    c.process_pending_interface_decls()
}

// preregister_all_fn_signatures registers all function/method signatures
// before processing any function bodies. This ensures methods are available
// when checking code that calls them, regardless of file order.
fn (mut c Checker) preregister_all_fn_signatures(files []ast.File) {
    for file in files {
        c.preregister_fn_signatures(file)
    }
}

pub fn (mut c Checker) preregister_fn_signatures(file ast.File) {
    c.cur_file_module = file.mod
    mut mod_scope := &Scope(unsafe { nil })
    lock c.env.scopes {
        if file.mod in c.env.scopes {
            mod_scope = unsafe { c.env.scopes[file.mod] }
        } else {
            eprintln('warning: scope not found for mod: ${file.mod}, skipping')
            return
        }
    }
    c.scope = mod_scope
    prev_collect := c.collect_fn_signatures_only
    c.collect_fn_signatures_only = true
    for stmt in file.stmts {
        c.preregister_fn_signature_stmt(stmt)
    }
    c.collect_fn_signatures_only = prev_collect
}

fn (mut c Checker) preregister_type_stmt(stmt ast.Stmt) {
    match stmt {
        ast.ConstDecl, ast.EnumDecl, ast.InterfaceDecl, ast.StructDecl, ast.TypeDecl {
            c.decl(stmt)
        }
        ast.GlobalDecl {
            c.preregister_module_storage_decl(stmt)
        }
        ast.ExprStmt {
            c.preregister_active_comptime_decl_stmt(stmt, true, false)
        }
        else {}
    }
}

fn (mut c Checker) preregister_fn_signature_stmt(stmt ast.Stmt) {
    match stmt {
        ast.FnDecl {
            c.decl(stmt)
        }
        ast.ExprStmt {
            c.preregister_active_comptime_decl_stmt(stmt, false, true)
        }
        else {}
    }
}

fn (mut c Checker) preregister_active_comptime_decl_stmt(stmt ast.ExprStmt, want_types bool, want_fns bool) {
    if stmt.expr !is ast.ComptimeExpr {
        return
    }
    cexpr := stmt.expr as ast.ComptimeExpr
    if cexpr.expr !is ast.IfExpr {
        return
    }
    c.preregister_active_if_decl_stmts(cexpr.expr as ast.IfExpr, want_types, want_fns)
}

fn (mut c Checker) preregister_active_if_decl_stmts(node ast.IfExpr, want_types bool, want_fns bool) {
    if c.eval_comptime_cond(node.cond) {
        c.preregister_decl_stmts(node.stmts, want_types, want_fns)
        return
    }
    match node.else_expr {
        ast.IfExpr {
            if node.else_expr.cond is ast.EmptyExpr {
                c.preregister_decl_stmts(node.else_expr.stmts, want_types, want_fns)
            } else {
                c.preregister_active_if_decl_stmts(node.else_expr, want_types, want_fns)
            }
        }
        else {}
    }
}

fn (mut c Checker) preregister_decl_stmts(stmts []ast.Stmt, want_types bool, want_fns bool) {
    for stmt in stmts {
        match stmt {
            ast.ConstDecl, ast.EnumDecl, ast.InterfaceDecl, ast.StructDecl, ast.TypeDecl {
                if want_types {
                    c.decl(stmt)
                }
            }
            ast.FnDecl {
                if want_fns {
                    c.decl(stmt)
                }
            }
            ast.GlobalDecl {
                if want_types {
                    c.preregister_module_storage_decl(stmt)
                }
            }
            ast.ExprStmt {
                c.preregister_active_comptime_decl_stmt(stmt, want_types, want_fns)
            }
            else {}
        }
    }
}

fn (mut c Checker) decl(decl ast.Stmt) {
    match decl {
        ast.ConstDecl {
            for field in decl.fields {
                // c.log('const decl: ${field.name}')
                mut int_val := 0
                if field.value is ast.BasicLiteral {
                    if field.value.kind == .number {
                        int_val = int(strconv.parse_int(field.value.value, 0, 64) or { 0 })
                    }
                }
                obj := Const{
                    mod:     c.mod
                    name:    field.name
                    int_val: int_val
                    // typ: c.expr(field.value)
                }
                c.scope.insert(field.name, obj)
                c.pending_const_fields << PendingConstField{
                    scope: c.scope
                    field: field
                }
            }
        }
        ast.EnumDecl {
            // Enum field value expressions are checked after all module
            // types are pre-registered, so imported enum references like
            // `http.Status.found` can resolve.
            mut fields := []Field{}
            for field in decl.fields {
                fields << Field{
                    name: field.name
                }
            }
            // as_type := decl.as_type !is ast.EmptyExpr { c.expr(decl.as_type) } else { Type(int_) }
            mut is_flag := decl.attributes.has('flag')
            obj := Enum{
                is_flag: is_flag
                name:    c.qualify_type_name(decl.name)
                fields:  fields
            }
            enum_type := Type(obj)
            c.scope.insert(decl.name, object_from_type(enum_type))
            c.scope.insert_type(decl.name, enum_type)
            c.register_enum_methods(obj)
        }
        ast.FnDecl {
            c.fn_decl(decl)
        }
        ast.GlobalDecl {
            for field in decl.fields {
                mut field_type := Type(int_)
                if field.typ !is ast.EmptyExpr {
                    field_type = c.type_expr(field.typ)
                } else if field.value !is ast.EmptyExpr {
                    field_type = c.expr(field.value)
                }
                obj := module_storage_object(c.cur_file_module, decl, field, field_type)
                c.scope.insert_or_update(field.name, obj)
            }
        }
        ast.InterfaceDecl {
            // TODO:
            obj := Interface{
                name: c.qualify_type_name(decl.name)
            }
            interface_type := Type(obj)
            c.scope.insert(decl.name, object_from_type(interface_type))
            c.scope.insert_type(decl.name, interface_type)
            c.pending_interface_decls << PendingInterfaceDecl{
                scope: c.scope
                decl:  decl
            }
        }
        ast.StructDecl {
            // c.log(' # StructDecl: ${decl.name}')
            // TODO: clean this up
            c.pending_struct_decls << PendingStructDecl{
                scope:       c.scope
                module_name: c.cur_file_module
                decl:        decl
            }
            // c.log('struct decl: ${decl.name}')
            // Don't qualify C types
            qualified_name := if decl.language == .c {
                decl.name
            } else {
                c.qualify_type_name(decl.name)
            }
            generic_params := generic_param_names_from_exprs(decl.generic_params)
            if generic_params.len > 0 {
                c.generic_type_params[decl.name] = generic_params.clone()
                c.generic_type_params[qualified_name] = generic_params.clone()
            }
            obj := Struct{
                name:           qualified_name
                generic_params: generic_params
                is_soa:         decl.attributes.has('soa')
            }
            mut typ := Type(obj)
            // TODO: proper
            if decl.language == .c {
                // c_scope is shared across parallel preregister workers; lock.
                c.env.c_scope_mu.lock()
                c.c_scope.insert(decl.name, object_from_type(typ))
                c.c_scope.insert_type(decl.name, typ)
                c.env.c_scope_mu.unlock()
            } else {
                c.scope.insert(decl.name, object_from_type(typ))
                c.scope.insert_type(decl.name, typ)
            }
        }
        ast.TypeDecl {
            generic_params := generic_param_names_from_exprs(decl.generic_params)
            if generic_params.len > 0 {
                qualified_name := c.qualify_type_name(decl.name)
                c.generic_type_params[decl.name] = generic_params.clone()
                c.generic_type_params[qualified_name] = generic_params.clone()
            }
            // alias
            if decl.variants.len == 0 {
                alias_type := Alias{
                    name: c.qualify_type_name(decl.name)
                }
                mut typ := Type(alias_type)
                c.scope.insert(decl.name, object_from_type(typ))
                c.scope.insert_type(decl.name, typ)
                c.pending_type_decls << PendingTypeDecl{
                    scope: c.scope
                    decl:  decl
                }
            }
            // sum type
            else {
                sum_type := SumType{
                    name:           c.qualify_type_name(decl.name)
                    generic_params: generic_params
                    // variants: decl.variants
                }
                mut typ := Type(sum_type)
                c.scope.insert(decl.name, object_from_type(typ))
                c.scope.insert_type(decl.name, typ)
                c.pending_type_decls << PendingTypeDecl{
                    scope: c.scope
                    decl:  decl
                }
            }
        }
        else {}
    }
}

fn (mut c Checker) check_types(exp_type Type, got_type Type) bool {
    // Prefer name-based equality first so recursive composite types
    // (e.g. `map[string]Any` where `Any` contains `map[string]Any`)
    // do not recurse indefinitely through structural `==`.
    if same_type_name(exp_type, got_type) {
        return true
    }
    exp_name := exp_type.name()
    got_name := got_type.name()
    if exp_name != '' && exp_name == got_name {
        return true
    }
    if exp_name == 'int' && (got_name == 'Duration' || got_name == 'time__Duration') {
        return true
    }
    if got_name == 'int' && (exp_name == 'Duration' || exp_name == 'time__Duration') {
        return true
    }
    // unwrap aliases for compatibility checks
    if exp_type is Alias {
        exp_al := exp_type as Alias
        mut exp_base := exp_al.base_type
        if exp_base.name() == '' && exp_al.name != '' {
            // Stale alias - re-resolve base type from scope
            exp_base = c.resolve_stale_alias(exp_al.name)
        }
        if exp_base.name() != '' {
            return c.check_types(exp_base, got_type)
        }
    }
    if got_type is Alias {
        got_al := got_type as Alias
        mut got_base := got_al.base_type
        if got_base.name() == '' && got_al.name != '' {
            // Stale alias - re-resolve base type from scope
            got_base = c.resolve_stale_alias(got_al.name)
        }
        if got_base.name() != '' {
            return c.check_types(exp_type, got_base)
        }
    }
    if exp_type is Interface && c.type_satisfies_interface(got_type, exp_type) {
        return true
    }
    if exp_type is Array && got_type is Array {
        return c.check_types(exp_type.elem_type, got_type.elem_type)
    }
    if exp_type is ArrayFixed && got_type is ArrayFixed {
        return exp_type.len == got_type.len && c.check_types(exp_type.elem_type, got_type.elem_type)
    }
    // Self-hosted binaries can occasionally lose primitive literal flags while
    // still preserving stable type names like `int_literal`/`float_literal`.
    if exp_name in ['i8', 'i16', 'int', 'i64', 'u8', 'u16', 'u32', 'u64', 'isize', 'usize', 'byte', 'rune', 'f32', 'f64']
        && got_name in ['int_literal', 'float_literal'] {
        return true
    }
    // Treat all `string` spellings as equivalent:
    // builtin string type, legacy `struct string`, and aliases named `string`.
    if c.is_string_like(exp_type) && c.is_string_like(got_type) {
        return true
    }
    if is_duration_type_name(exp_name) && (got_type.is_number() || is_numeric_type_name(got_name)) {
        return true
    }
    if is_duration_type_name(got_name) && (exp_type.is_number() || is_numeric_type_name(exp_name)) {
        return true
    }
    // allow nil in expression contexts that expect pointer-like values
    if got_type is Nil {
        match exp_type {
            FnType, Interface, Pointer {
                return true
            }
            else {}
        }
    }
    // number literals
    if exp_type.is_number() && got_type.is_number_literal() {
        return true
    }
    if exp_type.is_number_literal() && got_type.is_number() {
        return true
    }
    // primitives: allow numeric type promotions (e.g. int→f64, int→u16)
    if exp_type is Primitive && got_type is Primitive {
        exp_prim := exp_type as Primitive
        got_prim := got_type as Primitive
        if exp_prim.is_number() && got_prim.is_number() {
            return true
        }
    }
    if got_type is Char || got_type is Rune {
        if exp_type is Primitive {
            exp_prim := exp_type as Primitive
            if exp_prim.is_integer() {
                return true
            }
        }
    }
    // sum type: accept any variant type
    if exp_type is SumType {
        if c.sum_type_accepts_variant(exp_type as SumType, got_type) {
            return true
        }
    }
    // voidptr: any pointer type is assignable to voidptr (Pointer{void_})
    if exp_type is Pointer {
        exp_pt := exp_type as Pointer
        if exp_pt.base_type is Void {
            if got_type is Pointer {
                return true
            }
        }
    }

    return false
}

fn (mut c Checker) type_satisfies_interface(got_type Type, iface Interface) bool {
    mut actual_type := resolve_alias(got_type)
    if actual_type is Pointer {
        actual_type = Type(Pointer{
            base_type: resolve_alias(actual_type.base_type)
        })
    } else if actual_type is Struct && actual_type.name != '' {
        if live_type := c.lookup_type_by_name(actual_type.name) {
            if live_type is Struct && (live_type.fields.len > actual_type.fields.len
                || live_type.embedded.len > actual_type.embedded.len
                || live_type.implements.len > actual_type.implements.len) {
                actual_type = live_type
            }
        }
    }
    if actual_type is Struct && c.struct_implements_name(actual_type, iface.name) {
        return true
    }
    if actual_type is Interface && actual_type.name == iface.name {
        return true
    }

    iface_fields := if iface.fields.len == 0 && iface.name != '' {
        c.resolve_interface_fields(iface)
    } else {
        iface.fields
    }
    for field in iface_fields {
        if field.name == 'type_name' {
            continue
        }
        field_type := resolve_alias(field.typ)
        if field.is_interface_method && field_type is FnType {
            method_type := if actual_type is Interface {
                actual_field := c.find_interface_field(actual_type, field.name, true) or {
                    return false
                }
                actual_field.typ
            } else {
                c.lookup_method_direct(actual_type, field.name) or { return false }
            }
            if method_type !is FnType {
                return false
            }
            if !c.fn_types_compatible(field_type, method_type as FnType) {
                return false
            }
            continue
        }
        member_type := if info := c.find_field_info(actual_type, field.name) {
            info.field.typ
        } else if actual_type is Interface {
            actual_field := c.find_interface_field(actual_type, field.name, false) or {
                return false
            }
            actual_field.typ
        } else {
            return false
        }
        if !c.check_types(field_type, member_type) {
            return false
        }
    }
    return true
}

fn (mut c Checker) fn_types_compatible(expected FnType, got FnType) bool {
    if expected.params.len != got.params.len || expected.is_variadic != got.is_variadic {
        return false
    }
    for i, expected_param in expected.params {
        got_param := got.params[i]
        if !c.check_types(expected_param.typ, got_param.typ) {
            return false
        }
    }
    expected_return := expected.return_type or { Type(void_) }
    got_return := got.return_type or { Type(void_) }
    return c.check_types(expected_return, got_return)
}

fn (c &Checker) live_sumtype(smt SumType) SumType {
    if smt.name == '' || !checker_string_has_valid_data(smt.name) {
        return smt
    }
    if live_type := c.lookup_type_by_name(smt.name) {
        if live_type is SumType {
            live_smt := live_type as SumType
            if live_smt.variants.len > smt.variants.len {
                return live_smt
            }
        }
    }
    return smt
}

fn (c &Checker) sum_type_accepts_variant(smt SumType, got_type Type) bool {
    live_smt := c.live_sumtype(smt)
    got_name := got_type.name()
    got_name_ok := checker_string_has_valid_data(got_name)
    for variant in live_smt.variants {
        mut variant_type := resolve_alias(variant)
        variant_name := variant_type.name()
        if checker_string_has_valid_data(variant_name) {
            if live_variant := c.lookup_type_by_name(variant_name) {
                variant_type = resolve_alias(live_variant)
            }
        }
        resolved_variant_name := variant_type.name()
        if got_name_ok && checker_string_has_valid_data(resolved_variant_name)
            && resolved_variant_name == got_name {
            return true
        }
        if variant_type is SumType {
            if c.sum_type_accepts_variant(variant_type as SumType, got_type) {
                return true
            }
        }
    }
    return false
}

fn (c &Checker) is_string_struct(typ Type) bool {
    if typ is Struct {
        return typ.name == 'string' || typ.name.ends_with('__string')
    }
    return false
}

fn (c &Checker) is_string_like(typ Type) bool {
    return typ.name() == 'string' || c.is_string_struct(typ)
}

fn (c &Checker) is_ierror_like(typ Type) bool {
    if typ is Interface {
        if type_data_ptr_is_nil(typ) {
            return false
        }
        iface := typ as Interface
        return iface.name == 'IError' || iface.name == 'builtin__IError'
    }
    return false
}

fn is_duration_type_name(name string) bool {
    return name == 'Duration' || name.ends_with('__Duration')
}

fn is_numeric_type_name(name string) bool {
    return name in ['i8', 'i16', 'int', 'i64', 'u8', 'u16', 'u32', 'u64', 'isize', 'usize', 'byte',
        'rune', 'f32', 'f64', 'int_literal', 'float_literal']
}

fn (c &Checker) can_or_block_propagate_error(raw_cond_type Type, cond ast.Expr, err_type Type) bool {
    if !c.is_ierror_like(err_type) {
        return false
    }
    mut expected_is_result := false
    if expected_type := c.expected_type {
        expected_is_result = expected_type is ResultType
    }
    if raw_cond_type is ResultType {
        return true
    }
    if expected_is_result && c.inside_return_stmt {
        return true
    }
    return expected_is_result && cond is ast.IndexExpr
        && (cond as ast.IndexExpr).expr is ast.RangeExpr && c.is_string_like(raw_cond_type)
}

fn (mut c Checker) insert_error_scope_vars() {
    mut err_type := Type(string_)
    if obj := c.scope.lookup_parent('IError', 0) {
        err_type = obj.typ()
    }
    c.scope.insert('err', object_from_type(err_type))
    c.scope.insert('errcode', object_from_type(Type(int_)))
}

fn (c &Checker) is_string_iterable_type(typ Type) bool {
    mut cur := typ
    for {
        if type_data_ptr_is_nil(cur) {
            return false
        }
        if cur is Alias {
            cur = (cur as Alias).base_type
            continue
        }
        if cur is Pointer {
            cur = (cur as Pointer).base_type
            continue
        }
        break
    }
    return cur is String || c.is_string_struct(cur)
}

fn (c &Checker) for_in_value_type(iter_type Type) Type {
    if c.is_string_iterable_type(iter_type) {
        return Type(u8_)
    }
    return iter_type.value_type()
}

fn (mut c Checker) expr(expr ast.Expr) Type {
    c.expr_depth++
    if c.expr_depth > max_checker_expr_depth {
        c.expr_depth--
        return Type(void_)
    }
    mut pushed_stack := false
    if expr !is ast.ArrayInitExpr {
        c.expr_stack << 'expr'
        pushed_stack = true
    }
    if c.expr_depth > 2000 {
        start := if c.expr_stack.len > 40 { c.expr_stack.len - 40 } else { 0 }
        eprintln('checker expr recursion depth=${c.expr_depth}')
        for i := start; i < c.expr_stack.len; i++ {
            eprintln('  ${c.expr_stack[i]}')
        }
        panic('checker expr recursion')
    }
    typ := c.expr_impl(expr)
    // Store the computed type in the environment for expressions with positions.
    // SSA needs contextual array literal types, for example struct fields of
    // type []ast.Expr initialized with [ast.CallExpr{...}].
    pos := expr.pos()
    if pos.is_valid() {
        c.env.set_expr_type(pos.id, typ)
    }
    c.expr_depth--
    if pushed_stack && c.expr_stack.len > 0 {
        c.expr_stack.delete_last()
    }
    return typ
}

fn (mut c Checker) generic_args_expr(expr ast.GenericArgs) Type {
    // Keep this logic out of expr_impl to avoid huge stack frames in the
    // generated native checker path.
    mut name := ''
    match expr.lhs {
        ast.Ident {
            name = expr.lhs.name
        }
        ast.SelectorExpr {
            name = expr.lhs.rhs.name
        }
        else {}
    }

    lhs_type := c.expr(expr.lhs)
    if lhs_type is FnType {
        fn_type := lhs_type as FnType
        // If function already has generic params (from declaration), preserve them
        // but return a fresh copy so call_expr doesn't mutate the shared module scope object.
        if fn_type.generic_params.len > 0 {
            return Type(FnType{
                generic_params:  fn_type.generic_params
                params:          fn_type.params
                return_type:     fn_type.return_type
                is_variadic:     fn_type.is_variadic
                is_mut_receiver: fn_type.is_mut_receiver
                attributes:      fn_type.attributes
            })
        }
        mut args := []string{}
        for arg in expr.args {
            args << c.expr(arg).name()
        }
        return Type(with_generic_params(fn_type, args))
    }
    // If the LHS is indexable (array, map, string), re-interpret as IndexExpr.
    // The parser sometimes produces nested GenericArgs for nested indexing
    // like `a[b[c[d]]]` when it should produce nested IndexExprs.
    if expr.args.len == 1 && c.is_indexable_type(lhs_type) && !c.is_generic_struct_type(lhs_type) {
        return c.expr(ast.Expr(ast.IndexExpr{
            lhs:  expr.lhs
            expr: expr.args[0]
            pos:  expr.pos
        }))
    }
    if generic_struct := c.generic_struct_template(lhs_type) {
        return c.instantiate_generic_struct(generic_struct, expr.args)
    }

    mut args := []string{}
    for arg in expr.args {
        args << c.expr(arg).name()
    }

    return Struct{
        name:           name
        generic_params: args
    }
}

fn (mut c Checker) index_expr(expr ast.IndexExpr) Type {
    lhs_type := c.expr(expr.lhs)
    c.expr(expr.expr)
    // TODO: make sure lhs_type is indexable
    // if !lhs_type.is_indexable() { c.error('cannot index ${lhs_type.name()}') }
    return c.index_expr_result_type(lhs_type, expr)
}

fn (mut c Checker) index_expr_result_type(lhs_type Type, expr ast.IndexExpr) Type {
    // For slicing (RangeExpr), return the same type as the container
    // For single index, return the element type
    is_range := expr.expr is ast.RangeExpr
    mut container_type := lhs_type
    // Const/global strings can be represented as pointer-to-string in some paths.
    // For direct indexing/slicing expressions, treat them as plain strings.
    // But inside unsafe blocks, &string is used as pointer-to-string-array,
    // so indexing should yield string (via value_type on Pointer).
    mut lhs_check := resolve_alias(lhs_type)
    if lhs_check is Pointer && !c.inside_unsafe {
        mut ptr_base := resolve_alias((lhs_check as Pointer).base_type)
        if ptr_base is String || (ptr_base is Struct && (ptr_base.name == 'string'
            || ptr_base.name.ends_with('__string'))) {
            is_explicit_deref := expr.lhs is ast.PrefixExpr
                && (expr.lhs as ast.PrefixExpr).op == .mul
            if !is_explicit_deref {
                container_type = Type(string_)
            }
        }
    }
    if !is_range && c.inside_unsafe {
        if ptr_value_type := indexed_pointer_value_type(container_type) {
            return ptr_value_type
        }
    }
    value_type := if is_range {
        resolved_container := resolve_alias(container_type)
        if resolved_container is ArrayFixed {
            arr_fixed := resolved_container as ArrayFixed
            Type(Array{
                elem_type: arr_fixed.elem_type
            })
        } else {
            container_type
        }
    } else {
        if c.is_string_iterable_type(container_type) {
            Type(u8_)
        } else {
            container_type.value_type()
        }
    }
    // c.log('IndexExpr: ${value_type.name()} / ${lhs_type.name()}')
    return value_type
}

fn indexed_pointer_value_type(typ Type) ?Type {
    resolved := resolve_alias(typ)
    if resolved is Pointer {
        ptr := resolved as Pointer
        base := resolve_alias(ptr.base_type)
        if base is String {
            return Type(string_)
        }
        if base is Struct && (base.name == 'string' || base.name.ends_with('__string')) {
            return Type(string_)
        }
        if base is Array {
            return base.elem_type
        }
        if base is ArrayFixed {
            return base.elem_type
        }
        if base is Map {
            return base.value_type
        }
        return ptr.base_type
    }
    return none
}

fn (mut c Checker) scope_type_for_ident_expr(expr ast.Expr) ?Type {
    match expr {
        ast.Ident {
            if obj := c.scope.lookup_parent(expr.name, 0) {
                return obj.typ()
            }
        }
        else {}
    }

    return none
}

fn (mut c Checker) enum_type_for_shorthand_field(field_name string) ?Type {
    mut cur_scope := c.scope
    for cur_scope != unsafe { nil } {
        for _, obj in cur_scope.objects {
            typ := obj.typ()
            if typ is Enum {
                for field in typ.fields {
                    if field.name == field_name {
                        return typ
                    }
                }
            }
        }
        cur_scope = cur_scope.parent
    }
    lock c.env.scopes {
        for _, scope in c.env.scopes {
            for _, obj in scope.objects {
                typ := obj.typ()
                if typ is Enum {
                    for field in typ.fields {
                        if field.name == field_name {
                            return typ
                        }
                    }
                }
            }
        }
    }
    return none
}

fn (mut c Checker) enum_type_for_in_rhs_shorthand(rhs ast.Expr) ?Type {
    if rhs is ast.ArrayInitExpr && rhs.exprs.len > 0 {
        first := rhs.exprs[0]
        if first is ast.SelectorExpr && first.lhs is ast.EmptyExpr {
            return c.enum_type_for_shorthand_field(first.rhs.name)
        }
    }
    if rhs is ast.SelectorExpr && rhs.lhs is ast.EmptyExpr {
        return c.enum_type_for_shorthand_field(rhs.rhs.name)
    }
    return none
}

fn (c &Checker) is_empty_selector_expr(expr ast.Expr) bool {
    match expr {
        ast.SelectorExpr {
            return expr.lhs is ast.EmptyExpr
        }
        else {
            return false
        }
    }
}

fn (mut c Checker) set_infix_expected_type(expr ast.InfixExpr, lhs_type Type) {
    if lhs_type is Enum {
        c.expected_type = to_optional_type(Type(lhs_type))
        return
    }
    lhs_base := lhs_type.base_type()
    if lhs_base is Enum {
        c.expected_type = to_optional_type(Type(lhs_base))
        return
    }
    if expr.op == .left_shift {
        if lhs_type is Array {
            c.expected_type = to_optional_type(lhs_type.elem_type)
            return
        }
        if lhs_base is Array {
            c.expected_type = to_optional_type((lhs_base as Array).elem_type)
            return
        }
    }
    if expr.op in [.key_in, .not_in] && lhs_type !is Void {
        // Support typed arrays in `x in [...]` / `x !in [...]` when the lhs
        // enum arrives wrapped (e.g. aliases) or through non-enum wrappers.
        mut in_lhs_type := if lhs_type is Pointer {
            (lhs_type as Pointer).base_type
        } else {
            lhs_type
        }
        if in_lhs_type.name() == '' {
            if rhs_enum_type := c.enum_type_for_in_rhs_shorthand(expr.rhs) {
                in_lhs_type = rhs_enum_type
            }
        }
        if in_lhs_type.name() == '' {
            return
        }
        c.expected_type = to_optional_type(in_lhs_type)
        return
    }
    if expr.op in [.key_in, .not_in] {
        // Fallback: use scope type for enum shorthand in `in` expressions
        // when lhs expression type inference produced void.
        if lhs_ident_type := c.scope_type_for_ident_expr(expr.lhs) {
            c.expected_type = to_optional_type(lhs_ident_type)
        }
        return
    }
    if c.is_empty_selector_expr(expr.rhs) {
        // Generic enum-shorthand fallback for comparisons like `mode == .x`.
        if lhs_type !is Void {
            c.expected_type = to_optional_type(lhs_type)
        } else if lhs_ident_type := c.scope_type_for_ident_expr(expr.lhs) {
            c.expected_type = to_optional_type(lhs_ident_type)
        }
    }
}

fn (mut c Checker) infix_rhs_type(expr ast.InfixExpr) Type {
    if expr.op == .and {
        // In `a is T && a.field ...`, RHS is evaluated only when the smart-cast is true.
        // Type-check RHS in a nested scope with casts from LHS applied.
        c.open_scope()
        sc_names, sc_types := c.extract_smartcasts(expr.lhs)
        c.apply_smartcasts(sc_names, sc_types)
        rhs_type := c.expr(expr.rhs)
        c.close_scope()
        return rhs_type
    }
    return c.expr(expr.rhs)
}

fn (mut c Checker) logical_and_expr_part(expr ast.Expr) {
    unwrapped := c.unwrap_expr(expr)
    if unwrapped is ast.InfixExpr && unwrapped.op == .and {
        c.logical_and_expr_part(unwrapped.lhs)
        c.logical_and_expr_part(unwrapped.rhs)
        return
    }
    c.expr(expr)
    sc_names, sc_types := c.extract_smartcasts(unwrapped)
    c.apply_smartcasts(sc_names, sc_types)
}

fn (c &Checker) unalias_type(t Type) Type {
    next := t.base_type()
    if next is Alias {
        return c.unalias_type(next)
    }
    return next
}

fn (c &Checker) promote_infix_numeric_type(lhs_type Type, rhs_type Type) Type {
    // Promote untyped numeric literals to the concrete numeric type on the other side.
    // This keeps expressions like `1 + i64_var` and `24 * time.hour` typed correctly.
    rhs_concrete := c.unalias_type(rhs_type)
    if lhs_type.is_number_literal() && rhs_concrete.is_number() && !rhs_concrete.is_number_literal() {
        return rhs_type
    }
    lhs_concrete := c.unalias_type(lhs_type)
    if rhs_type.is_number_literal() && lhs_concrete.is_number() && !lhs_concrete.is_number_literal() {
        return lhs_type
    }
    return lhs_type
}

fn (mut c Checker) infix_expr(expr ast.InfixExpr) Type {
    if expr.op == .and {
        c.open_scope()
        c.logical_and_expr_part(expr)
        c.close_scope()
        return bool_
    }
    lhs_type := c.expr(expr.lhs)
    // Preserve enum context for shorthand RHS values like `.void_t`.
    expected_type := c.expected_type
    c.set_infix_expected_type(expr, lhs_type)
    rhs_type := c.infix_rhs_type(expr)
    $if ownership ? {
        lhs_base := lhs_type.base_type()
        if expr.op == .left_shift && (lhs_type is Array || lhs_base is Array) {
            c.ownership_consume_expr(expr.rhs, expr.rhs.pos(), 'array append')
        }
    }
    lhs_base_for_mut := lhs_type.base_type()
    if expr.op == .left_shift && (lhs_type is Array || lhs_base_for_mut is Array) {
        c.check_module_mut_field_mutation(expr.lhs, expr.pos)
    }
    c.expected_type = expected_type
    if expr.op.is_comparison() {
        return bool_
    }
    // Check for operator overloading on struct types
    resolved_lhs := resolve_alias(lhs_type)
    if resolved_lhs is Struct {
        resolved_lhs_st := resolved_lhs as Struct
        op_name := expr.op.str()
        tname := resolved_lhs_st.name
        mut methods := []&Fn{}
        rlock c.env.methods {
            if tname in c.env.methods {
                methods = unsafe { c.env.methods[tname] }
            }
        }
        for method in methods {
            if method.name == op_name {
                method_type := c.specialize_method_type_for_receiver(method.typ, lhs_type, op_name)
                if method_type is FnType {
                    method_ft := method_type as FnType
                    if ret := method_ft.return_type {
                        return ret
                    }
                }
                return method_type
            }
        }
    }
    return c.promote_infix_numeric_type(lhs_type, rhs_type)
}

fn (mut c Checker) init_expr(expr ast.InitExpr) Type {
    // TODO: try handle this from expr
    // mut typ_expr := expr.typ
    // if expr.typ is ast.GenericArgs {
    //     typ_expr = expr.typ.lhs
    // }
    typ := c.expr(expr.typ)
    // Unwrap aliases to get the base struct type for field lookups.
    mut resolved := resolve_alias(typ)
    // Visit field value expressions to store their types in the environment
    resolved_imm := resolved
    if resolved_imm is Struct {
        resolved_imm_st := resolved_imm as Struct
        for field in expr.fields {
            if field.value !is ast.EmptyExpr {
                expected_type_prev := c.expected_type
                for sf in resolved_imm_st.fields {
                    if sf.name == field.name {
                        if sf.is_module_mut {
                            owner_module := field_owner_module(sf, resolved_imm_st.name)
                            if owner_module != '' && owner_module != c.cur_file_module {
                                info := FieldAccessInfo{
                                    field:        sf
                                    owner_struct: resolved_imm_st.name
                                }
                                c.error_with_pos('cannot initialize module-mutable field `${field_access_display(info)}` outside module `${owner_module}`',
                                    expr.pos)
                            }
                        }
                        c.expected_type = to_optional_type(sf.typ)
                        break
                    }
                }
                c.expr(field.value)
                $if ownership ? {
                    c.ownership_consume_expr(field.value, field.value.pos(), 'struct field')
                }
                c.expected_type = expected_type_prev
            }
        }
    } else {
        for field in expr.fields {
            if field.value !is ast.EmptyExpr {
                c.expr(field.value)
                $if ownership ? {
                    c.ownership_consume_expr(field.value, field.value.pos(), 'struct field')
                }
            }
        }
    }
    return typ
}

fn (mut c Checker) keyword_operator_expr(expr ast.KeywordOperator) Type {
    // TODO:
    typ := c.expr(expr.exprs[0])
    match expr.op {
        .key_go, .key_spawn {
            return empty_thread()
        }
        .key_typeof {
            // typeof(expr) returns a comptime TypeInfo with .name and .idx
            return Struct{
                name:   'TypeInfo'
                fields: [
                    Field{
                        name: 'name'
                        typ:  string_
                    },
                    Field{
                        name: 'idx'
                        typ:  int_
                    },
                ]
            }
        }
        .key_sizeof, .key_isreftype {
            return int_
        }
        else {
            return typ
        }
    }
}

fn (mut c Checker) map_init_expr(expr ast.MapInitExpr) Type {
    mut typ := Type(void_)
    mut map_key_type := Type(void_)
    mut map_value_type := Type(void_)
    mut has_map_type := false
    mut inferred_from_first_entry := false
    // `map[type]type{...}`
    if expr.typ !is ast.EmptyExpr {
        typ = c.expr(expr.typ)
        if map_typ := unwrap_map_type(typ) {
            map_key_type = map_typ.key_type
            map_value_type = map_typ.value_type
            has_map_type = true
        }
    } else if exp_type := c.expected_type {
        if map_typ := unwrap_map_type(exp_type) {
            map_key_type = map_typ.key_type
            map_value_type = map_typ.value_type
            has_map_type = true
        }
    }
    // `{}`
    if expr.keys.len == 0 {
        if expr.typ !is ast.EmptyExpr {
            return typ
        }
        if exp_type := c.expected_type {
            return exp_type
        }
        c.error_with_pos('empty map {} used in unsupported context', expr.pos)
        return Type(void_)
    }
    // `{key: value}` without an explicit/expected map type: infer from first pair.
    if !has_map_type {
        map_key_type = c.expr(expr.keys[0]).typed_default()
        map_value_type = c.expr(expr.vals[0]).typed_default()
        $if ownership ? {
            c.ownership_consume_expr(expr.keys[0], expr.keys[0].pos(), 'map key')
            c.ownership_consume_expr(expr.vals[0], expr.vals[0].pos(), 'map value')
        }
        has_map_type = true
        inferred_from_first_entry = true
    }
    expected_type_prev := c.expected_type
    for i, key_expr in expr.keys {
        val_expr := expr.vals[i]
        if inferred_from_first_entry && i == 0 {
            continue
        }
        c.expected_type = to_optional_type(map_key_type)
        key_type := c.expr(key_expr).typed_default()
        c.expected_type = to_optional_type(map_value_type)
        val_type := c.expr(val_expr).typed_default()
        $if ownership ? {
            c.ownership_consume_expr(key_expr, key_expr.pos(), 'map key')
            c.ownership_consume_expr(val_expr, val_expr.pos(), 'map value')
        }
        if !c.check_types(map_key_type, key_type) {
            c.error_with_pos('invalid map key: expecting ${map_key_type.name()}, got ${key_type.name()}',
                key_expr.pos())
        }
        if !c.check_types(map_value_type, val_type) {
            c.error_with_pos('invalid map value: expecting ${map_value_type.name()}, got ${val_type.name()}',
                val_expr.pos())
        }
    }
    c.expected_type = expected_type_prev
    if expr.typ !is ast.EmptyExpr {
        return typ
    }
    return Map{
        key_type:   map_key_type
        value_type: map_value_type
    }
}

fn (mut c Checker) or_expr(expr ast.OrExpr) Type {
    mut cond := c.resolve_expr(expr.expr)
    raw_cond_type := c.expr(cond)
    mut cond_type := raw_cond_type.unwrap()
    if cond_type is FnType && expr.expr is ast.CallOrCastExpr {
        coce := expr.expr as ast.CallOrCastExpr
        cond = ast.Expr(ast.CallExpr{
            lhs:  coce.lhs
            args: [coce.expr]
            pos:  coce.pos
        })
        cond_type = c.expr(cond).unwrap()
    }
    if cond_type is FnType {
        fn_type := cond_type as FnType
        if ret_type := fn_type.return_type {
            cond_type = ret_type.unwrap()
        }
    }
    // c.log('OrExpr: ${cond_type.name()}')
    if expr.stmts.len > 0 {
        c.open_scope()
        c.insert_error_scope_vars()
        if cond_type is Void {
            c.stmt_list(expr.stmts)
            c.close_scope()
            return cond_type
        }
        last_expr_idx := trailing_expr_stmt_index(expr.stmts)
        if last_expr_idx > 0 {
            c.stmt_list(expr.stmts[..last_expr_idx])
        } else if last_expr_idx == -1 {
            c.stmt_list(expr.stmts)
        }
        if last_expr_idx >= 0 {
            last_stmt := expr.stmts[last_expr_idx] as ast.ExprStmt
            expected_type_prev := c.expected_type
            c.expected_type = to_optional_type(cond_type)
            expr_stmt_type := c.expr(last_stmt.expr).unwrap()
            c.expected_type = expected_type_prev
            c.close_scope()
            // c.log('OrExpr: last_stmt_type: ${cond_type.name()}')
            // TODO: non returning call (currently just checking void)
            // should probably lookup function/method and check for noreturn attribute?
            // if cond is ast.CallExpr {}
            // do we need to do promotion here

            // last stmt expr does does not return a type
            // None is always valid in or-blocks (propagates the error)
            if cond is ast.SqlExpr && expr_stmt_type !is Void && expr_stmt_type !is None
                && (cond_type is Void || !c.check_types(cond_type, expr_stmt_type)) {
                return expr_stmt_type
            }
            if c.can_or_block_propagate_error(raw_cond_type, cond, expr_stmt_type) {
                return cond_type
            }
            if expr_stmt_type is Nil && cond is ast.IndexExpr {
                return cond_type
            }
            if expr_stmt_type !is Void && expr_stmt_type !is None
                && !c.check_types(cond_type, expr_stmt_type) {
                c.error_with_pos('or expr expecting ${cond_type.name()}, got ${expr_stmt_type.name()}',
                    expr.pos)
            }
            return cond_type
        }
        c.stmt_list(expr.stmts)
        c.close_scope()
    }
    return cond_type
}

fn (mut c Checker) prefix_expr(expr ast.PrefixExpr) Type {
    expr_type := c.expr(expr.expr)
    if expr.op == .amp {
        c.check_module_mut_field_mut_ref(expr.expr, expr.pos)
        return Pointer{
            base_type: expr_type
        }
    } else if expr.op == .mul {
        if expr_type is Pointer {
            expr_pt := expr_type as Pointer
            // c.log('DEREF')
            return expr_pt.base_type
        } else if expr_type is Interface {
            // Interface types are internally pointers, so dereference is valid
            // This handles match narrowing where the concrete type is still behind a pointer
            return expr_type
        } else if expr_type is Struct {
            // Allow deref on structs narrowed from interfaces in match expressions
            // TODO: properly track interface narrowing instead of this workaround
            return expr_type
        } else if expr_type is Void && expr.expr is ast.ParenExpr {
            paren_expr := expr.expr as ast.ParenExpr
            if paren_expr.e