// Copyright (c) 2026 Alexander Medvednikov. All rights reserved.
// Use of this source code is governed by an MIT license
// that can be found in the LICENSE file.
module transformer

import os
import strings
import time
import v2.ast
import v2.pref
import v2.token
import v2.types

const embed_file_helper_type_name = '__V2EmbedFileData'
const c_keywords = ['auto', 'break', 'case', 'char', 'const', 'continue', 'default', 'do', 'double',
    'else', 'enum', 'extern', 'float', 'for', 'goto', 'if', 'inline', 'int', 'long', 'register',
    'restrict', 'return', 'short', 'signed', 'sizeof', 'static', 'struct', 'switch', 'typedef',
    'union', 'unsigned', 'void', 'volatile', 'while', '_Bool', '_Complex', '_Imaginary', 'unix',
    'linux']
const smartcast_search_limit = 128
const max_runtime_const_dep_expr_depth = 128

// Transformer performs AST-level transformations to simplify
// and normalize code before codegen. This avoids duplicating
// transformation logic across multiple backends (SSA, cleanc, etc.)
pub struct Transformer {
mut:
    pref &pref.Preferences = unsafe { nil }
    env  &types.Environment
    // flat_fb_counts tracks how often each cursor-transform arm falls back to
    // a legacy decode, keyed by arm name. Dumped via V2_FLAT_FB_STATS to
    // prioritize the remaining flat-native migration work.
    flat_fb_counts map[string]int
    // pending_flat_stmt_ids queues already-emitted flat stmt ids that
    // cursor-native arms hoist ahead of the statement being transformed —
    // the flat-side twin of `pending_stmts`. Hoisting arms must first flush
    // `pending_stmts` into this queue so the combined drain keeps the legacy
    // chronological order.
    pending_flat_stmt_ids []ast.FlatNodeId
    // Current scope for type lookups (walks up scope chain)
    scope &types.Scope = unsafe { nil }
    // Function root scope for registering transformer-created temp variables
    // This allows cleanc to look up temp variable types from the environment
    fn_root_scope &types.Scope = unsafe { nil }
    // Current module for scope lookups
    cur_module string
    // Temp variable counter for desugaring
    temp_counter int
    // Counter for synthesized positions (uses negative values to avoid collision)
    synth_pos_counter int = -1
    // Track needed auto-generated str functions (type_name -> elem_type for arrays)
    needed_str_fns map[string]string
    // Track needed auto-generated clone functions (fn_name -> struct_name)
    needed_clone_fns map[string]string
    // Track needed auto-generated array helper functions
    needed_array_contains_fns   map[string]ArrayMethodInfo
    needed_array_index_fns      map[string]ArrayMethodInfo
    needed_array_last_index_fns map[string]ArrayMethodInfo
    // Current function's return type name (for sum type wrapping in returns)
    cur_fn_ret_type_name string
    // Current function's concrete sum type return wrapper, when known from
    // the declared return type.
    cur_fn_return_sumtype_info ConcreteSumtypeWrapInfo
    // Tracks whether the current function returns Option/Result.
    // Some transformations use this to avoid wrapping plain sumtype returns.
    cur_fn_returns_option bool
    cur_fn_returns_result bool
    // When set, match branch values should be wrapped in this sum type
    // (used when a match expression is returned from a function with sum type return)
    sumtype_return_wrap string
    // When true, the last expression in each match branch is transformed as a
    // value. This is needed while expanding `return match`, before branch-local
    // returns are inserted.
    preserve_match_branch_value bool
    // Smart cast context stack - supports nested smart casts
    smartcast_stack       []SmartcastContext
    smartcast_expr_counts map[string]int
    // Functions that should be elided (conditional compilation, e.g. @[if verbose ?])
    elided_fns map[string]bool
    // Runtime const initializers grouped by module, preserving module discovery order.
    runtime_const_inits_by_mod  map[string][]RuntimeConstInit
    runtime_const_modules       []string
    runtime_const_init_fn_name  map[string]string
    runtime_const_known         map[string]bool
    runtime_const_storage_known map[string]bool
    // Resolved replacement for compile-time pseudo variable @VMODROOT.
    comptime_vmodroot string
    // Statements generated by expression-level expansions (e.g. filter/map)
    // that must be hoisted before the current statement in transform_stmts.
    pending_stmts []ast.Stmt
    // When true, skip lowering value-position IfExpr to temp variable.
    // Set during contexts that already handle IfExpr RHS (e.g. decl_assign).
    skip_if_value_lowering bool
    // For native backends: map interface variable names to their concrete type names.
    // When we see `shape1 := Shape(rect)`, record shape1 → "Rectangle".
    // Used to rewrite interface method calls to direct concrete calls.
    interface_concrete_types map[string]string
    // Track needed auto-generated sort comparator functions
    needed_sort_fns     map[string]SortComparatorInfo
    needed_enum_str_fns map[string]types.Enum
    // Track needed go wrapper functions (go call -> goroutine_create lowering)
    needed_go_wrappers map[string]GoWrapperInfo
    // Declared storage types for local variables in the current function.
    // These stay separate from checker/current expression types, which can be
    // narrowed by smartcasts while the variable is still stored as its declared type.
    local_decl_types                map[string]types.Type
    local_fn_pointer_return_types   map[string]types.Type
    local_receiver_generic_bindings map[string]map[string]types.Type
    // Track whether post-pass should inject the synthetic embed_file helper type.
    needed_embed_file_helper bool
    // Override array element types for variables whose checker-inferred type is wrong
    // (e.g. .map(fn_name) typed as []voidptr instead of []ReturnType)
    array_elem_type_overrides map[string]string
    // File set for resolving positions to line numbers (for assert messages)
    file_set &token.FileSet = unsafe { nil }
    // Current file and function name (for assert messages)
    cur_file_name                 string
    cur_fn_name_str               string
    cur_fn_recv_prefix            string // C prefix for current method's receiver type (e.g., "ui__Window")
    cur_fn_recv_param             string // Receiver parameter name (e.g., "w")
    cur_fn_recv_is_ptr            bool   // Receiver is passed as a C pointer in the current method
    cur_fn_generic_params         []string
    generic_var_type_params       map[string]string
    generic_fn_decl_names         map[string]bool
    generic_fn_decl_stmts         map[string][]ast.Stmt
    generic_fn_decl_body_cursors  map[string]ast.CursorList
    generic_fn_decl_index         map[string]ast.FnDecl
    generic_call_candidate_names  map[string]bool
    generic_fn_value_names        map[string]bool
    declared_method_fns           map[string]bool
    monomorphized_fn_bindings     map[string]map[string]types.Type
    cur_monomorphized_fn_bindings map[string]types.Type
    // @[live] hot code reloading: function names and source file
    live_fns         []LiveFn
    live_source_file string
    // Cached scope/method/fn_scope snapshots for lock-free parallel access.
    // Populated once in pre_pass from the shared Environment fields.
    cached_scopes               map[string]&types.Scope
    cached_scope_keys           []string
    cached_methods              map[string][]&types.Fn
    cached_method_keys          []string
    cached_fn_scopes            map[string]&types.Scope
    cached_fn_type_index        map[string]types.Type
    cached_fn_return_type_index map[string]types.Type
    cached_struct_field_types   map[string]types.Type
    // cached_method_base_index maps type_name -> generic-base method name ->
    // FnType, precomputed once from cached_methods. lookup_method_cached used to
    // linearly scan every method of a type and recompute its base name (via
    // generic_base_name_without_specialization) on every call site — O(calls x
    // methods) with a string scan inner loop, the single biggest transform cost.
    // This makes the lookup O(1). Flat map keyed by "type_name#base_name" -> the
    // types.Type sum (callers smartcast to FnType). Flat (not nested) so a lookup
    // doesn't copy an inner map, and stored as the sum (not the FnType variant)
    // because v2's own codegen mishandles a map valued by a bare sum-variant.
    cached_method_base_index map[string]types.Type
    // cached_method_keys_by_short buckets cached_method_keys by their short
    // (final `__`-segment) name. The fuzzy method-key fallback loops only ever
    // match a key whose short name equals the receiver's short name, so they can
    // scan just this bucket instead of every method key (O(all_keys) per call).
    cached_method_keys_by_short map[string][]string
    // cached_imported_module_scopes maps a module name -> the scopes of the
    // modules it imports (excluding self/C). lookup_imported_var_type used to
    // rebuild this set on every identifier lookup — objects.keys() + sort() +
    // a full scan of the module's symbol table for Module objects — which made
    // it one of the hottest functions during type propagation (O(idents x
    // objects) with a per-call sort). Precomputed once in cache_env_maps so the
    // lookup is a single map fetch plus a short scan over only the imports.
    cached_imported_module_scopes map[string][]&types.Scope
    // Accumulated synth types for deferred application (thread-safe).
    // Instead of writing directly to env.set_expr_type during parallel transform,
    // store here and apply after merge.
    synth_types map[int]types.Type
    // Generic monomorphization clones generic FnDecls per env.generic_types
    // binding before code generation, so backends receive concrete functions.
    monomorphized_specs map[string]bool
    // inject_changed_files records whether the last
    // inject_generic_struct_specializations call actually appended new struct
    // specializations (i.e. returned a modified file set). The monomorphize
    // fixpoint uses it to skip the next iteration's full-program collect scan
    // when nothing changed.
    inject_changed_files bool
    // last_mono_clones maps file index -> the FnDecl clone stmts that the most
    // recent monomorphize_pass appended to that file. The fixpoint rescans only
    // these freshly-materialized clones (the rest of the program was already
    // scanned) instead of re-walking all files. Empty when mono_pass added none.
    last_mono_clones                   map[int][]ast.Stmt
    last_struct_clones                 map[int][]ast.Stmt
    generic_spec_owner_file            map[string]int
    deferred_generic_call_specs        []DeferredGenericCallSpec
    generic_struct_specs               map[string]GenericStructSpec
    struct_field_generic_decl_types    map[string]types.Type
    struct_field_generic_decl_bindings map[string]map[string]types.Type
    struct_default_decl_infos          map[string]StructDefaultDeclInfo
    concrete_embedded_owner_names      map[string]map[string]string
    cur_generic_call_file_idx          int = -1
    cur_import_aliases                 map[string]string
    sum_type_decl_variant_names        map[string][]string
    // Cached at construction: avoids per-block t.pref nil/enum re-check in
    // hot loops (transform_stmts, IfGuardExpr handling, OrExpr expansion, etc).
    is_native_be               bool
    macos_tiny_candidate_graph bool
}

fn escape_c_keyword(name string) string {
    n := if name.len > 0 && name[0] == `@` { name[1..] } else { name }
    if n in c_keywords {
        return '_${n}'
    }
    return n
}

fn enum_member_ident(enum_type string, field_name string) string {
    escaped := if field_name.len > 0 && field_name[0] == `@` {
        'at_${field_name[1..]}'
    } else {
        escape_c_keyword(field_name)
    }
    return '${enum_type}__${escaped}'
}

fn (t &Transformer) enum_type_c_name_for_lookup(lookup_name string, typ types.Enum) string {
    if dunder := lookup_name.index('__') {
        mod_name := lookup_name[..dunder]
        last_dunder := lookup_name.last_index('__') or { dunder }
        if last_dunder >= 0 && last_dunder + 2 < lookup_name.len {
            type_name := lookup_name[last_dunder + 2..]
            if scope := t.get_module_scope(mod_name) {
                if direct_typ := scope.lookup_type(type_name) {
                    if direct_typ is types.Enum {
                        return lookup_name
                    }
                }
            }
        }
    }
    if dot := lookup_name.last_index('.') {
        mod_name := lookup_name[..dot]
        type_name := lookup_name[dot + 1..]
        if scope := t.get_module_scope(mod_name) {
            if direct_typ := scope.lookup_type(type_name) {
                if direct_typ is types.Enum {
                    return lookup_name.replace('.', '__')
                }
            }
        }
    }
    if typ.name != '' {
        return t.type_to_c_name(types.Type(typ))
    }
    return lookup_name.replace('.', '__')
}

fn (t &Transformer) enum_member_ident_for_lookup(lookup_name string, typ types.Enum, field_name string) string {
    return enum_member_ident(t.enum_type_c_name_for_lookup(lookup_name, typ), field_name)
}

fn (t &Transformer) skip_native_backend_transform_file(file ast.File) bool {
    if t.pref == unsafe { nil } {
        return false
    }
    own := match t.pref.backend {
        .arm64 { 'arm64' }
        .x64 { 'x64' }
        else { return false }
    }

    if !t.pref.single_backend && own != 'arm64' {
        return false
    }

    name := file.name.replace('\\', '/')
    if !name.contains('/v2/gen/') {
        return false
    }
    for backend_mod in ['cleanc', 'eval', 'v', 'c', 'x64', 'arm64'] {
        if backend_mod != own && name.contains('/v2/gen/${backend_mod}/') {
            return true
        }
    }
    return false
}

struct LiveFn {
    decl_name    string // e.g., 'frame' or 'update_model'
    mangled_name string // e.g., 'frame' or 'Game__update_model'
    is_method    bool
    recv_type    string // e.g., 'Game' (empty for non-methods)
}

// SmartcastContext holds info about a single smartcast
struct SmartcastContext {
    expr         string // The expression being smart-cast (e.g., "w.valera")
    variant      string // The variant type name for union member access (e.g., "int", "Kek", "Array_Attribute")
    variant_full string // The full variant name for type casts (e.g., "ast__Kek", "Array_ast__Attribute")
    sumtype      string // The sum type name (e.g., "Valera")
}

struct ArrayMethodInfo {
    array_type string
    elem_type  string
    is_fixed   bool
    fixed_len  int
}

// GoWrapperInfo tracks information needed to synthesize a go-wrapper function.
// For `go foo(a, b)`, we generate a wrapper that packs args and calls
// goroutines__goroutine_create, and a trampoline that unpacks args and calls foo.
struct GoWrapperInfo {
    fn_name      string   // C-mangled function name (e.g. "main__foo")
    wrapper_name string   // Wrapper function name (e.g. "__go_wrap_main__foo")
    param_names  []string // Parameter names
    param_types  []string // Parameter C type names
}

fn builder_write_string_stmt(sb_ref ast.Expr, s ast.Expr) ast.Stmt {
    return ast.Stmt(ast.ExprStmt{
        expr: ast.Expr(ast.CallExpr{
            lhs:  ast.Expr(ast.Ident{
                name: 'strings__Builder__write_string'
            })
            args: [sb_ref, s]
        })
    })
}

struct RuntimeConstInit {
    name        string
    expr        ast.Expr
    expr_cursor ast.Cursor
}

struct SortComparatorInfo {
    elem_type  string      // C type name of array element
    compare_op token.Token // .lt or .gt for the original comparison
    // For field access: a.field < b.field
    field_name string // empty for simple element comparison
    field_path []string
    // For index access: a[0] < b[0]
    index_expr string // empty for non-index comparison, e.g. "0"
    // Whether the comparison value type is string (needs string__lt)
    is_string_cmp bool
}

pub fn Transformer.new_with_pref(env &types.Environment, p &pref.Preferences) &Transformer {
    mut t := new_transformer_base(env, p)
    if p != unsafe { nil } && p.vroot.len > 0 {
        t.comptime_vmodroot = p.vroot
        return t
    }
    cwd := os.getwd()
    if root := detect_vmodroot_from_path(cwd) {
        t.comptime_vmodroot = root
    }
    return t
}

fn new_transformer_base(env &types.Environment, p &pref.Preferences) &Transformer {
    mut t := &Transformer{
        pref:                               unsafe { p }
        env:                                unsafe { env }
        needed_str_fns:                     map[string]string{}
        needed_clone_fns:                   map[string]string{}
        needed_array_contains_fns:          map[string]ArrayMethodInfo{}
        needed_array_index_fns:             map[string]ArrayMethodInfo{}
        needed_array_last_index_fns:        map[string]ArrayMethodInfo{}
        needed_sort_fns:                    map[string]SortComparatorInfo{}
        needed_enum_str_fns:                map[string]types.Enum{}
        needed_go_wrappers:                 map[string]GoWrapperInfo{}
        local_decl_types:                   map[string]types.Type{}
        local_fn_pointer_return_types:      map[string]types.Type{}
        local_receiver_generic_bindings:    map[string]map[string]types.Type{}
        generic_var_type_params:            map[string]string{}
        generic_fn_decl_names:              map[string]bool{}
        generic_fn_decl_stmts:              map[string][]ast.Stmt{}
        generic_fn_decl_body_cursors:       map[string]ast.CursorList{}
        generic_fn_decl_index:              map[string]ast.FnDecl{}
        generic_call_candidate_names:       map[string]bool{}
        generic_fn_value_names:             map[string]bool{}
        declared_method_fns:                map[string]bool{}
        monomorphized_fn_bindings:          map[string]map[string]types.Type{}
        cur_monomorphized_fn_bindings:      map[string]types.Type{}
        runtime_const_inits_by_mod:         map[string][]RuntimeConstInit{}
        runtime_const_init_fn_name:         map[string]string{}
        runtime_const_known:                map[string]bool{}
        runtime_const_storage_known:        map[string]bool{}
        interface_concrete_types:           map[string]string{}
        smartcast_expr_counts:              map[string]int{}
        monomorphized_specs:                map[string]bool{}
        generic_spec_owner_file:            map[string]int{}
        deferred_generic_call_specs:        []DeferredGenericCallSpec{}
        generic_struct_specs:               map[string]GenericStructSpec{}
        struct_field_generic_decl_types:    map[string]types.Type{}
        struct_field_generic_decl_bindings: map[string]map[string]types.Type{}
        struct_default_decl_infos:          map[string]StructDefaultDeclInfo{}
        concrete_embedded_owner_names:      map[string]map[string]string{}
        cur_import_aliases:                 map[string]string{}
        sum_type_decl_variant_names:        map[string][]string{}
        is_native_be:                       p != unsafe { nil }
            && (p.backend == .arm64 || p.backend == .x64)
    }
    return t
}

pub fn (mut t Transformer) set_file_set(fs &token.FileSet) {
    t.file_set = unsafe { fs }
}

pub fn (mut t Transformer) enable_macos_tiny_candidate_graph() {
    t.macos_tiny_candidate_graph = true
}

// new_worker_clone creates a lightweight Transformer that shares read-only state
// (env, pref, elided_fns, comptime_vmodroot, file_set) but has its own
// accumulator maps for thread-safe per-file transformation.
// worker_idx offsets synth_pos_counter so workers don't generate conflicting IDs
// or collide with synth positions already created during whole-program prepare.
pub fn (t &Transformer) new_worker_clone(worker_idx int) &Transformer {
    return &Transformer{
        pref:                               unsafe { t.pref }
        env:                                unsafe { t.env }
        elided_fns:                         t.elided_fns.clone()
        comptime_vmodroot:                  t.comptime_vmodroot
        file_set:                           unsafe { t.file_set }
        cached_scopes:                      t.cached_scopes.clone()
        cached_scope_keys:                  t.cached_scope_keys
        cached_methods:                     t.cached_methods
        cached_fn_type_index:               t.cached_fn_type_index
        cached_fn_return_type_index:        t.cached_fn_return_type_index
        cached_imported_module_scopes:      t.cached_imported_module_scopes
        cached_struct_field_types:          t.cached_struct_field_types
        cached_method_base_index:           t.cached_method_base_index
        cached_method_keys_by_short:        t.cached_method_keys_by_short
        cached_method_keys:                 t.cached_method_keys
        cached_fn_scopes:                   t.cached_fn_scopes.clone()
        synth_types:                        t.synth_types.clone()
        synth_pos_counter:                  t.synth_pos_counter - (worker_idx * 100_000)
        needed_str_fns:                     map[string]string{}
        needed_clone_fns:                   map[string]string{}
        needed_array_contains_fns:          map[string]ArrayMethodInfo{}
        needed_array_index_fns:             map[string]ArrayMethodInfo{}
        needed_array_last_index_fns:        map[string]ArrayMethodInfo{}
        needed_sort_fns:                    map[string]SortComparatorInfo{}
        needed_enum_str_fns:                map[string]types.Enum{}
        needed_go_wrappers:                 map[string]GoWrapperInfo{}
        local_decl_types:                   map[string]types.Type{}
        local_fn_pointer_return_types:      map[string]types.Type{}
        local_receiver_generic_bindings:    map[string]map[string]types.Type{}
        generic_var_type_params:            map[string]string{}
        generic_fn_decl_body_cursors:       t.generic_fn_decl_body_cursors.clone()
        generic_fn_decl_index:              t.generic_fn_decl_index.clone()
        generic_call_candidate_names:       t.generic_call_candidate_names.clone()
        generic_fn_value_names:             t.generic_fn_value_names.clone()
        declared_method_fns:                t.declared_method_fns.clone()
        monomorphized_fn_bindings:          t.monomorphized_fn_bindings.clone()
        cur_monomorphized_fn_bindings:      map[string]types.Type{}
        runtime_const_inits_by_mod:         map[string][]RuntimeConstInit{}
        runtime_const_init_fn_name:         map[string]string{}
        runtime_const_known:                map[string]bool{}
        runtime_const_storage_known:        map[string]bool{}
        interface_concrete_types:           map[string]string{}
        smartcast_expr_counts:              map[string]int{}
        monomorphized_specs:                t.monomorphized_specs.clone()
        generic_spec_owner_file:            t.generic_spec_owner_file.clone()
        deferred_generic_call_specs:        []DeferredGenericCallSpec{}
        generic_struct_specs:               t.generic_struct_specs.clone()
        struct_field_generic_decl_types:    t.struct_field_generic_decl_types.clone()
        struct_field_generic_decl_bindings: t.struct_field_generic_decl_bindings.clone()
        struct_default_decl_infos:          t.struct_default_decl_infos.clone()
        concrete_embedded_owner_names:      t.concrete_embedded_owner_names.clone()
        cur_generic_call_file_idx:          t.cur_generic_call_file_idx
        cur_import_aliases:                 t.cur_import_aliases.clone()
        sum_type_decl_variant_names:        t.sum_type_decl_variant_names.clone()
        is_native_be:                       t.is_native_be
        macos_tiny_candidate_graph:         t.macos_tiny_candidate_graph
    }
}

// merge_worker merges accumulated state from a worker transformer into this one.
pub fn (mut t Transformer) merge_worker(w &Transformer) {
    for k, v in w.needed_str_fns {
        t.needed_str_fns[k] = v
    }
    for k, v in w.needed_clone_fns {
        t.needed_clone_fns[k] = v
    }
    for k, v in w.needed_array_contains_fns {
        t.needed_array_contains_fns[k] = v
    }
    for k, v in w.needed_array_index_fns {
        t.needed_array_index_fns[k] = v
    }
    for k, v in w.needed_array_last_index_fns {
        t.needed_array_last_index_fns[k] = v
    }
    for k, v in w.needed_sort_fns {
        t.needed_sort_fns[k] = v
    }
    for k, v in w.needed_enum_str_fns {
        t.needed_enum_str_fns[k] = v
    }
    for k, v in w.needed_go_wrappers {
        t.needed_go_wrappers[k] = v
    }
    for k, v in w.elided_fns {
        t.elided_fns[k] = v
    }
    if w.needed_embed_file_helper {
        t.needed_embed_file_helper = true
    }
    for k, v in w.interface_concrete_types {
        t.interface_concrete_types[k] = v
    }
    for k, v in w.array_elem_type_overrides {
        t.array_elem_type_overrides[k] = v
    }
    for lf in w.live_fns {
        t.live_fns << lf
    }
    if w.live_source_file.len > 0 {
        t.live_source_file = w.live_source_file
    }
    for k, v in w.cached_fn_scopes {
        t.cached_fn_scopes[k] = v
    }
    for k, v in w.synth_types {
        t.synth_types[k] = v
    }
}

// transform_file_standalone transforms a single file, for use in parallel workers.
pub fn (mut t Transformer) transform_file_pub(file ast.File) ast.File {
    return t.transform_file(file)
}

// transform_file_stmt_pub transforms one top-level statement in a file context,
// for use by the declaration-level parallel transformer.
pub fn (mut t Transformer) transform_file_stmt_pub(file ast.File, stmt ast.Stmt) []ast.Stmt {
    t.enter_file_context(file)
    return t.transform_stmts([stmt])
}

fn (mut t Transformer) enter_file_context(file ast.File) {
    // Set current file name for assert messages
    t.cur_file_name = file.name
    // Set current module for scope lookups
    t.cur_module = file.mod
    t.cur_import_aliases = import_aliases_for_generic_collect(file.imports)
    // Set module scope as starting point
    if scope := t.get_module_scope(file.mod) {
        t.scope = scope
    } else {
        t.scope = unsafe { nil }
    }
}

fn detect_vmodroot_from_path(path string) ?string {
    if path.len == 0 {
        return none
    }
    mut dir := path
    if !os.is_abs_path(dir) {
        cwd := os.getwd()
        if cwd.len > 0 {
            dir = os.join_path(cwd, dir)
        }
    }
    if !os.is_dir(dir) {
        dir = os.dir(dir)
    }
    for _ in 0 .. 16 {
        if os.is_file(os.join_path(dir, 'v.mod')) {
            return dir
        }
        parent := os.dir(dir)
        if parent == dir {
            break
        }
        dir = parent
    }
    return none
}

fn (t &Transformer) is_eval_backend() bool {
    return t.pref != unsafe { nil } && t.pref.backend == .eval
}

fn quote_v_string_literal(raw string) string {
    mut escaped := raw.replace('\\', '\\\\')
    escaped = escaped.replace("'", "\\'")
    return "'${escaped}'"
}

fn quote_v_bytes_literal(raw []u8) string {
    hex_digits := '0123456789abcdef'
    mut sb := strings.new_builder(raw.len * 4 + 2)
    sb.write_u8(`'`)
    for b in raw {
        if b >= ` ` && b <= `~` && b !in [`\\`, `'`] {
            sb.write_u8(b)
            continue
        }
        match b {
            `\n` {
                sb.write_string('\\n')
            }
            `\r` {
                sb.write_string('\\r')
            }
            `\t` {
                sb.write_string('\\t')
            }
            `\\` {
                sb.write_string('\\\\')
            }
            `'` {
                sb.write_string("\\'")
            }
            else {
                sb.write_string('\\x')
                sb.write_u8(hex_digits[b >> 4])
                sb.write_u8(hex_digits[b & 0x0f])
            }
        }
    }
    sb.write_u8(`'`)
    return sb.str()
}

fn embed_file_helper_type_expr(pos token.Pos) ast.Expr {
    return ast.Expr(ast.Ident{
        name: embed_file_helper_type_name
        pos:  pos
    })
}

fn is_embed_file_helper_type(typ types.Type) bool {
    return typ.name() == embed_file_helper_type_name
}

fn (t &Transformer) vmodroot_string_literal(pos token.Pos) ast.StringLiteral {
    return ast.StringLiteral{
        kind:  .v
        value: quote_v_string_literal(t.comptime_vmodroot)
        pos:   pos
    }
}

fn embed_file_string_arg(expr ast.Expr) ?string {
    match expr {
        ast.StringLiteral {
            if expr.value.len >= 2 {
                return expr.value[1..expr.value.len - 1]
            }
            return ''
        }
        ast.BasicLiteral {
            if expr.kind == .string {
                if expr.value.len >= 2 {
                    return expr.value[1..expr.value.len - 1]
                }
                return ''
            }
            return none
        }
        else {
            return none
        }
    }
}

fn (mut t Transformer) current_file_path(pos token.Pos) string {
    if !pos.is_valid() || t.file_set == unsafe { nil } {
        return t.cur_file_name
    }
    file := t.file_set.file(pos)
    position := file.position(pos)
    return position.filename
}

fn (mut t Transformer) resolve_embed_file_paths(raw_path string, pos token.Pos) (string, string) {
    mut rel_path := raw_path
    if rel_path.contains('@VMODROOT') {
        rel_path = rel_path.replace('@VMODROOT', t.comptime_vmodroot)
    }
    if rel_path.contains('@VEXEROOT') {
        mut vexeroot := ''
        if os.args.len > 0 && os.args[0].len > 0 {
            vexeroot = os.dir(os.real_path(os.args[0]))
        }
        if vexeroot == '' && t.pref != unsafe { nil } && t.pref.vroot.len > 0 {
            vexeroot = os.join_path(t.pref.vroot, 'cmd', 'v2')
        }
        if vexeroot != '' {
            rel_path = rel_path.replace('@VEXEROOT', vexeroot)
        }
    }
    if os.is_abs_path(rel_path) {
        return raw_path, os.real_path(rel_path)
    }
    source_path := t.current_file_path(pos)
    base_dir := if source_path != '' { os.dir(source_path) } else { os.getwd() }
    return raw_path, os.real_path(os.join_path_single(base_dir, rel_path))
}

// embed_file_init_parts is the side-effecting prologue of
// `transform_embed_file_comptime_expr` — resolves the raw path argument,
// reads the file bytes from disk, and sets `needed_embed_file_helper`.
// Returns `(rpath, apath, file_bytes)` on success, none on zero-arg /
// non-string-literal arg (the legacy returns the unchanged ComptimeExpr in
// that case). Extracted so the legacy helper and the flat-write direct-emit
// port (`transform_embed_file_comptime_expr_to_flat`) share the same I/O and
// state-mutation prologue — same template as sessions 4, 59, 60.
fn (mut t Transformer) embed_file_init_parts(expr ast.ComptimeExpr, args []ast.Expr) ?(string, string, []u8) {
    if args.len == 0 {
        return none
    }
    raw_path := embed_file_string_arg(args[0]) or { return none }
    return t.embed_file_init_parts_from_raw(raw_path, expr.pos)
}

fn (mut t Transformer) embed_file_init_parts_from_raw(raw_path string, pos token.Pos) (string, string, []u8) {
    rpath, apath := t.resolve_embed_file_paths(raw_path, pos)
    file_bytes := os.read_bytes(apath) or { panic('embed_file: failed to read `${apath}`: ${err}') }
    t.needed_embed_file_helper = true
    return rpath, apath, file_bytes
}

fn (mut t Transformer) transform_embed_file_comptime_expr(expr ast.ComptimeExpr, args []ast.Expr) ast.Expr {
    rpath, apath, file_bytes := t.embed_file_init_parts(expr, args) or { return expr }
    return ast.InitExpr{
        typ:    embed_file_helper_type_expr(expr.pos)
        fields: [
            ast.FieldInit{
                name:  '_data'
                value: ast.Expr(ast.StringLiteral{
                    kind:  .v
                    value: quote_v_bytes_literal(file_bytes)
                    pos:   expr.pos
                })
            },
            ast.FieldInit{
                name:  'len'
                value: ast.Expr(ast.BasicLiteral{
                    kind:  .number
                    value: file_bytes.len.str()
                    pos:   expr.pos
                })
            },
            ast.FieldInit{
                name:  'path'
                value: ast.Expr(ast.StringLiteral{
                    kind:  .v
                    value: quote_v_string_literal(rpath)
                    pos:   expr.pos
                })
            },
            ast.FieldInit{
                name:  'apath'
                value: ast.Expr(ast.StringLiteral{
                    kind:  .v
                    value: quote_v_string_literal(apath)
                    pos:   expr.pos
                })
            },
        ]
        pos:    expr.pos
    }
}

// push_smartcast adds a new smartcast context to the stack
fn (mut t Transformer) push_smartcast(expr string, variant string, sumtype string) {
    if expr == '' {
        return
    }
    qualified_sumtype := t.qualify_type_name(sumtype)
    t.push_smartcast_ctx(SmartcastContext{
        expr:         expr
        variant:      variant
        variant_full: variant // Default to same as variant
        sumtype:      qualified_sumtype
    })
}

// push_smartcast_full adds a smartcast context with separate short and full variant names
fn (mut t Transformer) push_smartcast_full(expr string, variant string, variant_full string, sumtype string) {
    if expr == '' {
        return
    }
    // Qualify the sumtype name so apply_smartcast_* can determine the module
    // the sumtype lives in. e.g. 'Stmt' → 'ast__Stmt' when in builder module.
    qualified_sumtype := t.qualify_type_name(sumtype)
    t.push_smartcast_ctx(SmartcastContext{
        expr:         expr
        variant:      variant
        variant_full: variant_full
        sumtype:      qualified_sumtype
    })
}

fn (mut t Transformer) push_smartcast_ctx(ctx SmartcastContext) {
    if ctx.expr == '' {
        return
    }
    t.smartcast_stack << ctx
    t.smartcast_expr_counts[ctx.expr] = t.smartcast_expr_counts[ctx.expr] + 1
}

fn (mut t Transformer) dec_smartcast_expr_count(expr string) {
    if expr == '' {
        return
    }
    count := t.smartcast_expr_counts[expr]
    if count <= 1 {
        t.smartcast_expr_counts.delete(expr)
    } else {
        t.smartcast_expr_counts[expr] = count - 1
    }
}

// pop_smartcast removes the most recent smartcast context from the stack
fn (mut t Transformer) pop_smartcast() {
    if t.smartcast_stack.len > 0 {
        ctx := t.smartcast_stack[t.smartcast_stack.len - 1]
        t.smartcast_stack = t.smartcast_stack[..t.smartcast_stack.len - 1]
        t.dec_smartcast_expr_count(ctx.expr)
    }
}

fn (mut t Transformer) truncate_smartcasts(depth int) {
    for t.smartcast_stack.len > depth {
        t.pop_smartcast()
    }
}

// SmartcastRemoveResult holds the removed context and its original index
struct SmartcastRemoveResult {
    ctx SmartcastContext
    idx int
}

// remove_smartcast_for_expr removes the smartcast context for a specific expression
// Returns the removed context or none if not found
fn (mut t Transformer) remove_smartcast_for_expr(expr_str string) ?SmartcastContext {
    if result := t.remove_smartcast_for_expr_with_idx(expr_str) {
        return result.ctx
    }
    return none
}

// remove_smartcast_for_expr_with_idx removes the smartcast context and returns both context and original index
fn (mut t Transformer) remove_smartcast_for_expr_with_idx(expr_str string) ?SmartcastRemoveResult {
    if expr_str == '' {
        return none
    }
    if t.smartcast_expr_counts[expr_str] == 0 {
        return none
    }
    mut i := t.smartcast_stack.len
    mut searched := 0
    for i > 0 && searched < smartcast_search_limit {
        i--
        searched++
        if t.smartcast_stack[i].expr == expr_str {
            ctx := t.smartcast_stack[i]
            // Remove this specific context by creating new slice without this element
            mut new_stack := []SmartcastContext{cap: t.smartcast_stack.len - 1}
            for j, c in t.smartcast_stack {
                if j != i {
                    new_stack << c
                }
            }
            t.smartcast_stack = new_stack
            t.dec_smartcast_expr_count(ctx.expr)
            return SmartcastRemoveResult{
                ctx: ctx
                idx: i
            }
        }
    }
    return none
}

// remove_smartcast_ctx_with_idx removes a specific smartcast context and returns
// the removed context with its original index.
fn (mut t Transformer) remove_smartcast_ctx_with_idx(ctx SmartcastContext) ?SmartcastRemoveResult {
    mut i := t.smartcast_stack.len
    mut searched := 0
    for i > 0 && searched < smartcast_search_limit {
        i--
        searched++
        cur := t.smartcast_stack[i]
        if cur.expr == ctx.expr && cur.variant == ctx.variant
            && cur.variant_full == ctx.variant_full {
            removed := cur
            mut new_stack := []SmartcastContext{cap: t.smartcast_stack.len - 1}
            for j, c in t.smartcast_stack {
                if j != i {
                    new_stack << c
                }
            }
            t.smartcast_stack = new_stack
            t.dec_smartcast_expr_count(removed.expr)
            return SmartcastRemoveResult{
                ctx: removed
                idx: i
            }
        }
    }
    return none
}

// remove_matching_smartcasts temporarily removes all exact copies of ctx.
fn (mut t Transformer) remove_matching_smartcasts(ctx SmartcastContext) []SmartcastRemoveResult {
    mut removed := []SmartcastRemoveResult{}
    if ctx.expr == '' || t.smartcast_stack.len == 0 {
        return removed
    }
    start := if t.smartcast_stack.len > smartcast_search_limit {
        t.smartcast_stack.len - smartcast_search_limit
    } else {
        0
    }
    mut new_stack := []SmartcastContext{cap: t.smartcast_stack.len}
    for i, cur in t.smartcast_stack {
        if i >= start && cur.expr == ctx.expr && cur.variant == ctx.variant
            && cur.variant_full == ctx.variant_full {
            removed << SmartcastRemoveResult{
                ctx: cur
                idx: i
            }
            t.dec_smartcast_expr_count(cur.expr)
            continue
        }
        new_stack << cur
    }
    t.smartcast_stack = new_stack
    return removed
}

// restore_smartcasts restores previously removed contexts in original order.
fn (mut t Transformer) restore_smartcasts(removed []SmartcastRemoveResult) {
    mut i := removed.len
    for i > 0 {
        i--
        entry := removed[i]
        t.insert_smartcast_at(entry.idx, entry.ctx)
    }
}

// insert_smartcast_at inserts a smartcast context at a specific position
fn (mut t Transformer) insert_smartcast_at(idx int, ctx SmartcastContext) {
    if ctx.expr == '' {
        return
    }
    if idx >= t.smartcast_stack.len {
        // Append at end
        t.smartcast_stack << ctx
        t.smartcast_expr_counts[ctx.expr] = t.smartcast_expr_counts[ctx.expr] + 1
    } else {
        // Insert at position
        mut new_stack := []SmartcastContext{cap: t.smartcast_stack.len + 1}
        for i, c in t.smartcast_stack {
            if i == idx {
                new_stack << ctx
            }
            new_stack << c
        }
        // If idx was 0 and loop didn't add, add at beginning
        if idx == 0 && new_stack.len == t.smartcast_stack.len {
            new_stack = [ctx]
            new_stack << t.smartcast_stack
        }
        t.smartcast_stack = new_stack
        t.smartcast_expr_counts[ctx.expr] = t.smartcast_expr_counts[ctx.expr] + 1
    }
}

// find_smartcast_for_expr finds the smartcast context that matches the given expression string
// Returns the context or none if not found
fn (t &Transformer) find_smartcast_for_expr(expr_str string) ?SmartcastContext {
    // Empty expression strings are ambiguous (from unhandled AST nodes like IndexExpr)
    // and must never match, as they would incorrectly apply smartcasts to unrelated
    // expressions (e.g., EmptyExpr in enum shorthands like `.assign`).
    if expr_str == '' {
        return none
    }
    if t.smartcast_expr_counts[expr_str] == 0 {
        return none
    }
    // Search from most recent to oldest (reverse order)
    mut i := t.smartcast_stack.len
    mut searched := 0
    for i > 0 && searched < smartcast_search_limit {
        i--
        searched++
        if t.smartcast_stack[i].expr == expr_str {
            return t.smartcast_stack[i]
        }
    }
    return none
}

fn (t &Transformer) smartcast_context_tag_value(ctx SmartcastContext) ?int {
    if ctx.sumtype.starts_with('__iface__') {
        return none
    }
    variants := t.get_sum_type_variants(ctx.sumtype)
    for candidate in [ctx.variant, ctx.variant_full] {
        if candidate == '' {
            continue
        }
        if matched := t.match_variant(candidate, variants) {
            for i, variant in variants {
                if variant == matched {
                    return i
                }
            }
        }
    }
    return none
}

fn (t &Transformer) find_sumtype_with_variant_at_tag(variant_name string, tag int) string {
    if variant_name == '' || tag < 0 {
        return ''
    }
    for st in ['Expr', 'Type', 'Stmt', 'ast__Expr', 'ast__Type', 'ast__Stmt'] {
        variants := t.get_sum_type_variants(st)
        if tag < variants.len
            && sum_type_variant_matches_for_sumtype(st, variants[tag], variant_name) {
            return st
        }
    }
    for mod_name, scope in t.cached_scopes {
        for type_name, typ in scope.types {
            if typ is types.SumType {
                st_name := if mod_name != '' && mod_name != 'main' && mod_name != 'builtin' {
                    '${mod_name}__${type_name}'
                } else {
                    type_name
                }
                variants := typ.get_variants()
                if tag < variants.len
                    && sum_type_variant_matches_for_sumtype(st_name, variants[tag].name(), variant_name) {
                    return st_name
                }
            }
        }
    }
    return ''
}

fn (t &Transformer) smartcast_context_from_tag_check(expr ast.InfixExpr) ?SmartcastContext {
    if expr.op != .eq || expr.lhs !is ast.SelectorExpr {
        return none
    }
    tag_sel := expr.lhs as ast.SelectorExpr
    if tag_sel.rhs.name != '_tag' {
        return none
    }
    if expr.rhs !is ast.BasicLiteral {
        return none
    }
    tag_lit := expr.rhs as ast.BasicLiteral
    if tag_lit.kind != .number {
        return none
    }
    tag := tag_lit.value.int()
    if tag < 0 {
        return none
    }
    sumtype_expr := tag_sel.lhs
    mut sumtype_name := t.get_sumtype_name_for_expr(sumtype_expr)
    if sumtype_name == '' {
        return none
    }
    mut variants := t.get_sum_type_variants(sumtype_name)
    if tag >= variants.len {
        storage_sumtype := t.find_sumtype_with_variant_at_tag(sumtype_name, tag)
        if storage_sumtype == '' {
            return none
        }
        sumtype_name = storage_sumtype
        variants = t.get_sum_type_variants(sumtype_name)
    }
    variant_name := variants[tag]
    variant_short := if variant_name.contains('__') {
        variant_name.all_after_last('__')
    } else {
        variant_name
    }
    sumtype_module := if sumtype_name.contains('__') {
        sumtype_name.all_before_last('__')
    } else {
        ''
    }
    variant_full := if variant_name.contains('__') || sumtype_module == ''
        || variant_short.starts_with('Array_') || variant_short.starts_with('Map_') {
        variant_name
    } else {
        '${sumtype_module}__${variant_short}'
    }
    expr_str := t.expr_to_string(sumtype_expr)
    if expr_str == '' {
        return none
    }
    return SmartcastContext{
        expr:         expr_str
        variant:      variant_full
        variant_full: variant_full
        sumtype:      sumtype_name
    }
}

fn (t &Transformer) smartcast_context_from_condition_term(term ast.InfixExpr) ?SmartcastContext {
    if ctx := t.smartcast_context_from_is_check(term) {
        return ctx
    }
    return t.smartcast_context_from_tag_check(term)
}

fn (mut t Transformer) transform_tag_check_lhs(lhs ast.Expr) ast.Expr {
    if lhs is ast.Ident {
        if t.smartcast_stack.len > 0 {
            ctx := t.smartcast_stack[t.smartcast_stack.len - 1]
            if ctx.expr == lhs.name && t.is_sum_type(ctx.variant) {
                return t.transform_expr(lhs)
            }
        }
        return ast.Expr(lhs)
    }
    return t.transform_expr(lhs)
}

fn smartcast_type_name_matches(candidate string, target string) bool {
    mut c := candidate.trim_space()
    mut t := target.trim_space()
    if c.starts_with('&') {
        c = c[1..]
    }
    if t.starts_with('&') {
        t = t[1..]
    }
    c = c.trim_right('*')
    t = t.trim_right('*')
    if c == '' || t == '' {
        return false
    }
    if c == t {
        return true
    }
    c_short := if c.contains('__') { c.all_after_last('__') } else { c }
    t_short := if t.contains('__') { t.all_after_last('__') } else { t }
    return c_short == t_short
}

fn (mut t Transformer) transform_tag_check_lhs_for_sumtype(lhs ast.Expr, sumtype_name string) ast.Expr {
    lhs_expr_str := t.expr_to_string(lhs)
    if lhs_expr_str != '' {
        if ctx := t.find_smartcast_for_expr(lhs_expr_str) {
            if !ctx.sumtype.starts_with('__iface__')
                && (smartcast_type_name_matches(ctx.variant, sumtype_name)
                || smartcast_type_name_matches(ctx.variant_full, sumtype_name)) {
                return t.apply_smartcast_direct_ctx(lhs, ctx)
            }
        }
    }
    return t.transform_tag_check_lhs(lhs)
}

// has_active_smartcast returns true if there's any active smartcast context
fn (t &Transformer) has_active_smartcast() bool {
    return t.smartcast_stack.len > 0
}

// cur_smartcast_expr returns the current (most recent) smartcast expression or empty string
fn (t &Transformer) cur_smartcast_expr() string {
    if t.smartcast_stack.len > 0 {
        return t.smartcast_stack[t.smartcast_stack.len - 1].expr
    }
    return ''
}

// cur_smartcast_variant returns the current (most recent) smartcast variant or empty string
fn (t &Transformer) cur_smartcast_variant() string {
    if t.smartcast_stack.len > 0 {
        return t.smartcast_stack[t.smartcast_stack.len - 1].variant
    }
    return ''
}

pub fn (mut t Transformer) set_synth_pos_counter(val int) {
    t.synth_pos_counter = val
}

// next_synth_pos returns a unique negative position for synthesized AST nodes
fn (mut t Transformer) next_synth_pos() token.Pos {
    id := t.synth_pos_counter
    t.synth_pos_counter -= 1
    return token.Pos{
        id:     id
        offset: 0
    }
}

fn (mut t Transformer) make_number_expr(value string) ast.Expr {
    pos := t.next_synth_pos()
    return ast.Expr(ast.BasicLiteral{
        kind:  .number
        value: value
        pos:   pos
    })
}

fn (mut t Transformer) make_infix_expr_at(op token.Token, lhs ast.Expr, rhs ast.Expr, pos token.Pos) ast.Expr {
    infix_pos := if pos.id != 0 || pos.offset != 0 {
        pos
    } else {
        t.next_synth_pos()
    }
    return ast.Expr(ast.InfixExpr{
        op:  op
        lhs: lhs
        rhs: rhs
        pos: infix_pos
    })
}

fn (mut t Transformer) make_infix_expr(op token.Token, lhs ast.Expr, rhs ast.Expr) ast.Expr {
    return t.make_infix_expr_at(op, lhs, rhs, token.Pos{})
}

// synth_selector creates a typed SelectorExpr with a unique synthesized position
// and registers its type in the environment so downstream passes can resolve it.
fn (mut t Transformer) open_scope() {
    t.scope = types.new_scope(t.scope)
}

// close_scope returns to the parent scope
fn (mut t Transformer) close_scope() {
    if t.scope != unsafe { nil } {
        t.scope = t.scope.parent
    }
}

// is_var_enum checks if a variable's type is an enum
fn (t &Transformer) is_var_enum(name string) ?string {
    typ := t.lookup_var_type(name) or { return none }
    if typ is types.Enum {
        return typ.name
    }
    return none
}

fn generic_ref_short_name(expr ast.Expr) string {
    if !expr_has_valid_data(expr) {
        return ''
    }
    return match expr {
        ast.Ident {
            expr.name
        }
        ast.SelectorExpr {
            expr.rhs.name
        }
        ast.GenericArgs {
            generic_ref_short_name(expr.lhs)
        }
        ast.GenericArgOrIndexExpr {
            generic_ref_short_name(expr.lhs)
        }
        ast.IndexExpr {
            generic_ref_short_name(expr.lhs)
        }
        ast.ParenExpr {
            generic_ref_short_name(expr.expr)
        }
        else {
            ''
        }
    }
}

fn generic_ref_short_name_cursor(expr ast.Cursor) string {
    if !expr.is_valid() {
        return ''
    }
    return match expr.kind() {
        .expr_ident {
            expr.name()
        }
        .expr_selector {
            rhs := expr.edge(1)
            if rhs.kind() == .expr_ident {
                rhs.name()
            } else {
                ''
            }
        }
        .expr_generic_args, .expr_generic_arg_or_index, .expr_index, .expr_paren {
            generic_ref_short_name_cursor(expr.edge(0))
        }
        else {
            ''
        }
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs(files []ast.File) {
    t.collect_generic_fn_decl_names(files)
    for file in files {
        for stmt in file.stmts {
            t.collect_generic_fn_value_refs_in_stmt(stmt, false)
        }
    }
    t.collect_generic_fn_value_dependencies()
}

fn (mut t Transformer) collect_generic_fn_value_refs_from_flat(flat &ast.FlatAst) {
    t.collect_generic_fn_decl_names_from_flat(flat)
    for i in 0 .. flat.files.len {
        stmts := flat.file_cursor(i).stmts()
        for j in 0 .. stmts.len() {
            t.collect_generic_fn_value_refs_in_stmt_cursor(stmts.at(j), false)
        }
    }
    t.collect_generic_fn_value_dependencies()
}

fn (mut t Transformer) collect_generic_fn_decl_names(files []ast.File) {
    for file in files {
        for stmt in file.stmts {
            t.collect_generic_fn_decl_names_in_stmt(stmt)
        }
    }
}

fn (mut t Transformer) collect_generic_fn_decl_names_from_flat(flat &ast.FlatAst) {
    for i in 0 .. flat.files.len {
        stmts := flat.file_cursor(i).stmts()
        for j in 0 .. stmts.len() {
            t.collect_generic_fn_decl_names_in_stmt_cursor(stmts.at(j))
        }
    }
}

fn has_non_lifetime_generic_params_cursor(params ast.CursorList) bool {
    for i in 0 .. params.len() {
        if params.at(i).kind() != .expr_lifetime {
            return true
        }
    }
    return false
}

fn (mut t Transformer) collect_generic_fn_decl_names_in_stmt_cursor(stmt ast.Cursor) {
    if !stmt.is_valid() {
        return
    }
    match stmt.kind() {
        .stmt_comptime {
            t.collect_generic_fn_decl_names_in_stmt_cursor(stmt.edge(0))
        }
        .stmt_expr {
            t.collect_generic_fn_decl_names_in_expr_cursor(stmt.edge(0))
        }
        .stmt_fn_decl {
            generic_params := stmt.edge(1).list_at(0)
            body := stmt.list_at(3)
            if has_non_lifetime_generic_params_cursor(generic_params) {
                t.generic_fn_decl_names[stmt.name()] = true
                t.generic_fn_decl_body_cursors[stmt.name()] = body
            }
            for i in 0 .. body.len() {
                t.collect_generic_fn_decl_names_in_stmt_cursor(body.at(i))
            }
        }
        else {}
    }
}

fn (mut t Transformer) collect_generic_fn_decl_names_in_expr_cursor(expr ast.Cursor) {
    if !expr.is_valid() {
        return
    }
    match expr.kind() {
        .expr_comptime {
            t.collect_generic_fn_decl_names_in_expr_cursor(expr.edge(0))
        }
        .expr_if {
            if expr.edge_count() > 2 {
                for i in 2 .. expr.edge_count() {
                    t.collect_generic_fn_decl_names_in_stmt_cursor(expr.edge(i))
                }
            }
            t.collect_generic_fn_decl_names_in_expr_cursor(expr.edge(1))
        }
        else {}
    }
}

fn (mut t Transformer) collect_generic_fn_decl_names_in_stmt(stmt ast.Stmt) {
    if !stmt_has_valid_data(stmt) {
        return
    }
    match stmt {
        ast.ComptimeStmt {
            t.collect_generic_fn_decl_names_in_stmt(stmt.stmt)
        }
        ast.ExprStmt {
            t.collect_generic_fn_decl_names_in_expr(stmt.expr)
        }
        ast.FnDecl {
            if has_non_lifetime_generic_params(stmt.typ.generic_params) {
                t.generic_fn_decl_names[stmt.name] = true
                t.generic_fn_decl_stmts[stmt.name] = stmt.stmts
            }
            for body_stmt in stmt.stmts {
                t.collect_generic_fn_decl_names_in_stmt(body_stmt)
            }
        }
        else {}
    }
}

fn (mut t Transformer) collect_generic_fn_decl_names_in_expr(expr ast.Expr) {
    if !expr_has_valid_data(expr) {
        return
    }
    match expr {
        ast.ComptimeExpr {
            t.collect_generic_fn_decl_names_in_expr(expr.expr)
        }
        ast.IfExpr {
            for stmt in expr.stmts {
                t.collect_generic_fn_decl_names_in_stmt(stmt)
            }
            t.collect_generic_fn_decl_names_in_expr(expr.else_expr)
        }
        else {}
    }
}

fn (mut t Transformer) collect_generic_fn_value_dependencies() {
    mut processed := map[string]bool{}
    for {
        mut progressed := false
        for name, _ in t.generic_fn_value_names {
            if name in processed {
                continue
            }
            processed[name] = true
            progressed = true
            if body := t.generic_fn_decl_body_cursors[name] {
                t.collect_generic_fn_value_refs_in_stmt_list_cursor(body, true)
            } else if stmts := t.generic_fn_decl_stmts[name] {
                t.collect_generic_fn_value_refs_in_stmts(stmts, true)
            }
        }
        if !progressed {
            break
        }
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_stmts(stmts []ast.Stmt, include_generic_calls bool) {
    for stmt in stmts {
        t.collect_generic_fn_value_refs_in_stmt(stmt, include_generic_calls)
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_expr_cursor(expr ast.Cursor, include_generic_calls bool, in_call_lhs bool) {
    if !expr.is_valid() {
        return
    }
    match expr.kind() {
        .expr_array_init {
            for i in 5 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i), include_generic_calls,
                    false)
            }
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(2), include_generic_calls,
                false)
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(3), include_generic_calls,
                false)
        }
        .expr_as_cast {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
        }
        .expr_assoc {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
            for i in 2 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i).edge(0),
                    include_generic_calls, false)
            }
        }
        .expr_call {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                true)
            for i in 1 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i), include_generic_calls,
                    false)
            }
        }
        .expr_call_or_cast {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
        }
        .expr_cast {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
        }
        .expr_comptime, .expr_modifier, .expr_postfix, .expr_prefix, .expr_sql {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
        }
        .expr_fn_literal {
            captured_len := expr.extra_int()
            for i in 0 .. captured_len {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1 + i),
                    include_generic_calls, false)
            }
            for i in (1 + captured_len) .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(i), include_generic_calls)
            }
        }
        .expr_generic_args {
            base_name := generic_ref_short_name_cursor(expr.edge(0))
            if (include_generic_calls || !in_call_lhs) && base_name in t.generic_fn_decl_names {
                t.generic_fn_value_names[base_name] = true
            }
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                in_call_lhs)
            for i in 1 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i), include_generic_calls,
                    false)
            }
        }
        .expr_generic_arg_or_index {
            base_name := generic_ref_short_name_cursor(expr.edge(0))
            if (include_generic_calls || !in_call_lhs) && base_name in t.generic_fn_decl_names {
                t.generic_fn_value_names[base_name] = true
            }
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                in_call_lhs)
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
        }
        .expr_if {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
            for i in 2 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(i), include_generic_calls)
            }
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
        }
        .expr_if_guard {
            t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(0), include_generic_calls)
        }
        .expr_index {
            base_name := generic_ref_short_name_cursor(expr.edge(0))
            if (include_generic_calls || !in_call_lhs) && base_name in t.generic_fn_decl_names {
                t.generic_fn_value_names[base_name] = true
            }
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                in_call_lhs)
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
        }
        .expr_infix, .expr_range {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
        }
        .expr_init {
            for i in 1 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i).edge(0),
                    include_generic_calls, false)
            }
        }
        .expr_keyword_operator, .expr_tuple {
            for i in 0 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i), include_generic_calls,
                    false)
            }
        }
        .expr_lambda {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
        }
        .expr_lock {
            packed := u32(expr.extra_int())
            lock_len := int(packed & 0xFFFF)
            rlock_len := int((packed >> 16) & 0xFFFF)
            for i in 0 .. lock_len {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i), include_generic_calls,
                    false)
            }
            for i in lock_len .. (lock_len + rlock_len) {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i), include_generic_calls,
                    false)
            }
            for i in (lock_len + rlock_len) .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(i), include_generic_calls)
            }
        }
        .expr_map_init {
            keys_len := expr.extra_int()
            for i in 0 .. keys_len {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1 + i),
                    include_generic_calls, false)
            }
            for i in (1 + keys_len) .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(i), include_generic_calls,
                    false)
            }
        }
        .expr_match {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
            for i in 1 .. expr.edge_count() {
                branch := expr.edge(i)
                conds := branch.list_at(0)
                for j in 0 .. conds.len() {
                    t.collect_generic_fn_value_refs_in_expr_cursor(conds.at(j),
                        include_generic_calls, false)
                }
                stmts := branch.list_at(1)
                for j in 0 .. stmts.len() {
                    t.collect_generic_fn_value_refs_in_stmt_cursor(stmts.at(j),
                        include_generic_calls)
                }
            }
        }
        .expr_or {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
            for i in 1 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(i), include_generic_calls)
            }
        }
        .expr_paren {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                in_call_lhs)
        }
        .expr_select {
            t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(0), include_generic_calls)
            for i in 2 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(i), include_generic_calls)
            }
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(1), include_generic_calls,
                false)
        }
        .expr_selector {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                in_call_lhs)
        }
        .expr_string_inter {
            inters := expr.list_at(1)
            for i in 0 .. inters.len() {
                inter := inters.at(i)
                t.collect_generic_fn_value_refs_in_expr_cursor(inter.edge(0),
                    include_generic_calls, false)
                t.collect_generic_fn_value_refs_in_expr_cursor(inter.edge(1),
                    include_generic_calls, false)
            }
        }
        .expr_unsafe {
            for i in 0 .. expr.edge_count() {
                t.collect_generic_fn_value_refs_in_stmt_cursor(expr.edge(i), include_generic_calls)
            }
        }
        .aux_field_init {
            t.collect_generic_fn_value_refs_in_expr_cursor(expr.edge(0), include_generic_calls,
                false)
        }
        else {}
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_stmt_edges_cursor(stmt ast.Cursor, start int, include_generic_calls bool) {
    if start >= stmt.edge_count() {
        return
    }
    for i in start .. stmt.edge_count() {
        t.collect_generic_fn_value_refs_in_stmt_cursor(stmt.edge(i), include_generic_calls)
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_field_values_cursor(fields ast.CursorList, value_edge int, include_generic_calls bool) {
    for i in 0 .. fields.len() {
        t.collect_generic_fn_value_refs_in_expr_cursor(fields.at(i).edge(value_edge),
            include_generic_calls, false)
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_stmt_cursor(stmt ast.Cursor, include_generic_calls bool) {
    if !stmt.is_valid() {
        return
    }
    match stmt.kind() {
        .stmt_assert {
            t.collect_generic_fn_value_refs_in_expr_cursor(stmt.edge(0), include_generic_calls,
                false)
            t.collect_generic_fn_value_refs_in_expr_cursor(stmt.edge(1), include_generic_calls,
                false)
        }
        .stmt_assign {
            lhs_len := stmt.extra_int()
            if lhs_len < stmt.edge_count() {
                for i in lhs_len .. stmt.edge_count() {
                    t.collect_generic_fn_value_refs_in_expr_cursor(stmt.edge(i),
                        include_generic_calls, false)
                }
            }
        }
        .stmt_block {
            t.collect_generic_fn_value_refs_in_stmt_edges_cursor(stmt, 0, include_generic_calls)
        }
        .stmt_comptime {
            t.collect_generic_fn_value_refs_in_stmt_cursor(stmt.edge(0), include_generic_calls)
        }
        .stmt_const_decl {
            t.collect_generic_fn_value_refs_in_field_values_cursor(stmt.list_at(0), 0,
                include_generic_calls)
        }
        .stmt_defer {
            t.collect_generic_fn_value_refs_in_stmt_edges_cursor(stmt, 0, include_generic_calls)
        }
        .stmt_enum_decl {
            t.collect_generic_fn_value_refs_in_field_values_cursor(stmt.list_at(2), 1,
                include_generic_calls)
        }
        .stmt_expr {
            t.collect_generic_fn_value_refs_in_expr_cursor(stmt.edge(0), include_generic_calls,
                false)
        }
        .stmt_fn_decl {
            t.collect_generic_fn_value_refs_in_stmt_list_cursor(stmt.list_at(3),
                include_generic_calls)
        }
        .stmt_for_in {
            t.collect_generic_fn_value_refs_in_expr_cursor(stmt.edge(2), include_generic_calls,
                false)
        }
        .stmt_for {
            t.collect_generic_fn_value_refs_in_stmt_cursor(stmt.edge(0), include_generic_calls)
            t.collect_generic_fn_value_refs_in_expr_cursor(stmt.edge(1), include_generic_calls,
                false)
            t.collect_generic_fn_value_refs_in_stmt_cursor(stmt.edge(2), include_generic_calls)
            t.collect_generic_fn_value_refs_in_stmt_edges_cursor(stmt, 3, include_generic_calls)
        }
        .stmt_global_decl {
            t.collect_generic_fn_value_refs_in_field_values_cursor(stmt.list_at(1), 1,
                include_generic_calls)
        }
        .stmt_label {
            t.collect_generic_fn_value_refs_in_stmt_cursor(stmt.edge(0), include_generic_calls)
        }
        .stmt_return {
            for i in 0 .. stmt.edge_count() {
                t.collect_generic_fn_value_refs_in_expr_cursor(stmt.edge(i), include_generic_calls,
                    false)
            }
        }
        .stmt_struct_decl {
            t.collect_generic_fn_value_refs_in_field_values_cursor(stmt.list_at(4), 1,
                include_generic_calls)
        }
        else {}
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_stmt_list_cursor(stmts ast.CursorList, include_generic_calls bool) {
    for i in 0 .. stmts.len() {
        t.collect_generic_fn_value_refs_in_stmt_cursor(stmts.at(i), include_generic_calls)
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_stmt(stmt ast.Stmt, include_generic_calls bool) {
    if !stmt_has_valid_data(stmt) {
        return
    }
    match stmt {
        ast.AssertStmt {
            t.collect_generic_fn_value_refs_in_expr(stmt.expr, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_expr(stmt.extra, include_generic_calls, false)
        }
        ast.AssignStmt {
            for expr in stmt.rhs {
                t.collect_generic_fn_value_refs_in_expr(expr, include_generic_calls, false)
            }
        }
        ast.BlockStmt {
            t.collect_generic_fn_value_refs_in_stmts(stmt.stmts, include_generic_calls)
        }
        ast.ComptimeStmt {
            t.collect_generic_fn_value_refs_in_stmt(stmt.stmt, include_generic_calls)
        }
        ast.ConstDecl {
            for field in stmt.fields {
                t.collect_generic_fn_value_refs_in_expr(field.value, include_generic_calls, false)
            }
        }
        ast.DeferStmt {
            t.collect_generic_fn_value_refs_in_stmts(stmt.stmts, include_generic_calls)
        }
        ast.EnumDecl {
            for field in stmt.fields {
                t.collect_generic_fn_value_refs_in_expr(field.value, include_generic_calls, false)
            }
        }
        ast.ExprStmt {
            t.collect_generic_fn_value_refs_in_expr(stmt.expr, include_generic_calls, false)
        }
        ast.FnDecl {
            t.collect_generic_fn_value_refs_in_stmts(stmt.stmts, include_generic_calls)
        }
        ast.ForInStmt {
            t.collect_generic_fn_value_refs_in_expr(stmt.expr, include_generic_calls, false)
        }
        ast.ForStmt {
            t.collect_generic_fn_value_refs_in_stmt(stmt.init, include_generic_calls)
            t.collect_generic_fn_value_refs_in_expr(stmt.cond, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_stmt(stmt.post, include_generic_calls)
            t.collect_generic_fn_value_refs_in_stmts(stmt.stmts, include_generic_calls)
        }
        ast.GlobalDecl {
            for field in stmt.fields {
                t.collect_generic_fn_value_refs_in_expr(field.value, include_generic_calls, false)
            }
        }
        ast.LabelStmt {
            t.collect_generic_fn_value_refs_in_stmt(stmt.stmt, include_generic_calls)
        }
        ast.ReturnStmt {
            for expr in stmt.exprs {
                t.collect_generic_fn_value_refs_in_expr(expr, include_generic_calls, false)
            }
        }
        ast.StructDecl {
            for field in stmt.fields {
                t.collect_generic_fn_value_refs_in_expr(field.value, include_generic_calls, false)
            }
        }
        else {}
    }
}

fn (mut t Transformer) collect_generic_fn_value_refs_in_expr(expr ast.Expr, include_generic_calls bool, in_call_lhs bool) {
    if !expr_has_valid_data(expr) {
        return
    }
    match expr {
        ast.ArrayInitExpr {
            for item in expr.exprs {
                t.collect_generic_fn_value_refs_in_expr(item, include_generic_calls, false)
            }
            t.collect_generic_fn_value_refs_in_expr(expr.init, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_expr(expr.cap, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_expr(expr.len, include_generic_calls, false)
        }
        ast.AsCastExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.AssocExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
            for field in expr.fields {
                t.collect_generic_fn_value_refs_in_expr(field.value, include_generic_calls, false)
            }
        }
        ast.CallExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.lhs, include_generic_calls, true)
            for arg in expr.args {
                t.collect_generic_fn_value_refs_in_expr(arg, include_generic_calls, false)
            }
        }
        ast.CallOrCastExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.lhs, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.CastExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.ComptimeExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.FieldInit {
            t.collect_generic_fn_value_refs_in_expr(expr.value, include_generic_calls, false)
        }
        ast.FnLiteral {
            for captured in expr.captured_vars {
                t.collect_generic_fn_value_refs_in_expr(captured, include_generic_calls, false)
            }
            t.collect_generic_fn_value_refs_in_stmts(expr.stmts, include_generic_calls)
        }
        ast.GenericArgs {
            // Generic function values like `handler[A, X]` are instantiated later by
            // cgen. Roots are value-position refs; callees are added transitively.
            base_name := generic_ref_short_name(expr.lhs)
            if (include_generic_calls || !in_call_lhs) && base_name in t.generic_fn_decl_names {
                t.generic_fn_value_names[base_name] = true
            }
            t.collect_generic_fn_value_refs_in_expr(expr.lhs, include_generic_calls, in_call_lhs)
            for arg in expr.args {
                t.collect_generic_fn_value_refs_in_expr(arg, include_generic_calls, false)
            }
        }
        ast.GenericArgOrIndexExpr {
            base_name := generic_ref_short_name(expr.lhs)
            if (include_generic_calls || !in_call_lhs) && base_name in t.generic_fn_decl_names {
                t.generic_fn_value_names[base_name] = true
            }
            t.collect_generic_fn_value_refs_in_expr(expr.lhs, include_generic_calls, in_call_lhs)
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.IfExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.cond, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_stmts(expr.stmts, include_generic_calls)
            t.collect_generic_fn_value_refs_in_expr(expr.else_expr, include_generic_calls, false)
        }
        ast.IfGuardExpr {
            t.collect_generic_fn_value_refs_in_stmt(expr.stmt, include_generic_calls)
        }
        ast.IndexExpr {
            name := generic_ref_short_name(expr.lhs)
            if (include_generic_calls || !in_call_lhs) && name in t.generic_fn_decl_names {
                t.generic_fn_value_names[name] = true
            }
            t.collect_generic_fn_value_refs_in_expr(expr.lhs, include_generic_calls, in_call_lhs)
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.InfixExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.lhs, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_expr(expr.rhs, include_generic_calls, false)
        }
        ast.InitExpr {
            for field in expr.fields {
                t.collect_generic_fn_value_refs_in_expr(field.value, include_generic_calls, false)
            }
        }
        ast.KeywordOperator {
            for item in expr.exprs {
                t.collect_generic_fn_value_refs_in_expr(item, include_generic_calls, false)
            }
        }
        ast.LambdaExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.LockExpr {
            for lock_expr in expr.lock_exprs {
                t.collect_generic_fn_value_refs_in_expr(lock_expr, include_generic_calls, false)
            }
            for rlock_expr in expr.rlock_exprs {
                t.collect_generic_fn_value_refs_in_expr(rlock_expr, include_generic_calls, false)
            }
            t.collect_generic_fn_value_refs_in_stmts(expr.stmts, include_generic_calls)
        }
        ast.MapInitExpr {
            for key in expr.keys {
                t.collect_generic_fn_value_refs_in_expr(key, include_generic_calls, false)
            }
            for val in expr.vals {
                t.collect_generic_fn_value_refs_in_expr(val, include_generic_calls, false)
            }
        }
        ast.MatchExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
            for branch in expr.branches {
                for cond in branch.cond {
                    t.collect_generic_fn_value_refs_in_expr(cond, include_generic_calls, false)
                }
                t.collect_generic_fn_value_refs_in_stmts(branch.stmts, include_generic_calls)
            }
        }
        ast.ModifierExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.OrExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_stmts(expr.stmts, include_generic_calls)
        }
        ast.ParenExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, in_call_lhs)
        }
        ast.PostfixExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.PrefixExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.RangeExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.start, include_generic_calls, false)
            t.collect_generic_fn_value_refs_in_expr(expr.end, include_generic_calls, false)
        }
        ast.SelectExpr {
            t.collect_generic_fn_value_refs_in_stmt(expr.stmt, include_generic_calls)
            t.collect_generic_fn_value_refs_in_stmts(expr.stmts, include_generic_calls)
            t.collect_generic_fn_value_refs_in_expr(expr.next, include_generic_calls, false)
        }
        ast.SelectorExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.lhs, include_generic_calls, in_call_lhs)
        }
        ast.SqlExpr {
            t.collect_generic_fn_value_refs_in_expr(expr.expr, include_generic_calls, false)
        }
        ast.StringInterLiteral {
            for inter in expr.inters {
                t.collect_generic_fn_value_refs_in_expr(inter.expr, include_generic_calls, false)
                t.collect_generic_fn_value_refs_in_expr(inter.format_expr, include_generic_calls,
                    false)
            }
        }
        ast.Tuple {
            for item in expr.exprs {
                t.collect_generic_fn_value_refs_in_expr(item, include_generic_calls, false)
            }
        }
        ast.UnsafeExpr {
            t.collect_generic_fn_value_refs_in_stmts(expr.stmts, include_generic_calls)
        }
        else {}
    }
}

// pre_pass runs the sequential pre-pass: builds elided_fns and collects runtime const inits.
pub fn (mut t Transformer) pre_pass(files []ast.File) {
    t.collect_generic_fn_value_refs(files)
    // Pre-pass: scan all function declarations for conditional compilation attributes
    // to build elided_fns set before transforming call sites
    for file in files {
        for stmt in file.stmts {
            if stmt is ast.FnDecl {
                for attr in stmt.attributes {
                    if attr.comptime_cond !is ast.EmptyExpr {
                        if !t.eval_comptime_cond(attr.comptime_cond) {
                            t.elided_fns[stmt.name] = true
                        }
                    }
                }
            }
        }
    }
    // Pre-pass: collect const declarations that require runtime initialization.
    if !t.is_eval_backend() {
        t.collect_runtime_const_inits(files)
    }
    // Cache scope and method maps for lock-free access during transform.
    t.cache_env_maps()
    t.collect_sum_type_decl_variant_names(files)
}

// pre_pass_from_flat is the FlatAst-driven equivalent of pre_pass. It walks
// file-level stmt cursors so the transformer no longer depends on
// pre-rehydrated []ast.File or per-file []ast.Stmt arrays for its accumulators.
// The generic-function scans still reuse recursive legacy visitors; the
// conditional attribute and runtime-const scans are cursor-native.
pub fn (mut t Transformer) pre_pass_from_flat(flat &ast.FlatAst) {
    t.collect_generic_fn_value_refs_from_flat(flat)
    for i in 0 .. flat.files.len {
        stmts := flat.file_cursor(i).stmts()
        for j in 0 .. stmts.len() {
            stmt := stmts.at(j)
            if stmt.kind() != .stmt_fn_decl {
                continue
            }
            attrs := stmt.list_at(2)
            for ai in 0 .. attrs.len() {
                cond := attrs.at(ai).edge(1)
                if !cond.is_valid() || cond.kind() == .expr_empty {
                    continue
                }
                if !t.eval_comptime_cond_cursor(cond) {
                    t.elided_fns[stmt.name()] = true
                }
            }
        }
    }
    if !t.is_eval_backend() {
        t.collect_runtime_const_inits_from_flat(flat)
    }
    t.cache_env_maps()
    t.collect_sum_type_decl_variant_names_from_flat(flat)
}

// cache_env_maps snapshots the shared Environment maps into plain maps
// for lock-free access during parallel file transformation.
fn (mut t Transformer) cache_env_maps() {
    t.cached_scopes = t.env.snapshot_scopes()
    t.cached_scope_keys = t.cached_scopes.keys()
    t.cached_methods = t.env.snapshot_methods()
    t.cached_method_keys = t.cached_methods.keys()
    t.cached_fn_scopes = t.env.snapshot_fn_scopes()
    t.build_cached_imported_module_scopes()
    t.build_cached_struct_field_type_index()
    t.build_cached_fn_type_index()
    t.build_cached_method_base_index()
    mut by_short := map[string][]string{}
    for key in t.cached_method_keys {
        by_short[method_short_name(key)] << key
    }
    t.cached_method_keys_by_short = by_short.move()
}

// build_cached_imported_module_scopes precomputes, per module, the resolved
// scopes of the modules it imports (skipping self, C and unnamed entries).
// lookup_imported_var_type then iterates only this short list instead of
// rescanning and sorting the whole symbol table on every call. The import set
// is stable for the duration of a transform run (cached_scopes is snapshotted
// once in pre_pass), so a single precompute is safe.
fn (mut t Transformer) build_cached_imported_module_scopes() {
    mut by_module := map[string][]&types.Scope{}
    for module_name in t.cached_scope_keys {
        scope := t.cached_scopes[module_name] or { continue }
        mut imported_scopes := []&types.Scope{}
        for key, obj in scope.objects {
            if obj !is types.Module {
                continue
            }
            module_obj := obj as types.Module
            import_name := if module_obj.name != '' { module_obj.name } else { key }
            if import_name == '' || import_name == module_name || import_name == 'C' {
                continue
            }
            mut module_scope := module_obj.scope
            if module_scope == unsafe { nil } {
                module_scope = t.cached_scopes[import_name] or { continue }
            }
            imported_scopes << module_scope
        }
        by_module[module_name] = imported_scopes
    }
    t.cached_imported_module_scopes = by_module.move()
}

fn (mut t Transformer) build_cached_struct_field_type_index() {
    mut index := map[string]types.Type{}
    for module_name in t.cached_scope_keys {
        scope := t.cached_scopes[module_name] or { continue }
        for obj_name, obj in scope.objects {
            typ := transformer_object_type(obj) or { continue }
            if typ is types.Struct {
                add_struct_field_type_index_entries(mut index, module_name, obj_name, typ)
            }
        }
    }
    t.cached_struct_field_types = index.move()
}

fn add_struct_field_type_index_entries(mut index map[string]types.Type, module_name string, obj_name string, st types.Struct) {
    mut names := []string{cap: 4}
    if obj_name != '' {
        names << obj_name
    }
    if st.name != '' && st.name !in names {
        names << st.name
    }
    if module_name != '' && obj_name != '' && !obj_name.contains('__') {
        qualified := '${module_name}__${obj_name}'
        if qualified !in names {
            names << qualified
        }
    }
    for field in st.fields {
        if field.name == '' || !transformer_string_has_valid_data(field.name) {
            continue
        }
        for name in names {
            key := struct_field_generic_decl_key(name, field.name)
            if key !in index {
                index[key] = field.typ
            }
        }
        if module_name != '' && obj_name != '' {
            module_key := struct_field_lookup_cache_key(module_name, obj_name, field.name)
            if module_key !in index {
                index[module_key] = field.typ
            }
        }
        if module_name != '' && st.name.contains('__') {
            short_name := st.name.all_after_last('__')
            if short_name != '' {
                module_key := struct_field_lookup_cache_key(module_name, short_name, field.name)
                if module_key !in index {
                    index[module_key] = field.typ
                }
            }
        }
    }
}

fn struct_field_lookup_cache_key(module_name string, struct_name string, field_name string) string {
    return '${module_name}#${struct_name}.${field_name}'
}

fn (mut t Transformer) build_cached_fn_type_index() {
    mut fn_index := map[string]types.Type{}
    mut ret_index := map[string]types.Type{}
    for module_name in t.cached_scope_keys {
        scope := t.cached_scopes[module_name] or { continue }
        for fn_name, obj in scope.objects {
            if obj is types.Fn {
                fn_obj := obj as types.Fn
                typ := fn_obj.get_typ()
                if typ is types.FnType {
                    t.add_cached_fn_type_entry(mut fn_index, mut ret_index, module_name, fn_name,
                        typ)
                    short_module := short_module_name(module_name)
                    if short_module != module_name {
                        t.add_cached_fn_type_entry(mut fn_index, mut ret_index, short_module,
                            fn_name, typ)
                    }
                    any_key := '*#${fn_name}'
                    if any_key !in fn_index {
                        fn_index[any_key] = typ
                        if ret_type := typ.get_return_type() {
                            ret_index[any_key] = ret_type
                        }
                    }
                }
            }
        }
    }
    t.cached_fn_type_index = fn_index.move()
    t.cached_fn_return_type_index = ret_index.move()
}

fn (mut t Transformer) add_cached_fn_type_entry(mut fn_index map[string]types.Type, mut ret_index map[string]types.Type, module_name string, fn_name string, fn_type types.FnType) {
    key := '${module_name}#${fn_name}'
    if key in fn_index {
        return
    }
    fn_index[key] = fn_type
    if ret_type := fn_type.get_return_type() {
        ret_index[key] = ret_type
    }
}

fn short_module_name(module_name string) string {
    if module_name.contains('.') {
        return module_name.all_after_last('.')
    }
    if module_name.contains('__') {
        return module_name.all_after_last('__')
    }
    return module_name
}

// build_cached_method_base_index precomputes, for each type, a base-method-name
// -> FnType map so lookup_method_cached is O(1) instead of scanning every method
// and recomputing base names per call site. For each base name it keeps the
// first method (in snapshot order) whose type is an FnType, matching the old
// linear scan's "first base-or-exact match that is a FnType wins" semantics.
fn (mut t Transformer) build_cached_method_base_index() {
    // Iterate via keys()+index, not `for k, v in t.cached_methods`: v2's own
    // codegen mistypes the value of a `for k, v` over map[string][]&types.Fn as
    // []types.Fn (value array), breaking self-host.
    mut index := map[string]types.Type{}
    for type_name in t.cached_methods.keys() {
        methods := t.cached_methods[type_name] or { continue }
        for method in methods {
            typ := method.get_typ()
            if typ is types.FnType {
                base := generic_base_name_without_specialization(method.get_name())
                key := '${type_name}#${base}'
                if key !in index {
                    index[key] = typ
                }
            }
        }
    }
    t.cached_method_base_index = index.move()
}

// GeneratedFnsParts is the pure-computation bundle produced by
// `generated_fns_parts`. Holds the three already-routed buckets of
// auto-generated helper FnDecls: `core_fns` for the builtin module,
// `module_fns` keyed by source module name for module-prefixed helpers
// (e.g. `time__FormatDate__str`), and `user_fns` for everything else
// (typically main / user types).
pub struct GeneratedFnsParts {
pub:
    core_fns   []ast.Stmt
    module_fns map[string][]ast.Stmt
    user_fns   []ast.Stmt
}

// generated_fns_parts is the pure-computation extraction of the
// "collect + route" segment previously inline in `post_pass`. Runs each
// `generate_*_functions` helper that has a non-empty needed-list (str,
// clone, sort-comparator, array-method, go-wrapper), then routes each
// emitted FnDecl by name: `is_core_generated_fn` → `core_fns`; otherwise
// `generated_fn_module(name, files)` non-empty → `module_fns[mod]`;
// otherwise → `user_fns`. Returns `none` when no generator fires.
//
// Does NOT mutate `files` or any caller state (beyond the generators'
// own bookkeeping on `t`, which is part of their existing contract).
// Caller decides whether to splice the buckets into a legacy
// `[]ast.File` (via `post_pass`) or into a `FlatBuilder` (future
// `post_pass_to_flat`).
//
// Fifth Phase 5 (post_pass port) `_parts` extraction (completes the
// s144 punch list: runtime-const-init-fns, runtime-const-init-main-
// calls, live-reload, test-main, generated-fns split). Bit-equal:
// identical generator invocation order, identical per-stmt routing
// (FnDecl name → bucket), identical bucket-append order.
pub fn (mut t Transformer) generated_fns_parts(files []ast.File) ?GeneratedFnsParts {
    mut generated_fns := []ast.Stmt{}
    if t.needed_str_fns.len > 0 {
        generated_fns << t.generate_str_functions(files)
    }
    if t.needed_clone_fns.len > 0 {
        generated_fns << t.generate_clone_functions()
    }
    if t.needed_sort_fns.len > 0 {
        generated_fns << t.generate_sort_comparator_functions()
    }
    if t.needed_array_contains_fns.len > 0 || t.needed_array_index_fns.len > 0
        || t.needed_array_last_index_fns.len > 0 {
        generated_fns << t.generate_array_method_functions()
    }
    if t.needed_go_wrappers.len > 0 {
        generated_fns << t.generate_go_wrapper_functions()
    }
    if generated_fns.len == 0 {
        return none
    }
    mut core_fns := []ast.Stmt{}
    mut user_fns := []ast.Stmt{}
    mut module_fns := map[string][]ast.Stmt{}
    for gf in generated_fns {
        mut is_core := false
        mut fn_module := ''
        if gf is ast.FnDecl {
            is_core = is_core_generated_fn(gf.name)
            if !is_core {
                // Check if function name has a module prefix (e.g., time__FormatDate__str)
                // Extract module name and route to correct module file.
                fn_module = generated_fn_module(gf.name, files)
            }
        }
        if is_core {
            core_fns << gf
        } else if fn_module != '' {
            module_fns[fn_module] << gf
        } else {
            user_fns << gf
        }
    }
    return GeneratedFnsParts{
        core_fns:   core_fns
        module_fns: module_fns
        user_fns:   user_fns
    }
}

// generated_fns_parts_from_flat is the FlatAst-input counterpart to
// `generated_fns_parts`. Same generators, same bucket layout, same
// per-stmt routing — only the two `[]ast.File` consumers change:
//   - `generate_str_functions(files)` is replaced with
//     `generate_str_functions_with_explicit(explicit_str_fns)` where
//     `explicit_str_fns` comes from `explicit_str_method_fn_names_from_flat`
//     (s165).
//   - `generated_fn_module(name, files)` is replaced with
//     `generated_fn_module_from_flat(name, flat)` (s164).
//
// Lets `_via_driver` wedges compute `GeneratedFnsParts` from `&builder.flat`
// instead of `result []ast.File`, so the parts computation no longer pins
// the un-post_pass'd legacy file array.
pub fn (mut t Transformer) generated_fns_parts_from_flat(flat &ast.FlatAst) ?GeneratedFnsParts {
    explicit_str_fns := t.explicit_str_method_fn_names_from_flat(flat)
    mut generated_fns := []ast.Stmt{}
    if t.needed_str_fns.len > 0 {
        generated_fns << t.generate_str_functions_with_explicit(explicit_str_fns)
    }
    if t.needed_clone_fns.len > 0 {
        generated_fns << t.generate_clone_functions()
    }
    if t.needed_sort_fns.len > 0 {
        generated_fns << t.generate_sort_comparator_functions()
    }
    if t.needed_array_contains_fns.len > 0 || t.needed_array_index_fns.len > 0
        || t.needed_array_last_index_fns.len > 0 {
        generated_fns << t.generate_array_method_functions()
    }
    if t.needed_go_wrappers.len > 0 {
        generated_fns << t.generate_go_wrapper_functions()
    }
    if generated_fns.len == 0 {
        return none
    }
    mut core_fns := []ast.Stmt{}
    mut user_fns := []ast.Stmt{}
    mut module_fns := map[string][]ast.Stmt{}
    for gf in generated_fns {
        mut is_core := false
        mut fn_module := ''
        if gf is ast.FnDecl {
            is_core = is_core_generated_fn(gf.name)
            if !is_core {
                fn_module = generated_fn_module_from_flat(gf.name, flat)
            }
        }
        if is_core {
            core_fns << gf
        } else if fn_module != '' {
            module_fns[fn_module] << gf
        } else {
            user_fns << gf
        }
    }
    return GeneratedFnsParts{
        core_fns:   core_fns
        module_fns: module_fns
        user_fns:   user_fns
    }
}

// find_flat_file_idx_by_mod returns the first index into `flat.files` whose
// mod string equals `mod_name`, or -1 if no such file is registered.
// Mirrors the linear `for i, file in files { if file.mod == mod_name {...} }`
// scans inline in legacy `post_pass`.
fn find_flat_file_idx_by_mod(flat &ast.FlatAst, mod_name string) int {
    for i in 0 .. flat.files.len {
        if flat.string_at(flat.files[i].mod_idx) == mod_name {
            return i
        }
    }
    return -1
}

// inject_generated_fns_to_files is the legacy `[]ast.File` splice for
// `GeneratedFnsParts`. Extracted from `post_pass` so the splice can be
// invoked from tests as the reference for the flat-aware port (s153)
// without re-running the full generator pipeline. Behaviour is bit-equal
// to the previous inline routing:
//
//   1. `core_fns` → builtin file (fallback: append to `user_fns` if no
//      builtin file is registered).
//   2. `module_fns[mod]` → mod file (fallback: append to `user_fns` if no
//      mod file is registered).
//   3. `user_fns` → main file → builtin file → last file (3-tier
//      fallback ordering).
//
// Each splice rebuilds the target `ast.File` with the existing attrs +
// imports preserved and the new FnDecls appended after the existing
// stmts. Map iteration over `module_fns` relies on V's insertion-ordered
// DenseArray semantics.
fn inject_generated_fns_to_files(mut result []ast.File, parts GeneratedFnsParts) {
    core_fns := unsafe { parts.core_fns }
    mut user_fns := unsafe { parts.user_fns }
    module_fns := unsafe { parts.module_fns }
    if core_fns.len > 0 {
        mut builtin_idx := -1
        for i, file in result {
            if file.mod == 'builtin' {
                builtin_idx = i
                break
            }
        }
        if builtin_idx >= 0 {
            file := result[builtin_idx]
            mut new_stmts := []ast.Stmt{cap: file.stmts.len + core_fns.len}
            for stmt in file.stmts {
                new_stmts << stmt
            }
            for fn_decl in core_fns {
                new_stmts << fn_decl
            }
            result[builtin_idx] = ast.File{
                attributes: file.attributes
                mod:        file.mod
                name:       file.name
                stmts:      new_stmts
                imports:    file.imports
            }
        } else {
            user_fns << core_fns
        }
    }
    for mod_name, fns in module_fns {
        mut mod_idx := -1
        for i, file in result {
            if file.mod == mod_name {
                mod_idx = i
                break
            }
        }
        if mod_idx >= 0 {
            file := result[mod_idx]
            mut new_stmts := []ast.Stmt{cap: file.stmts.len + fns.len}
            for stmt in file.stmts {
                new_stmts << stmt
            }
            for fn_decl in fns {
                new_stmts << fn_decl
            }
            result[mod_idx] = ast.File{
                attributes: file.attributes
                mod:        file.mod
                name:       file.name
                stmts:      new_stmts
                imports:    file.imports
            }
        } else {
            for fn_decl in fns {
                user_fns << fn_decl
            }
        }
    }
    if user_fns.len > 0 {
        mut target_idx := -1
        for i, file in result {
            if file.mod == 'main' {
                target_idx = i
                break
            }
        }
        if target_idx == -1 {
            for i, file in result {
                if file.mod == 'builtin' {
                    target_idx = i
                    break
                }
            }
        }
        if target_idx == -1 && result.len > 0 {
            target_idx = result.len - 1
        }
        if target_idx >= 0 {
            file := result[target_idx]
            mut new_stmts := []ast.Stmt{cap: file.stmts.len + user_fns.len}
            for stmt in file.stmts {
                new_stmts << stmt
            }
            for fn_decl in user_fns {
                new_stmts << fn_decl
            }
            result[target_idx] = ast.File{
                attributes: file.attributes
                mod:        file.mod
                name:       file.name
                stmts:      new_stmts
                imports:    file.imports
            }
        }
    }
}

// inject_generated_fns_to_flat is the FlatBuilder-side splice counterpart
// to the 3-way `generated_fns_parts` routing previously inline in
// `post_pass`. Takes a pre-computed `GeneratedFnsParts` (caller still
// runs `t.generated_fns_parts(files)` against legacy `[]ast.File` because
// the generators themselves haven't been ported to flat yet) and folds
// each bucket into the appropriate FlatBuilder file root via
// `out.append_file_stmts` (s150's seed primitive):
//
//   1. `core_fns` → builtin file (fallback: append to `user_fns` if no
//      builtin file registered, mirroring legacy `user_fns << core_fns`).
//   2. `module_fns[mod]` → mod file (fallback: append to `user_fns` if no
//      mod file registered).
//   3. `user_fns` → main file → builtin file → last file (legacy 3-tier
//      fallback ordering preserved).
//
// Each splice emits its FnDecls via `out.emit_stmt`, collects the ids,
// then a single `out.append_file_stmts(idx, ids)` call rebuilds the file
// root. Map iteration over `module_fns` relies on V's insertion-ordered
// DenseArray semantics so bit-equality is preserved.
//
// Third flat-aware port (s153, completes the 3 append-only post_pass
// steps from s150's punch list: embed_file_helper, test_main,
// generated_fns). Pinned by 3-case test in
// `inject_generated_fns_to_flat_test.v`.
pub fn (mut t Transformer) inject_generated_fns_to_flat(mut out ast.FlatBuilder, parts GeneratedFnsParts) {
    core_fns := unsafe { parts.core_fns }
    mut user_fns := unsafe { parts.user_fns }
    module_fns := unsafe { parts.module_fns }
    // Bucket 1: core_fns → builtin file (fallback: user_fns).
    if core_fns.len > 0 {
        builtin_idx := find_flat_file_idx_by_mod(&out.flat, 'builtin')
        if builtin_idx >= 0 {
            mut ids := []ast.FlatNodeId{cap: core_fns.len}
            for fn_decl in core_fns {
                ids << out.emit_stmt(fn_decl)
            }
            out.append_file_stmts(builtin_idx, ids)
        } else {
            user_fns << core_fns
        }
    }
    // Bucket 2: module_fns[mod] → mod file (fallback: user_fns).
    for mod_name, fns in module_fns {
        mod_idx := find_flat_file_idx_by_mod(&out.flat, mod_name)
        if mod_idx >= 0 {
            mut ids := []ast.FlatNodeId{cap: fns.len}
            for fn_decl in fns {
                ids << out.emit_stmt(fn_decl)
            }
            out.append_file_stmts(mod_idx, ids)
        } else {
            for fn_decl in fns {
                user_fns << fn_decl
            }
        }
    }
    // Bucket 3: user_fns → main → builtin → last file.
    if user_fns.len > 0 {
        mut target_idx := find_flat_file_idx_by_mod(&out.flat, 'main')
        if target_idx == -1 {
            target_idx = find_flat_file_idx_by_mod(&out.flat, 'builtin')
        }
        if target_idx == -1 && out.flat.files.len > 0 {
            target_idx = out.flat.files.len - 1
        }
        if target_idx >= 0 {
            mut ids := []ast.FlatNodeId{cap: user_fns.len}
            for fn_decl in user_fns {
                ids << out.emit_stmt(fn_decl)
            }
            out.append_file_stmts(target_idx, ids)
        }
    }
}

// post_pass runs the sequential post-pass: injects runtime const init fns, generated functions,
// test main, live reload, and propagates types.
pub fn (mut t Transformer) post_pass(mut result []ast.File) {
    t.post_pass_files_with_generated_parts(mut result, none)
    t.apply_post_pass_tail(result)
}

// post_pass_files_with_generated_parts runs the file-mutating post-pass steps.
pub fn (mut t Transformer) post_pass_files_with_generated_parts(mut result []ast.File, generated_parts ?GeneratedFnsParts) {
    if !t.is_eval_backend() {
        t.inject_runtime_const_init_fns(mut result)
    }
    if t.needed_embed_file_helper {
        t.inject_embed_file_helper(mut result)
    }
    // Generate auto helper functions. Split into two groups:
    // 1. Core functions (for standard types like string, int, etc.) go in the builtin
    //    module file because cached builtin.o/vlib.o reference them. They must always
    //    be available regardless of which program is being compiled.
    // 2. User-type functions (e.g. Array_Test2_str) go in the main module file because
    //    they would pollute the cache and cause undefined symbol errors when a different
    //    program reuses the same cache.
    if parts := generated_parts {
        inject_generated_fns_to_files(mut result, parts)
    } else {
        if parts := t.generated_fns_parts(result) {
            inject_generated_fns_to_files(mut result, parts)
        }
    }
    if t.pref == unsafe { nil } || t.pref.backend != .cleanc {
        t.inject_test_main(mut result)
    }
    if !t.is_eval_backend() {
        t.inject_main_runtime_const_init_calls(mut result)
    }
    if t.is_native_be {
        t.inject_live_reload(mut result)
    }
}

// post_pass_to_flat is the FlatBuilder-side driver counterpart to
// `post_pass`. Runs the six file-mutating steps that legacy `post_pass`
// performs, in identical order, on a `FlatBuilder` instead of a legacy
// `[]ast.File`. Closes the post_pass port arc opened in s150 and
// completed in s151/s152/s153/s155/s159/s160.
//
// Order mirrors legacy `post_pass`:
//   1. `inject_runtime_const_init_fns_to_flat` (skip on eval backend)
//   2. `inject_embed_file_helper_to_flat` (gated by `needed_embed_file_helper`)
//   3. `inject_generated_fns_to_flat` (gated by `generated_parts != none`)
//   4. `inject_test_main_to_flat` (skip on cleanc backend)
//   5. `inject_main_runtime_const_init_to_flat` (skip on eval backend)
//   6. `inject_live_reload_to_flat` (only on native backend)
//
// `generated_parts` is computed by the caller via `t.generated_fns_parts`
// against whatever file source it has (legacy `[]ast.File` today). Once
// `generated_fns_parts_from_flat` lands, callers can drop the legacy file
// list entirely.
//
// The non-file post_pass tail (synth_types accumulator, fn_scopes
// propagation, `propagate_types`) is NOT included here — it operates on
// `t.env` and legacy `[]ast.File` respectively, not on `out`, so callers
// keep running it after this driver returns. `propagate_types` in
// particular still consumes `[]ast.File` and is already gated to skip on
// the arm64 backend in legacy `post_pass`.
pub fn (mut t Transformer) post_pass_to_flat(mut out ast.FlatBuilder, generated_parts ?GeneratedFnsParts) {
    if !t.is_eval_backend() {
        t.inject_runtime_const_init_fns_to_flat(mut out)
    }
    if t.needed_embed_file_helper {
        t.inject_embed_file_helper_to_flat(mut out)
    }
    if parts := generated_parts {
        t.inject_generated_fns_to_flat(mut out, parts)
    }
    if t.pref == unsafe { nil } || t.pref.backend != .cleanc {
        t.inject_test_main_to_flat(mut out)
    }
    if !t.is_eval_backend() {
        t.inject_main_runtime_const_init_to_flat(mut out)
    }
    if t.is_native_be {
        t.inject_live_reload_to_flat(mut out)
    }
}

// apply_post_pass_tail runs the trailing portion of legacy `post_pass`
// that operates on `t.env` and `[]ast.File` rather than on a FlatBuilder:
//
//   1. Apply accumulated `synth_types` to the environment (via
//      `t.env.set_expr_type`).
//   2. Push `cached_fn_scopes` back to `t.env.fn_scopes`.
//   3. Run `propagate_types(files)` for non-arm64 backends.
//
// These three steps are NOT part of `post_pass_to_flat` because they don't
// touch the flat output. They are factored here so any caller routing
// through `post_pass_to_flat` (s162's `transform_files_to_flat_via_driver`
// and s163's parallel counterpart) can share a single tail implementation
// instead of duplicating private-field access at each call site.
pub fn (mut t Transformer) apply_post_pass_tail(files []ast.File) {
    for id, typ in t.synth_types {
        t.env.set_expr_type(id, typ)
    }
    lock t.env.fn_scopes {
        fn_scope_keys := t.cached_fn_scopes.keys()
        for k in fn_scope_keys {
            v := t.cached_fn_scopes[k] or { continue }
            t.env.fn_scopes[k] = v
        }
    }
    if t.pref == unsafe { nil } || t.pref.backend != .arm64 {
        t.propagate_types(files)
    }
}

// apply_post_pass_tail_from_flat is the FlatAst-input counterpart to
// `apply_post_pass_tail`. Same three steps (synth_types accumulator →
// `t.env.set_expr_type`, `cached_fn_scopes` propagation → `t.env.fn_scopes`,
// `propagate_types_from_flat(flat)` for non-arm64 backends), only the third
// step's input changes from `[]ast.File` to `&FlatAst`. Steps 1+2 don't
// touch the file/flat input at all — they only mutate `t.env` from
// pre-accumulated state on `t`. Lets `_via_driver` wedges drop the
// `apply_post_pass_tail(result)` call site (last `[]ast.File` consumer in
// the post_pass tail) in favour of `apply_post_pass_tail_from_flat(&builder.flat)`.
pub fn (mut t Transformer) apply_post_pass_tail_from_flat(flat &ast.FlatAst) {
    for id, typ in t.synth_types {
        t.env.set_expr_type(id, typ)
    }
    lock t.env.fn_scopes {
        fn_scope_keys := t.cached_fn_scopes.keys()
        for k in fn_scope_keys {
            v := t.cached_fn_scopes[k] or { continue }
            t.env.fn_scopes[k] = v
        }
    }
    if t.pref == unsafe { nil } || t.pref.backend != .arm64 {
        t.propagate_types_from_flat(flat)
    }
}

fn embed_file_helper_receiver() ast.Parameter {
    return ast.Parameter{
        name: 'ed'
        typ:  embed_file_helper_type_expr(token.Pos{})
    }
}

fn embed_file_helper_selector(field_name string) ast.Expr {
    return ast.Expr(ast.SelectorExpr{
        lhs: ast.Expr(ast.Ident{
            name: 'ed'
        })
        rhs: ast.Ident{
            name: field_name
        }
    })
}

fn embed_file_helper_method(name string, return_type ast.Expr, body []ast.Stmt) ast.Stmt {
    return ast.Stmt(ast.FnDecl{
        is_public: true
        is_method: true
        receiver:  embed_file_helper_receiver()
        name:      name
        typ:       ast.FnType{
            return_type: return_type
        }
        stmts:     body
    })
}

fn embed_file_helper_stmts() []ast.Stmt {
    return [
        ast.Stmt(ast.StructDecl{
            is_public: true
            name:      embed_file_helper_type_name
            fields:    [
                ast.FieldDecl{
                    name: '_data'
                    typ:  ast.Expr(ast.Ident{
                        name: 'string'
                    })
                },
                ast.FieldDecl{
                    name: 'len'
                    typ:  ast.Expr(ast.Ident{
                        name: 'int'
                    })
                },
                ast.FieldDecl{
                    name: 'path'
                    typ:  ast.Expr(ast.Ident{
                        name: 'string'
                    })
                },
                ast.FieldDecl{
                    name: 'apath'
                    typ:  ast.Expr(ast.Ident{
                        name: 'string'
                    })
                },
            ]
        }),
        embed_file_helper_method('to_string', ast.Expr(ast.Ident{
            name: 'string'
        }), [
            ast.Stmt(ast.ReturnStmt{
                exprs: [embed_file_helper_selector('_data')]
            }),
        ]),
        embed_file_helper_method('to_bytes', ast.Expr(ast.Type(ast.ArrayType{
            elem_type: ast.Expr(ast.Ident{
                name: 'u8'
            })
        })), [
            ast.Stmt(ast.ReturnStmt{
                exprs: [
                    ast.Expr(ast.CallExpr{
                        lhs: ast.Expr(ast.SelectorExpr{
                            lhs: embed_file_helper_selector('_data')
                            rhs: ast.Ident{
                                name: 'bytes'
                            }
                        })
                    }),
                ]
            }),
        ]),
        embed_file_helper_method('data', ast.Expr(ast.PrefixExpr{
            op:   .amp
            expr: ast.Expr(ast.Ident{
                name: 'u8'
            })
        }), [
            ast.Stmt(ast.ReturnStmt{
                exprs: [
                    ast.Expr(ast.SelectorExpr{
                        lhs: embed_file_helper_selector('_data')
                        rhs: ast.Ident{
                            name: 'str'
                        }
                    }),
                ]
            }),
        ]),
        embed_file_helper_method('free', ast.empty_expr, []ast.Stmt{}),
        embed_file_helper_method('str', ast.Expr(ast.Ident{
            name: 'string'
        }), [
            ast.Stmt(ast.ReturnStmt{
                exprs: [
                    embed_file_helper_selector('path'),
                ]
            }),
        ]),
    ]
}

// EmbedFileHelperParts is the pure-computation bundle produced by
// `inject_embed_file_helper_parts`. `builtin_idx` is the index of the
// `builtin` module file in the caller's `[]ast.File`; `extra_stmts` is
// the helper-decl set (StructDecl + 5 helper FnDecls) that should be
// appended to that file's stmts.
pub struct EmbedFileHelperParts {
pub:
    builtin_idx int
    extra_stmts []ast.Stmt
}

// inject_embed_file_helper_parts is the pure-computation extraction of
// the pre-splice state previously inline in `inject_embed_file_helper`.
// Locates the `builtin` module file (returns `none` if not present),
// scans its existing stmts for a `StructDecl` already named
// `embed_file_helper_type_name` (returns `none` if the helper is
// already injected — re-entry guard), and otherwise pairs the file
// index with a fresh `embed_file_helper_stmts()` payload.
//
// Does NOT mutate `files` or any caller state. Caller decides whether
// to splice `extra_stmts` into a legacy `[]ast.File` (via
// `inject_embed_file_helper`) or into a `FlatBuilder` (future
// `post_pass_to_flat`).
//
// Sixth Phase 5 (post_pass port) `_parts` extraction (closes the
// "every post_pass step has a `_parts` handle" symmetry — sibling to
// s144/s145/s146/s147/s148). Bit-equal: identical builtin-file lookup
// + identical re-entry guard + identical `embed_file_helper_stmts()`
// payload.
pub fn (mut t Transformer) inject_embed_file_helper_parts(files []ast.File) ?EmbedFileHelperParts {
    mut builtin_idx := -1
    for i, file in files {
        if file.mod == 'builtin' {
            builtin_idx = i
            break
        }
    }
    if builtin_idx < 0 {
        return none
    }
    file := files[builtin_idx]
    for stmt in file.stmts {
        if stmt is ast.StructDecl && stmt.name == embed_file_helper_type_name {
            return none
        }
    }
    return EmbedFileHelperParts{
        builtin_idx: builtin_idx
        extra_stmts: embed_file_helper_stmts()
    }
}

fn (mut t Transformer) inject_embed_file_helper(mut result []ast.File) {
    parts := t.inject_embed_file_helper_parts(result) or { return }
    file := result[parts.builtin_idx]
    mut new_stmts := []ast.Stmt{cap: file.stmts.len + parts.extra_stmts.len}
    for stmt in file.stmts {
        new_stmts << stmt
    }
    for stmt in parts.extra_stmts {
        new_stmts << stmt
    }
    result[parts.builtin_idx] = ast.File{
        attributes: file.attributes
        mod:        file.mod
        name:       file.name
        stmts:      new_stmts
        imports:    file.imports
    }
}

// inject_embed_file_helper_parts_from_flat is the flat-cursor sibling of
// `inject_embed_file_helper_parts`. Walks `flat.files` for the `builtin`
// module entry and scans its stmts via cursor for an existing StructDecl
// named `embed_file_helper_type_name` (re-entry guard). Returns the same
// `EmbedFileHelperParts` shape; the `builtin_idx` is into `flat.files`
// (which the legacy callers' `[]ast.File` and the FlatBuilder's
// `flat.files` share by construction).
//
// First flat-aware port of a post_pass `_parts` helper (s151, opens the
// per-step flat-aware sweep). Pinned by `flat_append_file_stmts_test.v`'s
// signature-parity invariant when wired in via `inject_embed_file_helper_to_flat`.
pub fn (mut t Transformer) inject_embed_file_helper_parts_from_flat(flat &ast.FlatAst) ?EmbedFileHelperParts {
    mut builtin_idx := -1
    for i in 0 .. flat.files.len {
        if flat.string_at(flat.files[i].mod_idx) == 'builtin' {
            builtin_idx = i
            break
        }
    }
    if builtin_idx < 0 {
        return none
    }
    stmts := flat.file_cursor(builtin_idx).stmts()
    for i in 0 .. stmts.len() {
        c := stmts.at(i)
        if c.kind() == .stmt_struct_decl && c.name() == embed_file_helper_type_name {
            return none
        }
    }
    return EmbedFileHelperParts{
        builtin_idx: builtin_idx
        extra_stmts: embed_file_helper_stmts()
    }
}

// inject_embed_file_helper_to_flat is the FlatBuilder-side splice
// counterpart to `inject_embed_file_helper` (legacy `[]ast.File` mutator).
// Emits each `parts.extra_stmts` into `out` via `out.emit_stmt`, then
// folds the resulting stmt ids into the file root via
// `out.append_file_stmts(builtin_idx, extra_ids)` (s150's seed primitive).
//
// Bit-equal w.r.t. `signature()` to running legacy
// `inject_embed_file_helper(mut files)` followed by
// `ast.flatten_files(files)`: same builtin-file routing, same helper
// stmt payload, same final file root edges (attrs / imports unchanged,
// stmts list extended by the same stmt ids).
pub fn (mut t Transformer) inject_embed_file_helper_to_flat(mut out ast.FlatBuilder) {
    parts := t.inject_embed_file_helper_parts_from_flat(&out.flat) or { return }
    mut extra_ids := []ast.FlatNodeId{cap: parts.extra_stmts.len}
    for stmt in parts.extra_stmts {
        extra_ids << out.emit_stmt(stmt)
    }
    out.append_file_stmts(parts.builtin_idx, extra_ids)
}

// transform_files transforms all files and returns transformed copies
pub fn (mut t Transformer) transform_files(files []ast.File) []ast.File {
    timing := os.getenv('V2_TTIME') != ''
    mut sw := time.new_stopwatch()
    t_print_mem('enter')
    t.pre_pass(files)
    t_print_mem('after pre_pass')
    if timing {
        eprintln('  [ttime] sequential pre_pass: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    files_to_transform := t.prepare_files_for_transform(files)
    t_print_mem('after prepare/monomorphize')
    if timing {
        eprintln('  [ttime] sequential prepare: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    mut result := []ast.File{cap: files_to_transform.len}
    for file in files_to_transform {
        result << t.transform_file(file)
    }
    t_print_mem('after per-file loop')
    if timing {
        eprintln('  [ttime] sequential per-file: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    t.post_pass(mut result)
    t_print_mem('after post_pass')
    if timing {
        eprintln('  [ttime] sequential post_pass: ${sw.elapsed().milliseconds()}ms')
    }
    return result
}

// transform_files_from_flat drives the same per-file transform pipeline
// but seeds the pre-pass accumulators from FlatAst rather than from the
// legacy ast.File list.
//
// Monomorphization needs the full file set up front (it builds a
// cross-file generic-decl index), so flat input is prepared once and then
// rehydrated one file at a time when `files` is empty.
pub fn (mut t Transformer) transform_files_from_flat(flat &ast.FlatAst, files []ast.File) []ast.File {
    mut result := t.transform_files_from_flat_no_post_pass(flat, files)
    t.post_pass(mut result)
    return result
}

// transform_files_from_flat_no_post_pass is the extraction of
// `transform_files_from_flat`'s per-file transform loop, without the
// trailing `post_pass` call. Both `transform_files_from_flat` (legacy
// wrapper, calls `post_pass` after) and
// `transform_files_to_flat_via_driver` (new flat-output path, calls
// `post_pass_to_flat` on the flattened output instead) call this helper.
fn (mut t Transformer) transform_files_from_flat_no_post_pass(flat &ast.FlatAst, files []ast.File) []ast.File {
    timing := os.getenv('V2_TTIME') != ''
    file_timing := os.getenv('V2_TTIME_FILES') != ''
    mut sw := time.new_stopwatch()
    t_print_mem('flat no-post enter')
    t.pre_pass_from_flat(flat)
    t_print_mem('flat no-post after pre_pass')
    if timing {
        eprintln('  [ttime] flat no-post pre_pass: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    if t.needs_full_files_for_transform() {
        if files.len == 0 {
            extra_stmts := t.prepare_flat_for_transform(flat)
            t_print_mem('flat no-post after prepare/monomorphize')
            if timing {
                eprintln('  [ttime] flat no-post prepare: ${sw.elapsed().milliseconds()}ms')
                sw = time.new_stopwatch()
            }
            mut result := []ast.File{cap: flat.files.len}
            for i in 0 .. flat.files.len {
                mut fsw := time.new_stopwatch()
                src_file := prepared_flat_file_for_transform(flat, extra_stmts, i) or { continue }
                result << t.transform_file(src_file)
                if file_timing {
                    eprintln('  [ttime-file] flat no-post: ${src_file.name} ${fsw.elapsed().milliseconds()}ms')
                }
            }
            t_print_mem('flat no-post after per-file loop')
            if timing {
                eprintln('  [ttime] flat no-post per-file: ${sw.elapsed().milliseconds()}ms')
            }
            return result
        }
        files_to_transform := t.prepare_files_for_transform(files)
        t_print_mem('flat no-post after prepare/monomorphize')
        if timing {
            eprintln('  [ttime] flat no-post prepare: ${sw.elapsed().milliseconds()}ms')
            sw = time.new_stopwatch()
        }
        mut result := []ast.File{cap: files_to_transform.len}
        for file in files_to_transform {
            mut fsw := time.new_stopwatch()
            result << t.transform_file(file)
            if file_timing {
                eprintln('  [ttime-file] flat no-post: ${file.name} ${fsw.elapsed().milliseconds()}ms')
            }
        }
        t_print_mem('flat no-post after per-file loop')
        if timing {
            eprintln('  [ttime] flat no-post per-file: ${sw.elapsed().milliseconds()}ms')
        }
        return result
    }
    if files.len > 0 {
        mut result := []ast.File{cap: files.len}
        for file in files {
            mut fsw := time.new_stopwatch()
            result << t.transform_file(file)
            if file_timing {
                eprintln('  [ttime-file] flat no-post: ${file.name} ${fsw.elapsed().milliseconds()}ms')
            }
        }
        t_print_mem('flat no-post after per-file loop')
        if timing {
            eprintln('  [ttime] flat no-post per-file: ${sw.elapsed().milliseconds()}ms')
        }
        return result
    }
    mut result := []ast.File{cap: flat.files.len}
    for i in 0 .. flat.files.len {
        mut fsw := time.new_stopwatch()
        src_file := flat_file_for_transform(flat, i, []ast.Stmt{}) or { continue }
        result << t.transform_file(src_file)
        if file_timing {
            eprintln('  [ttime-file] flat no-post: ${src_file.name} ${fsw.elapsed().milliseconds()}ms')
        }
    }
    t_print_mem('flat no-post after per-file loop')
    if timing {
        eprintln('  [ttime] flat no-post per-file: ${sw.elapsed().milliseconds()}ms')
    }
    return result
}

// transform_files_to_flat is the legacy-compatible flat-output entry point.
// It wraps transform_files_from_flat + ast.flatten_files and returns both the
// FlatAst and transformed files for callers that still need []ast.File.
//
// NO PRODUCTION CALLERS remain: the builder uses transform_flat_to_flat_direct
// (sequential) / transform_files_parallel_flat_direct (parallel) for every
// backend, and .v/eval rehydrate via flat.to_files() at the codegen boundary.
// Kept only as the legacy parity reference for the flat-diff test suite; delete
// together with the remaining decode-fallback arms once the cursor-native
// transform is complete.
pub fn (mut t Transformer) transform_files_to_flat(flat &ast.FlatAst, files []ast.File) (ast.FlatAst, []ast.File) {
    result := t.transform_files_from_flat(flat, files)
    return ast.flatten_files(result), result
}

// transform_files_to_flat_via_driver is the post_pass_to_flat-based
// counterpart to `transform_files_to_flat`. Same external shape (returns
// `(ast.FlatAst, []ast.File)`) but uses the s161 driver instead of the
// `legacy post_pass + flatten_files` boundary:
//
//   1. Per-file transform via `transform_files_from_flat_no_post_pass`
//      (skips legacy `post_pass`).
//   2. Compute `generated_fns_parts` against the un-post_pass'd result
//      (the parts helper walks `[]ast.File` to determine module routing
//      for generated fns; the file set is the same as legacy at this point).
//   3. Flatten the un-post_pass'd files into a fresh FlatBuilder.
//   4. Run `post_pass_to_flat(mut builder, generated_parts)` — the s161
//      driver appends/prepends/replaces stmts on the flat directly.
//   5. Apply the non-file post_pass tail (synth_types accumulator,
//      fn_scopes propagation, `propagate_types`) which mutates `t.env`
//      and `result` but not the flat output.
//
// Bit-equivalent to legacy in TREE STRUCTURE (each file's stmts list
// holds the same content) but NOT bit-equal in `signature()`: the
// `.file.extra` slot stores `intern(mod)` as a raw intern index, and the
// two paths intern strings in different orders (legacy interns
// post-pass-added strings DURING `flatten_files` walk, leaving later
// files' mod strings at large indices; new path interns all bare files
// first then post-pass-added strings AFTER, leaving later files' mod
// strings at small indices). Compare via per-file `subtree_signature` of
// the stmts list (file root edge 2) to assert structural parity.
//
// Memory: this avoids the legacy post_pass + flatten_files boundary but still
// returns []ast.File for compatibility consumers.
//
// NO PRODUCTION CALLERS remain (every backend transforms flat-direct; .v/eval
// rehydrate at the codegen boundary). Kept only as the legacy parity reference
// for tests; delete once the cursor-native transform is complete.
pub fn (mut t Transformer) transform_files_to_flat_via_driver(flat &ast.FlatAst, files []ast.File) (ast.FlatAst, []ast.File) {
    timing := os.getenv('V2_TTIME') != ''
    mut sw := time.new_stopwatch()
    mut result := t.transform_files_from_flat_no_post_pass(flat, files)
    t_print_mem('flat driver after no-post')
    if timing {
        eprintln('  [ttime] flat driver no-post: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    mut builder := ast.new_flat_builder()
    for file in result {
        builder.append_file(file)
    }
    t_print_mem('flat driver after append')
    if timing {
        eprintln('  [ttime] flat driver append: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    // Compute parts against the freshly-appended flat (s166): no longer
    // needs `result []ast.File` for explicit_str / module routing — both
    // `explicit_str_method_fn_names_from_flat` (s165) and
    // `generated_fn_module_from_flat` (s164) walk `builder.flat` directly.
    generated_parts := t.generated_fns_parts_from_flat(&builder.flat)
    t_print_mem('flat driver after generated parts')
    if timing {
        eprintln('  [ttime] flat driver generated parts: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    t.post_pass_to_flat(mut builder, generated_parts)
    t_print_mem('flat driver after post_pass_to_flat')
    if timing {
        eprintln('  [ttime] flat driver post_pass_to_flat: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    t.post_pass_files_with_generated_parts(mut result, generated_parts)
    t_print_mem('flat driver after files generated parts')
    if timing {
        eprintln('  [ttime] flat driver files generated parts: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    // The compatibility files now receive the same file-mutating post-pass
    // edits as the flat output, so run the non-file tail on those files for
    // downstream legacy consumers.
    t.apply_post_pass_tail(result)
    t_print_mem('flat driver after post_pass tail')
    if timing {
        eprintln('  [ttime] flat driver post_pass tail: ${sw.elapsed().milliseconds()}ms')
    }
    return builder.flat, result
}

// transform_files_to_flat_direct transforms `files` into a FlatAst without
// collecting the transformed legacy []ast.File result. The input still goes
// through the existing whole-program generic preparation, but each prepared file
// is emitted through transform_file_to_flat and is then immediately consumed by
// the FlatBuilder. This is the low-memory path used by native backends that can
// consume post-transform FlatAst directly.
pub fn (mut t Transformer) transform_files_to_flat_direct(files []ast.File) ast.FlatAst {
    timing := os.getenv('V2_TTIME') != ''
    mut sw := time.new_stopwatch()
    t_print_mem('enter')
    t.pre_pass(files)
    t_print_mem('after pre_pass')
    if timing {
        eprintln('  [ttime] flat direct pre_pass: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    files_to_transform := t.prepare_files_for_transform(files)
    t_print_mem('after prepare/monomorphize')
    if timing {
        eprintln('  [ttime] flat direct prepare: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    mut builder := new_transform_output_flat_builder(files_to_transform)
    for file in files_to_transform {
        t.transform_file_to_flat(t.file_without_open_generic_fn_decls(file), mut builder)
    }
    t_print_mem('after per-file flat loop')
    if timing {
        eprintln('  [ttime] flat direct per-file: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    generated_parts := t.generated_fns_parts_from_flat(&builder.flat)
    t.post_pass_to_flat(mut builder, generated_parts)
    t.apply_post_pass_tail_from_flat(&builder.flat)
    t_print_mem('after post_pass')
    if timing {
        eprintln('  [ttime] flat direct post_pass: ${sw.elapsed().milliseconds()}ms')
    }
    return builder.flat
}

// transform_flat_to_flat_direct transforms flat input into flat output without
// collecting a whole legacy []ast.File input or the transformed legacy output.
// Generic monomorphization is append-only, so flat preparation keeps cloned
// declarations in a per-file side table and the per-file loop reads top-level
// statements from cursors, decoding only each statement handed to legacy
// lowering helpers.
pub fn (mut t Transformer) transform_flat_to_flat_direct(flat &ast.FlatAst, files []ast.File) ast.FlatAst {
    if files.len > 0 {
        return t.transform_files_to_flat_direct(files)
    }
    timing := os.getenv('V2_TTIME') != ''
    mut sw := time.new_stopwatch()
    t_print_mem('enter')
    t.pre_pass_from_flat(flat)
    t_print_mem('after pre_pass')
    if timing {
        eprintln('  [ttime] flat input direct pre_pass: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    extra_stmts := t.prepare_flat_for_transform(flat)
    t_print_mem('after prepare/monomorphize')
    if timing {
        eprintln('  [ttime] flat input direct prepare: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    mut builder := new_transform_output_flat_builder_from_flat(flat)
    for i in 0 .. flat.files.len {
        extra := extra_stmts[i] or { []ast.Stmt{} }
        t.transform_flat_file_index_to_flat(flat, i, extra, mut builder)
    }
    t_print_mem('after per-file flat loop')
    if timing {
        eprintln('  [ttime] flat input direct per-file: ${sw.elapsed().milliseconds()}ms')
        sw = time.new_stopwatch()
    }
    generated_parts := t.generated_fns_parts_from_flat(&builder.flat)
    t.post_pass_to_flat(mut builder, generated_parts)
    t.apply_post_pass_tail_from_flat(&builder.flat)
    t_print_mem('after post_pass')
    if timing {
        eprintln('  [ttime] flat input direct post_pass: ${sw.elapsed().milliseconds()}ms')
    }
    t.dump_flat_fallback_stats()
    return builder.flat
}

fn (t &Transformer) file_without_open_generic_fn_decls(file ast.File) ast.File {
    mut has_open_generic_fn := false
    for stmt in file.stmts {
        if stmt is ast.FnDecl && t.omit_backend_generic_decl(stmt) {
            has_open_generic_fn = true
            break
        }
    }
    if !has_open_generic_fn {
        return file
    }
    mut stmts := []ast.Stmt{cap: file.stmts.len}
    for stmt in file.stmts {
        if stmt is ast.FnDecl && t.omit_backend_generic_decl(stmt) {
            continue
        }
        stmts << stmt
    }
    return ast.File{
        attributes:     file.attributes
        mod:            file.mod
        name:           file.name
        stmts:          stmts
        imports:        file.imports
        selector_names: file.selector_names
    }
}

// count_flat_fallback records one legacy-decode fallback hit for a cursor
// transform arm. Used to prioritize the remaining flat-native migration.
@[inline]
fn (mut t Transformer) count_flat_fallback(key string) {
    t.flat_fb_counts[key]++
}

// dump_flat_fallback_stats prints the per-arm legacy-decode fallback counts
// recorded during the transform, gated on V2_FLAT_FB_STATS.
fn (t &Transformer) dump_flat_fallback_stats() {
    if os.getenv('V2_FLAT_FB_STATS') == '' {
        return
    }
    mut keys := t.flat_fb_counts.keys()
    keys.sort_with_compare(fn [t] (a &string, b &string) int {
        return t.flat_fb_counts[*b] - t.flat_fb_counts[*a]
    })
    mut total := 0
    for k in keys {
        total += t.flat_fb_counts[k]
    }
    eprintln('[flat-fb] total legacy-decode fallbacks: ${total}')
    for k in keys {
        eprintln('[flat-fb]   ${t.flat_fb_counts[k]:8} ${k}')
    }
}

fn new_transform_output_flat_builder(files []ast.File) ast.FlatBuilder {
    mut total_bytes := i64(0)
    for file in files {
        if file.name == '' || !os.exists(file.name) {
            continue
        }
        total_bytes += os.file_size(file.name)
    }
    nodes_cap, edges_cap, strings_cap := ast.arena_caps_for_bytes(total_bytes * 2)
    return ast.new_flat_builder_with_capacity(nodes_cap, edges_cap, strings_cap)
}

fn new_transform_output_flat_builder_from_flat(flat &ast.FlatAst) ast.FlatBuilder {
    mut total_bytes := i64(0)
    for ff in flat.files {
        name := flat.file_name(ff)
        if name == '' || !os.exists(name) {
            continue
        }
        total_bytes += os.file_size(name)
    }
    nodes_cap, edges_cap, strings_cap := ast.arena_caps_for_bytes(total_bytes * 2)
    return ast.new_flat_builder_with_capacity(nodes_cap, edges_cap, strings_cap)
}

fn prepared_flat_file_for_transform(flat &ast.FlatAst, extra_stmts map[int][]ast.Stmt, fi int) ?ast.File {
    extra := extra_stmts[fi] or { []ast.Stmt{} }
    return flat_file_for_transform(flat, fi, extra)
}

fn flat_file_for_transform(flat &ast.FlatAst, fi int, extra_stmts []ast.Stmt) ?ast.File {
    if fi < 0 || fi >= flat.files.len {
        return none
    }
    fc := flat.file_cursor(fi)
    stmt_list := fc.stmts()
    mut stmts := []ast.Stmt{cap: stmt_list.len() + extra_stmts.len}
    for i in 0 .. stmt_list.len() {
        stmts << stmt_list.at(i).stmt()
    }
    if extra_stmts.len > 0 {
        stmts << extra_stmts
    }
    return ast.File{
        name:           fc.name()
        mod:            fc.mod()
        selector_names: fc.selector_names()
        attributes:     fc.attrs().attributes()
        imports:        fc.imports().import_stmts()
        stmts:          stmts
    }
}

fn runtime_const_init_base_name(mod string) string {
    mut suffix := if mod == '' { 'main' } else { mod }
    suffix = suffix.replace('.', '_').replace('-', '_')
    return '__v_init_consts_${suffix}'
}

fn runtime_const_init_call_name(mod string, fn_name string) string {
    if mod != '' && mod != 'main' && mod != 'builtin' {
        return '${mod}__${fn_name}'
    }
    return fn_name
}

fn module_init_call_name(mod string) string {
    if mod != '' && mod != 'main' && mod != 'builtin' {
        return '${mod}__init'
    }
    return 'init'
}

fn (t &Transformer) uses_minimal_windows_x64_runtime() bool {
    return t.pref != unsafe { nil } && t.pref.backend == .x64 && t.pref.get_effective_arch() == .x64
        && t.pref.target_os_or_host().to_lower() == 'windows'
}

fn (t &Transformer) uses_minimal_linux_x64_runtime() bool {
    return t.pref != unsafe { nil } && t.pref.backend == .x64 && t.pref.get_effective_arch() == .x64
        && t.pref.target_os_or_host().to_lower() == 'linux'
}

fn (t &Transformer) uses_minimal_x64_runtime() bool {
    return t.uses_minimal_windows_x64_runtime() || t.uses_minimal_linux_x64_runtime()
        || t.macos_tiny_candidate_graph
}

fn (t &Transformer) collect_runtime_init_imports_from_if_expr(node ast.IfExpr, mut imports []ast.ImportStmt) {
    if t.eval_comptime_cond(node.cond) {
        t.collect_runtime_init_imports_from_stmts(node.stmts, mut imports)
        return
    }
    match node.else_expr {
        ast.IfExpr {
            if node.else_expr.cond is ast.EmptyExpr {
                t.collect_runtime_init_imports_from_stmts(node.else_expr.stmts, mut imports)
            } else {
                t.collect_runtime_init_imports_from_if_expr(node.else_expr, mut imports)
            }
        }
        else {}
    }
}

fn (t &Transformer) collect_runtime_init_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 {
                    t.collect_runtime_init_imports_from_if_expr(stmt.expr.expr, mut imports)
                }
            }
            else {}
        }
    }
}

fn (t &Transformer) active_runtime_init_imports(file ast.File) []ast.ImportStmt {
    mut imports := file.imports.clone()
    t.collect_runtime_init_imports_from_stmts(file.stmts, mut imports)
    return imports
}

fn runtime_init_available_modules(files []ast.File) map[string]bool {
    mut available := map[string]bool{}
    available[''] = true
    available['main'] = true
    for file in files {
        if file.mod != '' {
            available[file.mod] = true
        }
    }
    return available
}

fn add_runtime_init_module_key(mut modules map[string]bool, name string, available map[string]bool) bool {
    if name == '' {
        return false
    }
    mut changed := false
    mut matched_available := false
    mut candidates := [name]
    if name.contains('.') {
        short_name := name.all_after_last('.')
        if short_name != '' {
            candidates << short_name
        }
    }
    for candidate in candidates {
        if candidate !in available {
            continue
        }
        matched_available = true
        if candidate !in modules {
            modules[candidate] = true
            changed = true
        }
    }
    if !matched_available && name !in modules {
        modules[name] = true
        changed = true
    }
    return changed
}

fn (t &Transformer) imported_runtime_init_modules(files []ast.File) map[string]bool {
    mut modules := map[string]bool{}
    modules[''] = true
    available_modules := runtime_init_available_modules(files)
    add_runtime_init_module_key(mut modules, 'main', available_modules)
    mut changed := true
    for changed {
        changed = false
        for file in files {
            if file.mod !in modules {
                continue
            }
            for imp in t.active_runtime_init_imports(file) {
                changed = add_runtime_init_module_key(mut modules, imp.name, available_modules)
                    || changed
            }
        }
    }
    return modules
}

fn runtime_init_available_modules_from_flat(flat &ast.FlatAst) map[string]bool {
    mut available := map[string]bool{}
    available[''] = true
    available['main'] = true
    for ff in flat.files {
        mod_name := flat.file_mod(ff)
        if mod_name != '' {
            available[mod_name] = true
        }
    }
    return available
}

fn (t &Transformer) collect_runtime_init_imports_from_if_expr_cursor(node ast.Cursor, mut imports []ast.ImportStmt) {
    if !node.is_valid() || node.kind() != .expr_if {
        return
    }
    cond := node.edge(0)
    if t.eval_comptime_cond_cursor(cond) {
        t.collect_runtime_init_imports_from_if_cursor_stmts(node, mut imports)
        return
    }
    else_expr := node.edge(1)
    if !else_expr.is_valid() || else_expr.kind() != .expr_if {
        return
    }
    else_cond := else_expr.edge(0)
    if !else_cond.is_valid() || else_cond.kind() == .expr_empty {
        t.collect_runtime_init_imports_from_if_cursor_stmts(else_expr, mut imports)
        return
    }
    t.collect_runtime_init_imports_from_if_expr_cursor(else_expr, mut imports)
}

fn (t &Transformer) collect_runtime_init_imports_from_if_cursor_stmts(node ast.Cursor, mut imports []ast.ImportStmt) {
    for i in 2 .. node.edge_count() {
        t.collect_runtime_init_imports_from_stmt_cursor(node.edge(i), mut imports)
    }
}

fn (t &Transformer) collect_runtime_init_imports_from_stmt_cursor(stmt ast.Cursor, mut imports []ast.ImportStmt) {
    if !stmt.is_valid() {
        return
    }
    match stmt.kind() {
        .stmt_import {
            imports << stmt.import_stmt()
        }
        .stmt_expr {
            expr := stmt.edge(0)
            if !expr.is_valid() || expr.kind() != .expr_comptime {
                return
            }
            inner := expr.edge(0)
            if inner.is_valid() && inner.kind() == .expr_if {
                t.collect_runtime_init_imports_from_if_expr_cursor(inner, mut imports)
            }
        }
        else {}
    }
}

fn (t &Transformer) collect_runtime_init_imports_from_stmt_cursors(stmts ast.CursorList, mut imports []ast.ImportStmt) {
    for i in 0 .. stmts.len() {
        t.collect_runtime_init_imports_from_stmt_cursor(stmts.at(i), mut imports)
    }
}

fn (t &Transformer) active_runtime_init_imports_from_flat_file(fc ast.FileCursor) []ast.ImportStmt {
    file_imports := fc.imports()
    mut imports := []ast.ImportStmt{cap: file_imports.len()}