module builder

import os
import v2.ast
import v2.gen.v
import v2.parser
import v2.types

const core_cached_module_paths = [
    'builtin',
    'strconv',
    'strings',
    'hash',
    'math.bits',
    'os',
    'time',
    'term',
    'term.termios',
    'os.cmdline',
    'encoding.binary',
    'crypto.sha256',
    'strings.textscanner',
]

const core_cached_module_names = [
    'builtin',
    'strconv',
    'strings',
    'hash',
    'bits',
    'os',
    'time',
    'term',
    'termios',
    'cmdline',
    'binary',
    'sha256',
    'textscanner',
]

const builtin_cache_name = 'builtin'

const builtin_cached_module_paths = ['builtin', 'strconv', 'strings', 'hash', 'math.bits']

const builtin_cached_module_names = ['builtin', 'strconv', 'strings', 'hash', 'bits']

const vlib_cache_name = 'vlib'

const vlib_cached_module_paths = [
    'os',
    'time',
    'term',
    'term.termios',
    'os.cmdline',
    'encoding.binary',
    'crypto.sha256',
    'strings.textscanner',
]

const vlib_cached_module_names = [
    'os',
    'time',
    'term',
    'termios',
    'cmdline',
    'binary',
    'sha256',
    'textscanner',
]

const veb_cache_name = 'veb'

const veb_cached_module_paths = [
    'veb',
    'fasthttp',
    'io',
    'net',
    'net.http',
    'net.http.chunked',
    'net.conv',
    'net.openssl',
    'net.socks',
    'net.ssl',
    'net.urllib',
    'compress',
    'compress.gzip',
    'compress.zlib',
    'compress.zstd',
    'hash.crc32',
    'math.big',
    'sync',
    'sync.stdatomic',
    'x.json2',
    'runtime',
    'arrays',
    'encoding.html',
]

const veb_cached_module_names = [
    'veb',
    'fasthttp',
    'io',
    'net',
    'http',
    'chunked',
    'conv',
    'openssl',
    'socks',
    'ssl',
    'urllib',
    'compress',
    'gzip',
    'zlib',
    'zstd',
    'crc32',
    'big',
    'sync',
    'stdatomic',
    'json2',
    'runtime',
    'arrays',
    'html',
]

const v2compiler_cache_name = 'v2compiler'

const imports_cache_name = 'imports'

const virtuals_cache_name = 'virtuals'

struct CachedImportModule {
    import_path string
    module_name string
}

struct CachedVirtualModule {
    name         string
    header_name  string
    source_files []string
}

const v2compiler_cached_module_paths = [
    'v2.ast',
    'v2.abi',
    'v2.builder',
    'v2.errors',
    'v2.eval',
    'v2.gen.arm64',
    'v2.gen.c',
    'v2.gen.cleanc',
    'v2.gen.v',
    'v2.gen.x64',
    'v2.insel',
    'v2.markused',
    'v2.mir',
    'v2.parser',
    'v2.pref',
    'v2.scanner',
    'v2.ssa',
    'v2.ssa.optimize',
    'v2.token',
    'v2.transformer',
    'v2.types',
]

const v2compiler_cached_module_names = [
    'ast',
    'abi',
    'builder',
    'errors',
    'eval',
    'arm64',
    'c',
    'cleanc',
    'v',
    'x64',
    'insel',
    'markused',
    'mir',
    'parser',
    'pref',
    'scanner',
    'ssa',
    'optimize',
    'token',
    'transformer',
    'types',
]

const core_cache_format = 'cc15'

const core_headers_format = 'vh49'

const core_cache_compiler_dependency_dirs = [
    'vlib/v2/abi',
    'vlib/v2/ast',
    'vlib/v2/builder',
    'vlib/v2/errors',
    'vlib/v2/eval',
    'vlib/v2/gen/arm64',
    'vlib/v2/gen/c',
    'vlib/v2/gen/cleanc',
    'vlib/v2/gen/v',
    'vlib/v2/gen/x64',
    'vlib/v2/insel',
    'vlib/v2/markused',
    'vlib/v2/mir',
    'vlib/v2/parser',
    'vlib/v2/pref',
    'vlib/v2/scanner',
    'vlib/v2/ssa',
    'vlib/v2/ssa/optimize',
    'vlib/v2/token',
    'vlib/v2/transformer',
    'vlib/v2/types',
    'vlib/v2/util',
]

const core_cache_compiler_dependency_file_paths = ['cmd/v2/v2.v', 'vlib/net/openssl/openssl_compat.h']

fn (b &Builder) core_cache_dir() string {
    base := if b.pref.is_prod { 'v2_cleanc_obj_cache_prod' } else { 'v2_cleanc_obj_cache' }
    root := if b.pref.vroot.len > 0 { b.pref.vroot } else { os.getwd() }
    root_key := sanitize_cache_part(os.norm_path(os.abs_path(root)))
    if root_key.len == 0 {
        return cache_path_join(os.temp_dir(), base)
    }
    return cache_path_join(os.temp_dir(), '${base}_${root_key}')
}

fn (b &Builder) ensure_core_cache_dir() bool {
    cache_dir := b.core_cache_dir()
    if !os.exists(cache_dir) {
        os.mkdir_all(cache_dir, mode: 0o700) or { return false }
    }
    if !os.is_dir(cache_dir) {
        return false
    }
    if !os.is_readable(cache_dir) || !os.is_writable(cache_dir) {
        os.chmod(cache_dir, 0o700) or {}
    }
    return os.is_readable(cache_dir) && os.is_writable(cache_dir)
}

fn (b &Builder) core_cache_obj_path() string {
    return cache_path_join(b.core_cache_dir(), '${builtin_cache_name}.o')
}

fn (b &Builder) core_cache_stamp_path() string {
    return cache_path_join(b.core_cache_dir(), '${builtin_cache_name}.stamp')
}

fn (b &Builder) core_headers_stamp_path() string {
    return cache_path_join(b.core_cache_dir(), 'cached_modules.vh.stamp')
}

fn (b &Builder) imports_headers_stamp_path() string {
    return cache_path_join(b.core_cache_dir(), '${imports_cache_name}.vh.stamp')
}

fn (b &Builder) v2compiler_headers_stamp_path() string {
    return cache_path_join(b.core_cache_dir(), '${v2compiler_cache_name}.vh.stamp')
}

fn (b &Builder) imports_manifest_path() string {
    return cache_path_join(b.core_cache_dir(), '${imports_cache_name}.manifest')
}

fn (b &Builder) virtuals_headers_stamp_path() string {
    return cache_path_join(b.core_cache_dir(), '${virtuals_cache_name}.vh.stamp')
}

fn (b &Builder) virtuals_manifest_path() string {
    return cache_path_join(b.core_cache_dir(), '${virtuals_cache_name}.manifest')
}

fn (b &Builder) core_header_path(module_name string) string {
    return cache_path_join(b.core_cache_dir(), '${module_name}.vh')
}

fn cache_path_join(dir string, file string) string {
    base := dir.trim_right('/\\')
    if base == '' {
        return file
    }
    return '${base}/${file}'
}

fn (b &Builder) core_header_paths() []string {
    mut paths := []string{cap: core_cached_module_names.len}
    for module_name in core_cached_module_names {
        paths << b.core_header_path(module_name)
    }
    return paths
}

fn (b &Builder) cached_header_paths() []string {
    mut paths := b.core_header_paths()
    for module_name in veb_cached_module_names {
        paths << b.core_header_path(module_name)
    }
    return paths
}

fn (b &Builder) v2compiler_header_paths() []string {
    mut paths := []string{cap: v2compiler_cached_module_names.len}
    for module_name in v2compiler_cached_module_names {
        paths << b.core_header_path(module_name)
    }
    return paths
}

fn cached_header_module_paths() []string {
    mut paths := core_cached_module_paths.clone()
    for module_path in veb_cached_module_paths {
        paths << module_path
    }
    return paths
}

fn cached_header_module_names() []string {
    mut names := core_cached_module_names.clone()
    for module_name in veb_cached_module_names {
        names << module_name
    }
    return names
}

fn (b &Builder) core_cached_parse_paths() []string {
    return b.core_header_paths()
}

// vlib_only_header_paths returns .vh paths for only the builtin+vlib modules
// (not v2compiler modules). Used when generating the main .c file to avoid
// type/function conflicts with the v2compiler.o cached object.
fn (b &Builder) vlib_only_header_paths() []string {
    mut paths := []string{cap: builtin_cached_module_names.len + vlib_cached_module_names.len}
    for module_name in builtin_cached_module_names {
        paths << b.core_header_path(module_name)
    }
    for module_name in vlib_cached_module_names {
        paths << b.core_header_path(module_name)
    }
    return paths
}

fn (b &Builder) use_builtin_header_for_parse() bool {
    for file in b.user_files {
        if os.file_name(file) == 'v2.v' {
            return false
        }
    }
    return true
}

fn (b &Builder) module_source_files(modules []string) []string {
    mut files_set := map[string]bool{}
    for module_name in modules {
        module_files := b.source_files_for_module_name(module_name)
        for file in module_files {
            files_set[file] = true
        }
    }
    mut files := files_set.keys()
    files.sort()
    return files
}

fn (b &Builder) source_files_for_module_name(module_name string) []string {
    mut files_set := map[string]bool{}
    if b.uses_flat_module_enumeration() {
        // In flat mode b.files is dropped; source the actual parsed file
        // paths from the flat cursors. This is required for external (non-vlib)
        // modules whose location the disk-scan fallback below cannot resolve.
        for i in 0 .. b.flat.files.len {
            if b.flat_file_module_name(i) != module_name {
                continue
            }
            name := b.flat.file_name(b.flat.files[i])
            if name == '' || name.ends_with('.vh') {
                continue
            }
            files_set[name] = true
        }
    } else {
        for file in b.files {
            if ast_file_module_name(file) != module_name {
                continue
            }
            if file.name == '' || file.name.ends_with('.vh') {
                continue
            }
            files_set[file.name] = true
        }
    }
    if files_set.len == 0 {
        module_path := b.module_name_to_path(module_name)
        module_dir := b.pref.get_vlib_module_path(module_path)
        for file in get_v_files_from_dir(module_dir, b.pref.user_defines,
            b.pref.source_filter_target_os()) {
            files_set[file] = true
        }
    }
    mut files := files_set.keys()
    files.sort()
    return files
}

fn (b &Builder) core_cache_compiler_dependency_files() []string {
    root := if b.pref.vroot.len > 0 { b.pref.vroot } else { os.getwd() }
    mut files_set := map[string]bool{}
    for rel_dir in core_cache_compiler_dependency_dirs {
        dir := os.join_path(root, rel_dir)
        if !os.is_dir(dir) {
            continue
        }
        for file in get_v_files_from_dir(dir, b.pref.user_defines, b.pref.source_filter_target_os()) {
            files_set[os.norm_path(file)] = true
        }
    }
    for rel_file in core_cache_compiler_dependency_file_paths {
        file := os.join_path(root, rel_file)
        if os.exists(file) {
            files_set[os.norm_path(file)] = true
        }
    }
    mut files := files_set.keys()
    files.sort()
    return files
}

fn (b &Builder) user_entry_stamp_files() []string {
    mut files_set := map[string]bool{}
    user_defines := if b.pref != unsafe { nil } { b.pref.user_defines } else { []string{} }
    for file in b.user_files {
        if os.is_dir(file) {
            mut found_parsed_files := false
            for parsed_file in b.files {
                if parsed_file.name == '' || parsed_file.name.ends_with('.vh') {
                    continue
                }
                relative_path_under_root(file, parsed_file.name) or { continue }
                files_set[os.norm_path(parsed_file.name)] = true
                found_parsed_files = true
            }
            if found_parsed_files {
                continue
            }
            for source_file in get_user_v_files_from_dir(file, user_defines,
                b.pref.source_filter_target_os()) {
                if source_file == '' || source_file.ends_with('.vh') {
                    continue
                }
                files_set[os.norm_path(source_file)] = true
            }
            continue
        }
        files_set[os.norm_path(file)] = true
    }
    mut files := files_set.keys()
    files.sort()
    return files
}

fn sanitize_cache_part(name string) string {
    mut out := []u8{cap: name.len}
    for ch in name {
        if (ch >= `a` && ch <= `z`) || (ch >= `A` && ch <= `Z`)
            || (ch >= `0` && ch <= `9`) || ch == `_` {
            out << u8(ch)
        } else {
            out << `_`
        }
    }
    res := out.bytestr().trim('_')
    if res == '' {
        return 'unnamed'
    }
    return res
}

fn sanitize_staged_c_source(source string) string {
    return sanitize_channel_semaphore_waits(source)
}

fn sanitize_cached_main_c_source(source string) string {
    return sanitize_c_typedef_names(sanitize_channel_semaphore_waits(source))
}

fn sanitize_cached_object_c_source(source string) string {
    mut sanitized := sanitize_c_typedef_names(source)
    sanitized = guard_cached_stdatomic_compat_includes(sanitized)
    return sanitized
}

fn sanitize_channel_semaphore_waits(source string) string {
    lines := source.split_into_lines()
    mut out := []string{cap: lines.len}
    prefix := 'sync__Semaphore__wait('
    for line in lines {
        mut fixed := line
        if idx := fixed.index(prefix) {
            arg_start := idx + prefix.len
            if arg_start < fixed.len && fixed[arg_start] != `&` {
                arg_end := fixed.index_after(')', arg_start) or { -1 }
                if arg_end > arg_start {
                    arg := fixed[arg_start..arg_end]
                    if arg.contains('->writesem') || arg.contains('->readsem') {
                        fixed = fixed[..arg_start] + '&' + fixed[arg_start..]
                    }
                }
            }
        }
        out << fixed
    }
    return out.join('\n')
}

fn sanitize_c_typedef_names(source string) string {
    mut out := source
    for name in ['atomic_uintptr_t', 'pthread_rwlockattr_t', 'pthread_condattr_t'] {
        out = out.replace('struct ${name}', name)
    }
    return out
}

fn guard_cached_stdatomic_compat_includes(source string) string {
    if !source.contains('/thirdparty/stdatomic/nix/atomic.h') {
        return source
    }
    lines := source.split_into_lines()
    mut out := []string{cap: lines.len + 8}
    for line in lines {
        trimmed := line.trim_space()
        if trimmed == '#include <stdatomic.h>' {
            out << '#ifndef __TINYC__'
            out << line
            out << '#endif'
            continue
        }
        if trimmed.starts_with('#include ')
            && trimmed.contains('/thirdparty/stdatomic/nix/atomic.h') {
            out << '#if defined(__TINYC__) && defined(__APPLE__) && defined(__aarch64__)'
            out << '#define extern static'
            out << '#endif'
            out << line
            out << '#if defined(__TINYC__) && defined(__APPLE__) && defined(__aarch64__)'
            out << '#undef extern'
            out << '#endif'
            continue
        }
        out << line
    }
    return out.join('\n')
}

fn virtual_header_name(name string) string {
    return 'main_${sanitize_cache_part(name)}'
}

fn (b &Builder) virtual_module_root() string {
    for file in b.user_files {
        if file != '' && os.is_dir(file) {
            return os.norm_path(os.abs_path(file))
        }
    }
    if b.user_files.len > 0 && b.user_files[0] != '' {
        return os.norm_path(os.abs_path(os.dir(b.user_files[0])))
    }
    return os.norm_path(os.getwd())
}

fn relative_path_under_root(root string, file string) ?string {
    if root == '' || file == '' {
        return none
    }
    root_norm := os.norm_path(os.abs_path(root)).replace('\\', '/').trim_right('/')
    file_norm := os.norm_path(os.abs_path(file)).replace('\\', '/')
    if file_norm == root_norm {
        return ''
    }
    prefix := root_norm + '/'
    if !file_norm.starts_with(prefix) {
        return none
    }
    return file_norm[prefix.len..]
}

fn (b &Builder) virtual_main_group_for_path(file string) ?string {
    rel := relative_path_under_root(b.virtual_module_root(), file) or { return none }
    if rel == '' || !rel.contains('/') {
        return none
    }
    group := rel.all_before('/')
    if group == '' || group.starts_with('.') {
        return none
    }
    return group
}

fn strip_leading_source_attributes(line string) string {
    mut rest := line.trim_space()
    for {
        if rest.starts_with('@[') {
            end := rest.index(']') or { return rest }
            rest = rest[end + 1..].trim_space()
            continue
        }
        if rest.starts_with('[') {
            end := rest.index(']') or { return rest }
            rest = rest[end + 1..].trim_space()
            continue
        }
        break
    }
    return rest
}

fn source_line_declares_executable_main(line string) bool {
    mut rest := strip_leading_source_attributes(line)
    if rest.len == 0 || rest.starts_with('//') {
        return false
    }
    if rest.starts_with('pub ') {
        rest = rest[4..].trim_space()
    }
    if !rest.starts_with('fn') {
        return false
    }
    rest = rest[2..].trim_space()
    return rest.starts_with('main(') || rest.starts_with('main (')
}

fn source_file_declares_executable_main(path string) bool {
    lines := os.read_lines(path) or { return false }
    for line in lines {
        if source_line_declares_executable_main(line) {
            return true
        }
    }
    return false
}

fn ast_file_declares_executable_main(file ast.File) bool {
    for stmt in file.stmts {
        if stmt is ast.FnDecl && !stmt.is_method && !stmt.is_static && stmt.language == .v
            && stmt.name == 'main' {
            return true
        }
    }
    return false
}

// flat_file_declares_executable_main is the flat-cursor analogue of
// `ast_file_declares_executable_main`: it scans a file's top-level statement
// cursors for a non-method, non-static, `.v`-language `fn main`. All four
// conditions must match the legacy predicate so virtual main-module grouping
// stays bit-identical to the `b.files` path.
fn flat_file_declares_executable_main(fc ast.FileCursor) bool {
    stmts := fc.stmts()
    for j in 0 .. stmts.len() {
        c := stmts.at(j)
        if c.kind() != .stmt_fn_decl {
            continue
        }
        if c.flag(ast.flag_is_method) || c.flag(ast.flag_is_static) {
            continue
        }
        if unsafe { ast.Language(int(c.aux())) } != .v {
            continue
        }
        if c.name() == 'main' {
            return true
        }
    }
    return false
}

fn (b &Builder) collect_virtual_main_modules() []CachedVirtualModule {
    mut grouped := map[string][]string{}
    mut groups_with_main := map[string]bool{}
    if b.uses_flat_module_enumeration() {
        for i in 0 .. b.flat.files.len {
            fc := b.flat.file_cursor(i)
            name := fc.name()
            if name == '' || name.ends_with('.vh') || b.flat_file_module_name(i) != 'main' {
                continue
            }
            group := b.virtual_main_group_for_path(name) or { continue }
            if flat_file_declares_executable_main(fc) {
                groups_with_main[group] = true
                continue
            }
            mut files := grouped[group] or { []string{} }
            files << name
            grouped[group] = files
        }
    } else {
        for file in b.files {
            if file.name == '' || file.name.ends_with('.vh') || ast_file_module_name(file) != 'main' {
                continue
            }
            group := b.virtual_main_group_for_path(file.name) or { continue }
            if ast_file_declares_executable_main(file) {
                groups_with_main[group] = true
                continue
            }
            mut files := grouped[group] or { []string{} }
            files << file.name
            grouped[group] = files
        }
    }
    for group, _ in groups_with_main {
        grouped.delete(group)
    }
    return cached_virtual_modules_from_grouped_files(grouped)
}

fn (b &Builder) collect_virtual_main_modules_from_paths(paths []string) []CachedVirtualModule {
    mut grouped := map[string][]string{}
    mut groups_with_main := map[string]bool{}
    for path in paths {
        if path == '' || path.ends_with('.vh') || !os.exists(path) {
            continue
        }
        if file_module_name(path) or { '' } != 'main' {
            continue
        }
        group := b.virtual_main_group_for_path(path) or { continue }
        if source_file_declares_executable_main(path) {
            groups_with_main[group] = true
            continue
        }
        mut files := grouped[group] or { []string{} }
        files << path
        grouped[group] = files
    }
    for group, _ in groups_with_main {
        grouped.delete(group)
    }
    return cached_virtual_modules_from_grouped_files(grouped)
}

fn cached_virtual_modules_from_grouped_files(grouped map[string][]string) []CachedVirtualModule {
    mut groups := []CachedVirtualModule{cap: grouped.len}
    mut names := grouped.keys()
    names.sort()
    for name in names {
        mut files := grouped[name].clone()
        files.sort()
        groups << CachedVirtualModule{
            name:         name
            header_name:  virtual_header_name(name)
            source_files: files
        }
    }
    return groups
}

fn virtual_module_source_files(groups []CachedVirtualModule) []string {
    mut files := []string{}
    mut seen := map[string]bool{}
    for group in groups {
        for file in group.source_files {
            norm_file := os.norm_path(file)
            if norm_file in seen {
                continue
            }
            seen[norm_file] = true
            files << file
        }
    }
    files.sort()
    return files
}

fn virtual_module_names(groups []CachedVirtualModule) []string {
    mut names := []string{cap: groups.len}
    for group in groups {
        names << group.name
    }
    return names
}

fn filter_out_source_files(files []string, excluded []string) []string {
    mut excluded_set := map[string]bool{}
    for file in excluded {
        excluded_set[os.norm_path(file)] = true
        excluded_set[os.norm_path(os.abs_path(file))] = true
    }
    mut out := []string{cap: files.len}
    for file in files {
        if source_file_in_set(file, excluded_set) {
            continue
        }
        out << file
    }
    return out
}

fn source_file_in_set(file string, file_set map[string]bool) bool {
    norm_file := os.norm_path(file)
    abs_file := os.norm_path(os.abs_path(file))
    if norm_file in file_set || abs_file in file_set {
        return true
    }
    for excluded, _ in file_set {
        trimmed := excluded.trim_left('./')
        if trimmed == '' {
            continue
        }
        if norm_file == trimmed || abs_file == trimmed {
            return true
        }
        if norm_file.ends_with('/${trimmed}') || abs_file.ends_with('/${trimmed}') {
            return true
        }
    }
    return false
}

fn (b &Builder) cache_stamp_for_modules(cache_name string, modules []string, cc string, cc_flags string, cc_link_flags string, use_markused bool) string {
    source_files := b.module_source_files(modules)
    compiler_files := b.core_cache_compiler_dependency_files()
    mut lines := []string{cap: source_files.len + compiler_files.len + 10}
    lines << 'cache=${cache_name}'
    lines << 'format=${core_cache_format}'
    lines << 'cc=${cc}'
    lines << 'cc_flags=${cc_flags}'
    lines << 'cc_link_flags=${cc_link_flags}'
    lines << 'use_markused=${use_markused}'
    lines << 'context_alloc=${b.pref.use_context_allocator}'
    lines << 'target_os=${b.pref.target_os_or_host()}'
    // Include user entry files in cache stamp: the transformer injects
    // helper functions (str, eq, sort comparators) into builtin module AST
    // based on types from the user's source file. Different source files
    // produce different generated functions, so the cache must invalidate.
    for file in b.user_entry_stamp_files() {
        lines << 'entry:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in source_files {
        lines << '${file}:${os.file_last_mod_unix(file)}'
    }
    for file in compiler_files {
        lines << '${file}:${os.file_last_mod_unix(file)}'
    }
    return lines.join('\n')
}

fn (b &Builder) core_cache_context_stamp() string {
    mut files := b.user_files.clone()
    files.sort()
    mut lines := []string{cap: files.len + 1}
    for file in files {
        norm_file := os.norm_path(file)
        lines << '${norm_file}:${os.file_last_mod_unix(norm_file)}'
    }
    lines << 'entry_count=${files.len}'
    return lines.join('|')
}

fn (b &Builder) header_stamp_for_modules(modules []string) string {
    source_files := b.module_source_files(modules)
    compiler_files := b.core_cache_compiler_dependency_files()
    entry_files := b.user_entry_stamp_files()
    mut lines := []string{cap: source_files.len + compiler_files.len + entry_files.len + 4}
    lines << 'format=${core_headers_format}'
    lines << 'target_os=${b.pref.target_os_or_host()}'
    for file in entry_files {
        lines << 'entry:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in source_files {
        lines << '${file}:${os.file_last_mod_unix(file)}'
    }
    for file in compiler_files {
        lines << '${file}:${os.file_last_mod_unix(file)}'
    }
    return lines.join('\n')
}

fn (b &Builder) cache_dependency_stamp_lines(cache_names []string) []string {
    mut lines := []string{cap: cache_names.len}
    for cache_name in cache_names {
        stamp_path := cache_path_join(b.core_cache_dir(), '${cache_name}.stamp')
        if !os.exists(stamp_path) {
            continue
        }
        lines << 'dependency:${cache_name}:${os.file_last_mod_unix(stamp_path)}'
    }
    return lines
}

fn (b &Builder) cache_stamp_for_parsed_modules(cache_name string, module_names []string, dependency_cache_names []string, cc string, cc_flags string, cc_link_flags string, use_markused bool) string {
    source_files := b.module_source_files(module_names)
    compiler_files := b.core_cache_compiler_dependency_files()
    dependency_lines := b.cache_dependency_stamp_lines(dependency_cache_names)
    mut lines := []string{cap: source_files.len + compiler_files.len + module_names.len +
        dependency_lines.len + 10}
    lines << 'cache=${cache_name}'
    lines << 'format=${core_cache_format}'
    lines << 'cc=${cc}'
    lines << 'cc_flags=${cc_flags}'
    lines << 'cc_link_flags=${cc_link_flags}'
    lines << 'use_markused=${use_markused}'
    lines << 'context_alloc=${b.pref.use_context_allocator}'
    lines << 'target_os=${b.pref.target_os_or_host()}'
    for module_name in module_names {
        lines << 'module:${module_name}'
    }
    lines << dependency_lines
    for file in b.user_entry_stamp_files() {
        lines << 'entry:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in source_files {
        lines << 'source:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in compiler_files {
        lines << 'compiler:${file}:${os.file_last_mod_unix(file)}'
    }
    return lines.join('\n')
}

fn (b &Builder) cache_stamp_for_virtual_modules(groups []CachedVirtualModule, dependency_cache_names []string, cc string, cc_flags string, cc_link_flags string, use_markused bool) string {
    source_files := virtual_module_source_files(groups)
    compiler_files := b.core_cache_compiler_dependency_files()
    dependency_lines := b.cache_dependency_stamp_lines(dependency_cache_names)
    mut lines := []string{cap: source_files.len + compiler_files.len + groups.len +
        dependency_lines.len + 10}
    lines << 'cache=${virtuals_cache_name}'
    lines << 'format=${core_cache_format}'
    lines << 'cc=${cc}'
    lines << 'cc_flags=${cc_flags}'
    lines << 'cc_link_flags=${cc_link_flags}'
    lines << 'use_markused=${use_markused}'
    lines << 'context_alloc=${b.pref.use_context_allocator}'
    lines << 'target_os=${b.pref.target_os_or_host()}'
    for group in groups {
        lines << 'virtual:${group.name}:${group.header_name}'
    }
    lines << dependency_lines
    for file in b.user_entry_stamp_files() {
        lines << 'entry:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in source_files {
        lines << 'source:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in compiler_files {
        lines << 'compiler:${file}:${os.file_last_mod_unix(file)}'
    }
    return lines.join('\n')
}

fn (b &Builder) imports_header_stamp_for_modules(imports []CachedImportModule, module_names []string) string {
    source_files := b.module_source_files(module_names)
    compiler_files := b.core_cache_compiler_dependency_files()
    mut lines := []string{cap: source_files.len + compiler_files.len + imports.len + 6}
    lines << 'cache=${imports_cache_name}'
    lines << 'format=${core_headers_format}'
    lines << 'target_os=${b.pref.target_os_or_host()}'
    for import_mod in imports {
        lines << 'import:${import_mod.import_path}:${import_mod.module_name}'
    }
    for file in b.user_entry_stamp_files() {
        lines << 'entry:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in source_files {
        lines << 'source:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in compiler_files {
        lines << 'compiler:${file}:${os.file_last_mod_unix(file)}'
    }
    return lines.join('\n')
}

fn (b &Builder) virtuals_header_stamp_for_modules(groups []CachedVirtualModule) string {
    source_files := virtual_module_source_files(groups)
    compiler_files := b.core_cache_compiler_dependency_files()
    mut lines := []string{cap: source_files.len + compiler_files.len + groups.len + 6}
    lines << 'cache=${virtuals_cache_name}'
    lines << 'format=${core_headers_format}'
    lines << 'target_os=${b.pref.target_os_or_host()}'
    for group in groups {
        lines << 'virtual:${group.name}:${group.header_name}'
    }
    for file in b.user_entry_stamp_files() {
        lines << 'entry:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in source_files {
        lines << 'source:${file}:${os.file_last_mod_unix(file)}'
    }
    for file in compiler_files {
        lines << 'compiler:${file}:${os.file_last_mod_unix(file)}'
    }
    return lines.join('\n')
}

fn stamp_tracked_file_line(line string) (string, string, bool) {
    mut path_start := -1
    for prefix in ['entry:', 'source:', 'compiler:', 'emit:', 'compiler_exe:'] {
        if line.starts_with(prefix) {
            path_start = prefix.len
            break
        }
    }
    if path_start < 0 {
        if line.starts_with('/') || line.starts_with('./') || line.starts_with('../') {
            path_start = 0
        } else {
            return '', '', false
        }
    }
    colon_idx := line.last_index(':') or { return '', '', false }
    if colon_idx <= path_start {
        return '', '', false
    }
    return line[path_start..colon_idx], line[colon_idx + 1..], true
}

fn stamp_file_lines_are_fresh(stamp string) bool {
    for line in stamp.split_into_lines() {
        file, expected_mtime, tracked := stamp_tracked_file_line(line)
        if !tracked {
            continue
        }
        if !os.exists(file) {
            return false
        }
        if '${os.file_last_mod_unix(file)}' != expected_mtime {
            return false
        }
    }
    return true
}

// can_use_cached_core_headers_for_parse checks whether .vh header files
// exist, are non-empty, and their stamp matches the current source/compiler
// file timestamps.  The .o stamp validation is skipped (the gen phase
// rebuilds stale .o files via ensure_cached_module_object), but the .vh
// stamp IS validated so that stale headers trigger a full parse — otherwise
// the gen phase would regenerate .o from incomplete .vh ASTs.
fn (b &Builder) can_use_cached_core_headers_for_parse() bool {
    if b.pref.no_cache || b.pref.skip_builtin {
        return false
    }
    if b.pref.backend != .cleanc {
        return false
    }
    if !b.ensure_core_cache_dir() {
        return false
    }
    // Validate .vh header stamp (no cc/cc_flags — only source + compiler timestamps).
    expected_header_stamp := b.header_stamp_for_modules(cached_header_module_paths())
    current_header_stamp := os.read_file(b.core_headers_stamp_path()) or { return false }
    if current_header_stamp != expected_header_stamp {
        return false
    }
    for header_path in b.cached_header_paths() {
        if !os.exists(header_path) {
            return false
        }
        if os.file_size(header_path) == 0 {
            return false
        }
    }
    for cache_name in [builtin_cache_name, vlib_cache_name] {
        if !os.exists(cache_path_join(b.core_cache_dir(), '${cache_name}.o'))
            || !os.exists(cache_path_join(b.core_cache_dir(), '${cache_name}.stamp')) {
            return false
        }
    }
    return true
}

fn (b &Builder) cached_import_manifest() []CachedImportModule {
    manifest := os.read_file(b.imports_manifest_path()) or { return []CachedImportModule{} }
    mut imports := []CachedImportModule{}
    for line in manifest.split_into_lines() {
        if !line.starts_with('import:') {
            continue
        }
        rest := line['import:'.len..]
        sep_idx := rest.last_index(':') or { continue }
        import_path := rest[..sep_idx]
        module_name := rest[sep_idx + 1..]
        if import_path.len == 0 || module_name.len == 0 {
            continue
        }
        imports << CachedImportModule{
            import_path: import_path
            module_name: module_name
        }
    }
    return imports
}

fn (b &Builder) cached_virtual_manifest() []CachedVirtualModule {
    manifest := os.read_file(b.virtuals_manifest_path()) or { return []CachedVirtualModule{} }
    mut header_by_group := map[string]string{}
    mut files_by_group := map[string][]string{}
    for line in manifest.split_into_lines() {
        if line.starts_with('virtual:') {
            rest := line['virtual:'.len..]
            sep_idx := rest.last_index(':') or { continue }
            name := rest[..sep_idx]
            header_name := rest[sep_idx + 1..]
            if name == '' || header_name == '' {
                continue
            }
            header_by_group[name] = header_name
            continue
        }
        if line.starts_with('source:') {
            rest := line['source:'.len..]
            sep_idx := rest.index(':') or { continue }
            name := rest[..sep_idx]
            source_file := rest[sep_idx + 1..]
            if name == '' || source_file == '' {
                continue
            }
            mut files := files_by_group[name] or { []string{} }
            files << source_file
            files_by_group[name] = files
        }
    }
    mut groups := []CachedVirtualModule{cap: header_by_group.len}
    mut names := header_by_group.keys()
    names.sort()
    for name in names {
        mut files := files_by_group[name] or { []string{} }
        files.sort()
        if files.len == 0 {
            continue
        }
        groups << CachedVirtualModule{
            name:         name
            header_name:  header_by_group[name]
            source_files: files
        }
    }
    return groups
}

fn (b &Builder) can_use_cached_import_headers_for_parse() bool {
    // Import header reuse is only safe when the cached manifest covers the full
    // transitive import set. The parser currently discovers imports incrementally,
    // so a partial manifest can mix cached .vh files with fresh source modules and
    // leave the combined imports object stale.
    return false
}

fn (b &Builder) can_use_cached_v2compiler_headers_for_parse() bool {
    if !b.is_cmd_v2_self_build() || b.pref.no_cache || b.pref.skip_builtin {
        return false
    }
    if !b.ensure_core_cache_dir() {
        return false
    }
    if !b.can_use_cached_module_bundle_for_parse(v2compiler_cache_name, false) {
        return false
    }
    expected_stamp := b.header_stamp_for_modules(v2compiler_cached_module_paths)
    current_stamp := os.read_file(b.v2compiler_headers_stamp_path()) or { return false }
    if current_stamp != expected_stamp || !stamp_file_lines_are_fresh(current_stamp) {
        return false
    }
    for header_path in b.v2compiler_header_paths() {
        if !os.exists(header_path) || os.file_size(header_path) == 0 {
            return false
        }
    }
    return true
}

// v2compiler_headers_consumed_for_parse reports whether the generated v2compiler .vh module
// headers can ever be read back by the parser. v2compiler header parse-reuse is currently
// disabled (the generated headers are not yet complete/safe), so generating them is dead work on
// a cold self-build. Set V2_V2COMPILER_VH=1 to re-enable generation while iterating on that path.
fn (b &Builder) v2compiler_headers_consumed_for_parse() bool {
    return os.getenv('V2_V2COMPILER_VH') != ''
}

fn (b &Builder) can_use_cached_virtual_headers_for_parse(groups []CachedVirtualModule) bool {
    if groups.len == 0 || b.pref.no_cache || b.pref.skip_builtin {
        return false
    }
    if !b.ensure_core_cache_dir() {
        return false
    }
    if !os.exists(cache_path_join(b.core_cache_dir(), '${virtuals_cache_name}.o'))
        || !os.exists(cache_path_join(b.core_cache_dir(), '${virtuals_cache_name}.stamp')) {
        return false
    }
    expected_stamp := b.virtuals_header_stamp_for_modules(groups)
    current_stamp := os.read_file(b.virtuals_headers_stamp_path()) or { return false }
    if current_stamp != expected_stamp || !stamp_file_lines_are_fresh(current_stamp) {
        return false
    }
    manifest_groups := b.cached_virtual_manifest()
    if manifest_groups.len != groups.len {
        return false
    }
    for group in groups {
        header_path := b.core_header_path(group.header_name)
        if !os.exists(header_path) || os.file_size(header_path) == 0 {
            return false
        }
    }
    return true
}

fn (b &Builder) replace_virtual_sources_with_headers(files []string, groups []CachedVirtualModule) []string {
    if groups.len == 0 {
        return files
    }
    mut source_to_group := map[string]CachedVirtualModule{}
    for group in groups {
        for file in group.source_files {
            source_to_group[os.norm_path(os.abs_path(file))] = group
        }
    }
    mut added_headers := map[string]bool{}
    mut out := []string{cap: files.len}
    for file in files {
        norm_file := os.norm_path(os.abs_path(file))
        if group := source_to_group[norm_file] {
            if group.header_name !in added_headers {
                out << b.core_header_path(group.header_name)
                added_headers[group.header_name] = true
            }
            continue
        }
        out << file
    }
    return out
}

fn (b &Builder) cached_import_parse_path(module_path string) ?string {
    if b.can_use_cached_import_headers_for_parse() {
        for import_mod in b.cached_import_manifest() {
            if import_mod.import_path != module_path {
                continue
            }
            header_path := b.core_header_path(import_mod.module_name)
            if !os.exists(header_path) || os.file_size(header_path) == 0 {
                return none
            }
            return header_path
        }
    }
    for i, cached_module_path in veb_cached_module_paths {
        if module_path != cached_module_path {
            continue
        }
        if !b.can_use_cached_module_bundle_for_parse(veb_cache_name, true) {
            return none
        }
        if i >= veb_cached_module_names.len {
            return none
        }
        header_path := b.core_header_path(veb_cached_module_names[i])
        if !os.exists(header_path) || os.file_size(header_path) == 0 {
            return none
        }
        return header_path
    }
    if b.can_use_cached_v2compiler_headers_for_parse() {
        for i, cached_module_path in v2compiler_cached_module_paths {
            if module_path != cached_module_path {
                continue
            }
            if i >= v2compiler_cached_module_names.len {
                return none
            }
            header_path := b.core_header_path(v2compiler_cached_module_names[i])
            if !os.exists(header_path) || os.file_size(header_path) == 0 {
                return none
            }
            return header_path
        }
    }
    return none
}

fn (b &Builder) can_use_cached_core_headers() bool {
    if b.pref.no_cache || b.pref.skip_builtin {
        return false
    }
    if !b.ensure_core_cache_dir() {
        return false
    }
    cc := configured_cc(b.pref.vroot)
    cc_flags := configured_cflags()
    if !b.can_use_cached_module_bundle(builtin_cache_name, builtin_cached_module_paths, cc,
        cc_flags, '', false) {
        return false
    }
    if vlib_cached_module_paths.len > 0
        && !b.can_use_cached_module_bundle(vlib_cache_name, vlib_cached_module_paths, cc, cc_flags, '', false) {
        return false
    }
    expected_header_stamp := b.header_stamp_for_modules(cached_header_module_paths())
    current_header_stamp := os.read_file(b.core_headers_stamp_path()) or { return false }
    if current_header_stamp != expected_header_stamp {
        return false
    }
    for header_path in b.cached_header_paths() {
        if !os.exists(header_path) {
            return false
        }
        // .vh files must have content — empty headers cause missing
        // symbol errors during split compilation.
        header_size := os.file_size(header_path)
        if header_size == 0 {
            return false
        }
    }
    return true
}

fn (b &Builder) can_use_cached_module_bundle(cache_name string, module_paths []string, cc string, cc_flags string, cc_link_flags string, use_markused bool) bool {
    if !b.ensure_core_cache_dir() {
        return false
    }
    obj_file := cache_name + '.o'
    stamp_file := cache_name + '.stamp'
    obj_path := os.join_path(b.core_cache_dir(), obj_file)
    stamp_path := os.join_path(b.core_cache_dir(), stamp_file)
    if !os.exists(obj_path) || !os.exists(stamp_path) {
        return false
    }
    expected_cache_stamp := b.cache_stamp_for_modules(cache_name, module_paths, cc, cc_flags,
        cc_link_flags, use_markused)
    current_cache_stamp := os.read_file(stamp_path) or { return false }
    return current_cache_stamp == expected_cache_stamp
}

fn (b &Builder) can_use_cached_module_bundle_for_parse(cache_name string, use_markused bool) bool {
    if !b.ensure_core_cache_dir() {
        return false
    }
    obj_path := cache_path_join(b.core_cache_dir(), '${cache_name}.o')
    stamp_path := cache_path_join(b.core_cache_dir(), '${cache_name}.stamp')
    if !os.exists(obj_path) || !os.exists(stamp_path) {
        return false
    }
    stamp := os.read_file(stamp_path) or { return false }
    return stamp.contains('cache=${cache_name}\n')
        && stamp.contains('format=${core_cache_format}\n')
        && stamp.contains('use_markused=${use_markused}\n')
        && stamp.contains('target_os=${b.pref.target_os_or_host()}\n')
}

fn (mut b Builder) ensure_core_module_headers() {
    if !b.ensure_core_cache_dir() {
        return
    }
    expected_stamp := b.header_stamp_for_modules(cached_header_module_paths())
    mut has_headers := true
    for header_path in b.cached_header_paths() {
        if !os.exists(header_path) {
            has_headers = false
            break
        }
    }
    mut needs_regen := !has_headers
    if has_headers {
        current_stamp := os.read_file(b.core_headers_stamp_path()) or { '' }
        if current_stamp != expected_stamp {
            needs_regen = true
        }
    }
    if !needs_regen {
        return
    }
    header_modules := cached_header_module_paths()
    header_source_files := b.parse_module_source_files_for_headers(header_modules)
    source_fn_returns := b.source_fn_return_types(header_modules)
    for module_name in cached_header_module_names() {
        header_ast := b.build_module_header_ast(header_source_files, module_name) or { return }
        mut gen := v.new_gen(b.pref)
        gen.gen(header_ast)
        mut header_source := sanitize_header_source(gen.output_string(), source_fn_returns)
        source_fn_decls := b.source_fn_decls_for_module(module_name)
        header_source = merge_missing_source_fn_decls(header_source, source_fn_decls)
        source_struct_fields := b.source_struct_field_types_for_module(module_name)
        header_source = repair_missing_struct_field_types(header_source, source_struct_fields)
        if header_source.len == 0 {
            // Empty header would cause missing symbols in split compilation.
            // Remove any partial headers already written and skip stamp update
            // so the next build retries generation.
            for cleanup_name in cached_header_module_names() {
                os.rm(b.core_header_path(cleanup_name)) or {}
            }
            os.rm(b.core_headers_stamp_path()) or {}
            return
        }
        if !header_source.ends_with('\n') {
            header_source += '\n'
        }
        os.write_file(b.core_header_path(module_name), header_source) or { return }
    }
    os.write_file(b.core_headers_stamp_path(), expected_stamp) or {}
}

fn (mut b Builder) ensure_import_module_headers(module_names []string) {
    if module_names.len == 0 || !b.ensure_core_cache_dir() {
        return
    }
    imports := b.import_modules_for_cached_modules(module_names)
    if imports.len == 0 {
        return
    }
    expected_stamp := b.imports_header_stamp_for_modules(imports, module_names)
    mut has_headers := true
    for module_name in module_names {
        header_path := b.core_header_path(module_name)
        if !os.exists(header_path) || os.file_size(header_path) == 0 {
            has_headers = false
            break
        }
    }
    if has_headers {
        current_stamp := os.read_file(b.imports_headers_stamp_path()) or { '' }
        if current_stamp == expected_stamp {
            return
        }
    }
    if b.used_import_vh_for_parse {
        return
    }
    header_source_files := b.parse_module_source_files_for_headers(module_names)
    source_fn_returns := b.source_fn_return_types(module_names)
    for module_name in module_names {
        header_ast := b.build_module_header_ast(header_source_files, module_name) or { return }
        mut gen := v.new_gen(b.pref)
        gen.gen(header_ast)
        mut header_source := sanitize_header_source(gen.output_string(), source_fn_returns)
        source_fn_decls := b.source_fn_decls_for_module(module_name)
        header_source = merge_missing_source_fn_decls(header_source, source_fn_decls)
        source_struct_fields := b.source_struct_field_types_for_module(module_name)
        header_source = repair_missing_struct_field_types(header_source, source_struct_fields)
        if header_source.len == 0 {
            for cleanup_name in module_names {
                os.rm(b.core_header_path(cleanup_name)) or {}
            }
            os.rm(b.imports_headers_stamp_path()) or {}
            os.rm(b.imports_manifest_path()) or {}
            return
        }
        if !header_source.ends_with('\n') {
            header_source += '\n'
        }
        os.write_file(b.core_header_path(module_name), header_source) or { return }
    }
    mut manifest_lines := []string{cap: imports.len}
    for import_mod in imports {
        manifest_lines << 'import:${import_mod.import_path}:${import_mod.module_name}'
    }
    os.write_file(b.imports_manifest_path(), manifest_lines.join('\n')) or { return }
    os.write_file(b.imports_headers_stamp_path(), expected_stamp) or {}
}

fn (mut b Builder) ensure_v2compiler_module_headers() {
    if !b.is_cmd_v2_self_build() || !b.ensure_core_cache_dir() {
        return
    }
    expected_stamp := b.header_stamp_for_modules(v2compiler_cached_module_paths)
    mut has_headers := true
    for header_path in b.v2compiler_header_paths() {
        if !os.exists(header_path) || os.file_size(header_path) == 0 {
            has_headers = false
            break
        }
    }
    if has_headers {
        current_stamp := os.read_file(b.v2compiler_headers_stamp_path()) or { '' }
        if current_stamp == expected_stamp {
            return
        }
    }
    header_source_files := b.v2compiler_header_source_files()
    source_fn_returns := b.source_fn_return_types(v2compiler_cached_module_paths)
    for module_name in v2compiler_cached_module_names {
        header_ast := b.build_module_header_ast(header_source_files, module_name) or { return }
        mut gen := v.new_gen(b.pref)
        gen.gen(header_ast)
        mut header_source := sanitize_header_source(gen.output_string(), source_fn_returns)
        source_struct_fields := b.source_struct_field_types_for_module(module_name)
        header_source = repair_missing_struct_field_types(header_source, source_struct_fields)
        if header_source.len == 0 {
            for cleanup_name in v2compiler_cached_module_names {
                os.rm(b.core_header_path(cleanup_name)) or {}
            }
            os.rm(b.v2compiler_headers_stamp_path()) or {}
            return
        }
        if !header_source.ends_with('\n') {
            header_source += '\n'
        }
        os.write_file(b.core_header_path(module_name), header_source) or { return }
    }
    os.write_file(b.v2compiler_headers_stamp_path(), expected_stamp) or {}
}

fn (mut b Builder) v2compiler_header_source_files() []ast.File {
    mut needed := map[string]bool{}
    for module_name in v2compiler_cached_module_names {
        needed[module_name] = true
    }
    mut found := map[string]bool{}
    for file in b.files {
        if file.name == '' || file.name.ends_with('.vh') {
            continue
        }
        module_name := ast_file_module_name(file)
        if module_name in needed {
            found[module_name] = true
        }
    }
    if found.len == needed.len {
        return b.files
    }
    return b.parse_module_source_files_for_headers(v2compiler_cached_module_paths)
}

fn (mut b Builder) ensure_virtual_module_headers(groups []CachedVirtualModule) {
    if groups.len == 0 || !b.ensure_core_cache_dir() {
        return
    }
    expected_stamp := b.virtuals_header_stamp_for_modules(groups)
    mut has_headers := true
    for group in groups {
        header_path := b.core_header_path(group.header_name)
        if !os.exists(header_path) || os.file_size(header_path) == 0 {
            has_headers = false
            break
        }
    }
    if has_headers {
        current_stamp := os.read_file(b.virtuals_headers_stamp_path()) or { '' }
        if current_stamp == expected_stamp {
            return
        }
    }
    if b.used_virtual_vh_for_parse {
        return
    }
    source_files := virtual_module_source_files(groups)
    header_source_files := b.parse_source_files_for_headers(source_files)
    source_fn_returns := b.source_fn_return_types_for_files(source_files)
    for group in groups {
        header_ast := b.build_virtual_module_header_ast(header_source_files, group) or { return }
        mut gen := v.new_gen(b.pref)
        gen.gen(header_ast)
        mut header_source := sanitize_header_source(gen.output_string(), source_fn_returns)
        source_fn_decls := b.source_fn_decls_for_files(group.source_files)
        header_source = merge_missing_source_fn_decls(header_source, source_fn_decls)
        source_struct_fields := b.source_struct_field_types_for_files(group.source_files)
        header_source = repair_missing_struct_field_types(header_source, source_struct_fields)
        if header_source.len == 0 {
            for cleanup_group in groups {
                os.rm(b.core_header_path(cleanup_group.header_name)) or {}
            }
            os.rm(b.virtuals_headers_stamp_path()) or {}
            os.rm(b.virtuals_manifest_path()) or {}
            return
        }
        if !header_source.ends_with('\n') {
            header_source += '\n'
        }
        os.write_file(b.core_header_path(group.header_name), header_source) or { return }
    }
    mut manifest_lines := []string{}
    for group in groups {
        manifest_lines << 'virtual:${group.name}:${group.header_name}'
        for file in group.source_files {
            manifest_lines << 'source:${group.name}:${file}'
        }
    }
    os.write_file(b.virtuals_manifest_path(), manifest_lines.join('\n')) or { return }
    os.write_file(b.virtuals_headers_stamp_path(), expected_stamp) or {}
}

fn (b &Builder) import_modules_for_cached_modules(module_names []string) []CachedImportModule {
    mut module_set := map[string]bool{}
    for module_name in module_names {
        module_set[module_name] = true
    }
    mut import_set := map[string]bool{}
    mut imports := []CachedImportModule{}
    allow_pkgconfig_imports := !b.pref.is_cross_target()
    if b.uses_flat_module_enumeration() {
        for i in 0 .. b.flat.files.len {
            for import_stmt in active_file_imports_from_flat_with_options(&b.flat, b.flat.files[i],
                b.pref.user_defines, b.pref.explicit_user_defines,
                b.pref.source_filter_target_os(), allow_pkgconfig_imports) {
                module_name := import_stmt.name.all_after_last('.')
                if module_name !in module_set {
                    continue
                }
                key := '${import_stmt.name}:${module_name}'
                if key in import_set {
                    continue
                }
                import_set[key] = true
                imports << CachedImportModule{
                    import_path: import_stmt.name
                    module_name: module_name
                }
            }
        }
    } else {
        for file in b.files {
            for import_stmt in active_file_imports_with_options(file, b.pref.user_defines,
                b.pref.explicit_user_defines, b.pref.source_filter_target_os(),
                allow_pkgconfig_imports) {
                module_name := import_stmt.name.all_after_last('.')
                if module_name !in module_set {
                    continue
                }
                key := '${import_stmt.name}:${module_name}'
                if key in import_set {
                    continue
                }
                import_set[key] = true
                imports << CachedImportModule{
                    import_path: import_stmt.name
                    module_name: module_name
                }
            }
        }
    }
    for i := 1; i < imports.len; i++ {
        mut j := i
        for j > 0 && imports[j - 1].import_path > imports[j].import_path {
            imports[j - 1], imports[j] = imports[j], imports[j - 1]
            j--
        }
    }
    return imports
}

fn (b &Builder) source_fn_return_types(modules []string) map[string]string {
    return b.source_fn_return_types_for_files(b.module_source_files(modules))
}

fn (b &Builder) source_fn_return_types_for_files(files []string) map[string]string {
    mut fn_returns := map[string]string{}
    for file in files {
        lines := os.read_lines(file) or { continue }
        for raw_line in lines {
            line := raw_line.trim_space()
            info := parse_fn_signature_and_return(line) or { continue }
            if info.return_type.len > 0 {
                fn_returns[info.signature] = info.return_type
            }
        }
    }
    return fn_returns
}

fn (b &Builder) source_fn_decls_for_module(module_name string) map[string]string {
    return b.source_fn_decls_for_files(b.source_files_for_module_name(module_name))
}

fn (b &Builder) source_fn_decls_for_files(files []string) map[string]string {
    mut decls := map[string]string{}
    for file in files {
        lines := os.read_lines(file) or { continue }
        mut in_interface := false
        mut interface_name := ''
        mut interface_is_public := false
        mut interface_method_is_mut := false
        for raw_line in lines {
            line := raw_line.trim_space()
            if in_interface {
                if line.starts_with('}') {
                    in_interface = false
                    interface_name = ''
                    interface_is_public = false
                    interface_method_is_mut = false
                    continue
                }
                if line.len == 0 || line.starts_with('//') {
                    continue
                }
                if line == 'mut:' {
                    interface_method_is_mut = true
                    continue
                }
                if !header_interface_method_line_is_valid(line) {
                    continue
                }
                open_idx := line.index('(') or { continue }
                close_idx := header_find_matching_paren(line, open_idx) or { continue }
                method_name := line[..open_idx].trim_space()
                if method_name.len == 0 {
                    continue
                }
                params := line[open_idx..close_idx + 1]
                mut ret := line[close_idx + 1..].trim_space()
                if comment_idx := ret.index('//') {
                    ret = ret[..comment_idx].trim_space()
                }
                vis := if interface_is_public { 'pub fn' } else { 'fn' }
                mut decl_line := '${vis} (it ${interface_name}) ${method_name}${params}'
                if ret.len > 0 {
                    decl_line += ' ${ret}'
                }
                if interface_method_is_mut {
                    decl_line = '${vis} (mut it ${interface_name}) ${method_name}${params}'
                    if ret.len > 0 {
                        decl_line += ' ${ret}'
                    }
                }
                info := parse_fn_signature_and_return(decl_line) or { continue }
                decls[info.signature] = decl_line
                continue
            }
            if line.starts_with('pub interface ') || line.starts_with('interface ') {
                if !line.ends_with('{') {
                    continue
                }
                mut body := line
                interface_is_public = body.starts_with('pub interface ')
                if interface_is_public {
                    body = body[4..].trim_space()
                }
                if !body.starts_with('interface ') {
                    continue
                }
                rest := body['interface '.len..]
                interface_name = rest.all_before('{').trim_space()
                if interface_name.len == 0 {
                    continue
                }
                in_interface = true
                interface_method_is_mut = false
                continue
            }
            if !line.starts_with('fn ') && !line.starts_with('pub fn ') {
                continue
            }
            info := parse_fn_signature_and_return(line) or { continue }
            mut decl_line := info.signature
            if info.return_type.len > 0 {
                decl_line += ' ${info.return_type}'
            }
            decls[info.signature] = decl_line
        }
    }
    return decls
}

fn (b &Builder) source_struct_field_types_for_module(module_name string) map[string]string {
    return b.source_struct_field_types_for_files(b.source_files_for_module_name(module_name))
}

fn (b &Builder) source_struct_field_types_for_files(files []string) map[string]string {
    mut field_types := map[string]string{}
    for file in files {
        lines := os.read_lines(file) or { continue }
        mut in_struct := false
        mut struct_name := ''
        for raw_line in lines {
            mut line := raw_line.trim_space()
            if !in_struct {
                if sname := header_struct_block_name(line) {
                    struct_name = sname
                    in_struct = true
                }
                continue
            }
            if line.starts_with('}') {
                in_struct = false
                struct_name = ''
                continue
            }
            if line.len == 0 || line.starts_with('//') || line.starts_with('[') || line == 'mut:'
                || line == 'pub:' || line == 'pub mut:' {
                continue
            }
            if comment_idx := line.index('//') {
                line = line[..comment_idx].trim_space()
            }
            if line.len == 0 {
                continue
            }
            mut lhs := line
            if eq_idx := line.index('=') {
                lhs = line[..eq_idx].trim_space()
            }
            tokens := lhs.split(' ').filter(it.len > 0)
            if tokens.len < 2 {
                continue
            }
            field_name := tokens[0]
            field_type := tokens[1..].join(' ')
            field_types['${struct_name}.${field_name}'] = field_type
        }
    }
    return field_types
}

fn (mut b Builder) parse_module_source_files_for_headers(modules []string) []ast.File {
    return b.parse_source_files_for_headers(b.module_source_files(modules))
}

fn (mut b Builder) parse_source_files_for_headers(source_paths []string) []ast.File {
    mut parser_reused := parser.Parser.new(b.pref)
    return parser_reused.parse_files(source_paths, mut b.file_set)
}

fn (b &Builder) build_module_header_ast(source_files []ast.File, module_name string) ?ast.File {
    return b.build_header_ast_for_files(source_files, module_name, module_name, []string{})
}

fn (b &Builder) build_virtual_module_header_ast(source_files []ast.File, group CachedVirtualModule) ?ast.File {
    return b.build_header_ast_for_files(source_files, 'main', group.header_name, group.source_files)
}

fn (b &Builder) build_header_ast_for_files(source_files []ast.File, module_name string, header_name string, allowed_files []string) ?ast.File {
    mut allowed_set := map[string]bool{}
    for file in allowed_files {
        allowed_set[os.norm_path(file)] = true
    }
    mut found_module := false
    mut module_stmt := ast.ModuleStmt{
        name: module_name
    }
    mut import_stmts := []ast.ImportStmt{}
    mut import_seen := map[string]bool{}
    mut enum_stmts := []ast.Stmt{}
    mut type_decl_stmts := []ast.Stmt{}
    mut type_decl_seen := map[string]bool{}
    mut decl_stmts := []ast.Stmt{}
    for file in source_files {
        if ast_file_module_name(file) != module_name {
            continue
        }
        if allowed_set.len > 0 && os.norm_path(file.name) !in allowed_set {
            continue
        }
        for stmt in file.stmts {
            match stmt {
                ast.ModuleStmt {
                    if !found_module {
                        module_stmt = stmt
                        found_module = true
                    }
                }
                ast.ImportStmt {
                    key := import_stmt_cache_key(stmt)
                    if key !in import_seen {
                        import_seen[key] = true
                        import_stmts << stmt
                    }
                }
                ast.StructDecl {
                    mut sfields := []ast.FieldDecl{cap: stmt.fields.len}
                    for field in stmt.fields {
                        mut field_typ := field.typ
                        if field_typ is ast.EmptyExpr {
                            if inferred_typ := infer_const_type_expr(field.value) {
                                field_typ = inferred_typ
                            } else {
                                continue
                            }
                        }
                        sfields << ast.FieldDecl{
                            name:                field.name
                            typ:                 field_typ
                            value:               field.value
                            attributes:          field.attributes
                            is_public:           field.is_public
                            is_mut:              field.is_mut
                            is_module_mut:       field.is_module_mut
                            is_interface_method: field.is_interface_method
                        }
                    }
                    decl_stmts << ast.Stmt(ast.StructDecl{
                        is_public:      stmt.is_public
                        is_union:       stmt.is_union
                        implements:     stmt.implements
                        embedded:       stmt.embedded
                        language:       stmt.language
                        name:           stmt.name
                        generic_params: stmt.generic_params
                        fields:         sfields
                        pos:            stmt.pos
                    })
                }
                ast.ConstDecl {
                    mut fields := []ast.FieldInit{}
                    for field in stmt.fields {
                        if compact_value := b.header_const_type_expr(module_name, field) {
                            fields << ast.FieldInit{
                                name:  field.name
                                value: compact_value
                            }
                        }
                    }
                    if fields.len > 0 {
                        decl_stmts << ast.Stmt(ast.ConstDecl{
                            is_public: stmt.is_public
                            fields:    fields
                        })
                    }
                }
                ast.EnumDecl {
                    enum_stmts << ast.Stmt(stmt)
                }
                ast.TypeDecl {
                    type_decl := b.resolved_header_type_decl(module_name, stmt) or { continue }
                    type_decl_stmts << ast.Stmt(type_decl)
                    type_decl_seen[type_decl.name] = true
                }
                ast.InterfaceDecl {
                    decl_stmts << ast.Stmt(b.resolved_header_interface_decl(module_name, stmt))
                }
                ast.GlobalDecl {
                    mut gfields := []ast.FieldDecl{cap: stmt.fields.len}
                    for field in stmt.fields {
                        mut global_typ := field.typ
                        if global_typ is ast.EmptyExpr {
                            if inferred_typ := infer_const_type_expr(field.value) {
                                global_typ = inferred_typ
                            } else {
                                continue
                            }
                        }
                        if !header_type_expr_is_usable(global_typ) {
                            continue
                        }
                        gfields << ast.FieldDecl{
                            name:                field.name
                            typ:                 global_typ
                            attributes:          field.attributes
                            is_public:           field.is_public
                            is_mut:              field.is_mut
                            is_module_mut:       field.is_module_mut
                            is_interface_method: field.is_interface_method
                        }
                    }
                    if gfields.len > 0 {
                        decl_stmts << ast.Stmt(ast.GlobalDecl{
                            attributes: stmt.attributes
                            fields:     gfields
                            is_public:  stmt.is_public
                        })
                    }
                }
                ast.FnDecl {
                    resolved_fn := b.resolved_header_fn_decl(module_name, stmt)
                    if !header_fn_decl_is_usable(resolved_fn) {
                        continue
                    }
                    fn_decl := ast.FnDecl{
                        attributes: []ast.Attribute{}
                        is_public:  resolved_fn.is_public
                        is_method:  resolved_fn.is_method
                        is_static:  resolved_fn.is_static
                        receiver:   resolved_fn.receiver
                        language:   resolved_fn.language
                        name:       resolved_fn.name
                        typ:        resolved_fn.typ
                        stmts:      []ast.Stmt{}
                        pos:        resolved_fn.pos
                    }
                    decl_stmts << ast.Stmt(fn_decl)
                }
                else {}
            }
        }
    }
    if allowed_set.len == 0 {
        b.append_source_type_alias_decls(module_name, mut type_decl_stmts, mut type_decl_seen)
    } else {
        b.append_source_type_alias_decls_for_files(allowed_files, mut type_decl_stmts, mut
            type_decl_seen)
    }
    if !found_module || enum_stmts.len + type_decl_stmts.len + decl_stmts.len == 0 {
        return none
    }
    mut header_stmts := []ast.Stmt{cap: 1 + import_stmts.len + enum_stmts.len +
        type_decl_stmts.len + decl_stmts.len}
    header_stmts << ast.Stmt(module_stmt)
    for import_stmt in import_stmts {
        header_stmts << ast.Stmt(import_stmt)
    }
    header_stmts << enum_stmts
    header_stmts << type_decl_stmts
    header_stmts << decl_stmts
    return ast.File{
        mod:     module_stmt.name
        name:    '${header_name}.vh'
        stmts:   header_stmts
        imports: import_stmts
    }
}

fn (b &Builder) resolved_header_interface_decl(module_name string, stmt ast.InterfaceDecl) ast.InterfaceDecl {
    if stmt.fields.len > 0 {
        return stmt
    }
    if module_name == 'builtin' && stmt.name == 'IError' {
        msg_type := ast.Expr(ast.Type(ast.FnType{
            params:      []ast.Parameter{}
            return_type: type_name_to_ast_expr('string')
        }))
        code_type := ast.Expr(ast.Type(ast.FnType{
            params:      []ast.Parameter{}
            return_type: type_name_to_ast_expr('int')
        }))
        return ast.InterfaceDecl{
            is_public:      stmt.is_public
            attributes:     stmt.attributes
            name:           stmt.name
            generic_params: stmt.generic_params
            embedded:       stmt.embedded
            fields:         [
                ast.FieldDecl{
                    name:                'msg'
                    typ:                 msg_type
                    is_interface_method: true
                },
                ast.FieldDecl{
                    name:                'code'
                    typ:                 code_type
                    is_interface_method: true
                },
            ]
        }
    }
    return stmt
}

fn (b &Builder) append_source_type_alias_decls(module_name string, mut type_decl_stmts []ast.Stmt, mut type_decl_seen map[string]bool) {
    b.append_source_type_alias_decls_for_files(b.source_files_for_module_name(module_name), mut
        type_decl_stmts, mut type_decl_seen)
}

fn (b &Builder) append_source_type_alias_decls_for_files(files []string, mut type_decl_stmts []ast.Stmt, mut type_decl_seen map[string]bool) {
    for file in files {
        lines := os.read_lines(file) or { continue }
        for raw_line in lines {
            line := raw_line.trim_space()
            if line.len == 0 || line.starts_with('//') {
                continue
            }
            mut is_public := false
            mut body := line
            if body.starts_with('pub ') {
                is_public = true
                body = body[4..].trim_space()
            }
            if !body.starts_with('type ') || !body.contains('=') {
                continue
            }
            rest := body['type '.len..]
            eq_idx := rest.index('=') or { continue }
            lhs := rest[..eq_idx].trim_space()
            mut lhs_tokens := lhs.split_any(' \t')
            if lhs_tokens.len == 0 {
                continue
            }
            type_name := lhs_tokens[0]
            if type_name.len == 0 || type_name.contains('.') {
                continue
            }
            rhs := rest[eq_idx + 1..].trim_space()
            if rhs.len == 0 {
                continue
            }
            source_decl := ast.TypeDecl{
                is_public: is_public
                language:  .v
                name:      type_name
                base_type: type_name_to_ast_expr(rhs)
            }
            b.set_or_append_type_decl(mut type_decl_stmts, source_decl)
            type_decl_seen[type_name] = true
        }
    }
}

fn (b &Builder) set_or_append_type_decl(mut type_decl_stmts []ast.Stmt, decl ast.TypeDecl) {
    for i, stmt in type_decl_stmts {
        if stmt is ast.TypeDecl && stmt.name == decl.name {
            type_decl_stmts[i] = ast.Stmt(decl)
            return
        }
    }
    type_decl_stmts << ast.Stmt(decl)
}

fn (b &Builder) resolved_header_type_decl(module_name string, stmt ast.TypeDecl) ?ast.TypeDecl {
    if stmt.variants.len > 0 || stmt.base_type !is ast.EmptyExpr {
        return stmt
    }
    base_type_expr := b.lookup_alias_base_type_expr(module_name, stmt.name) or { return none }
    return ast.TypeDecl{
        is_public:      stmt.is_public
        language:       stmt.language
        name:           stmt.name
        generic_params: stmt.generic_params
        base_type:      base_type_expr
        variants:       stmt.variants
    }
}

fn (b &Builder) lookup_alias_base_type_expr(module_name string, type_name string) ?ast.Expr {
    if b.env == unsafe { nil } {
        return b.lookup_alias_source_type_expr(module_name, type_name)
    }
    if scope := b.env.get_scope(module_name) {
        mut mod_scope := unsafe { scope }
        if obj := mod_scope.lookup_parent(type_name, 0) {
            obj_typ := obj.typ()
            if base_type_name := types.alias_base_type_name(obj_typ) {
                return type_name_to_ast_expr(base_type_name)
            }
            obj_type_name := normalize_header_type_name(types.type_name(obj_typ))
            if obj_type_name != '' && obj_type_name != type_name {
                return type_name_to_ast_expr(obj_type_name)
            }
        }
    }
    return b.lookup_alias_source_type_expr(module_name, type_name)
}

fn (b &Builder) resolved_header_fn_decl(module_name string, stmt ast.FnDecl) ast.FnDecl {
    mut resolved_typ := stmt.typ
    if b.env != unsafe { nil } {
        if stmt.is_method {
            receiver_type_name := header_receiver_type_name(stmt.receiver.typ)
            if receiver_type_name != '' {
                if fn_typ := b.env.lookup_method(receiver_type_name, stmt.name) {
                    resolved_typ = merge_header_fn_type(stmt.typ, types.Type(fn_typ))
                }
            }
        } else if scope := b.env.get_scope(module_name) {
            mut mod_scope := unsafe { scope }
            if obj := mod_scope.lookup_parent(stmt.name, 0) {
                obj_typ := obj.typ()
                if obj_typ is types.FnType {
                    resolved_typ = merge_header_fn_type(stmt.typ, obj_typ)
                }
            }
        }
    }
    return ast.FnDecl{
        attributes: stmt.attributes
        is_public:  stmt.is_public
        is_method:  stmt.is_method
        is_static:  stmt.is_static
        receiver:   stmt.receiver
        language:   stmt.language
        name:       stmt.name
        typ:        resolved_typ
        stmts:      stmt.stmts
        pos:        stmt.pos
    }
}

fn header_receiver_type_name(receiver_type_expr ast.Expr) string {
    return match receiver_type_expr {
        ast.ModifierExpr {
            header_receiver_type_name(receiver_type_expr.expr)
        }
        ast.PrefixExpr {
            header_receiver_type_name(receiver_type_expr.expr)
        }
        else {
            receiver_type_expr.name()
        }
    }
}

fn merge_header_fn_type(source_fn ast.FnType, resolved_type types.Type) ast.FnType {
    match resolved_type {
        types.FnType {
            mut merged_return := source_fn.return_type
            if merged_return is ast.EmptyExpr {
                if return_type := resolved_type.get_return_type() {
                    merged_return = type_name_to_ast_expr(types.type_name(return_type))
                }
            }
            mut merged_params := source_fn.params.clone()
            param_types := resolved_type.get_param_types()
            if param_types.len > 0 {
                limit := if merged_params.len < param_types.len {
                    merged_params.len
                } else {
                    param_types.len
                }
                for i in 0 .. limit {
                    if merged_params[i].typ !is ast.EmptyExpr {
                        continue
                    }
                    param_type := type_name_to_ast_expr(types.type_name(param_types[i]))
                    merged_params[i] = ast.Parameter{
                        name:   merged_params[i].name
                        typ:    param_type
                        is_mut: merged_params[i].is_mut
                        pos:    merged_params[i].pos
                    }
                }
            }
            return ast.FnType{
                generic_params: source_fn.generic_params
                params:         merged_params
                return_type:    merged_return
            }
        }
        else {
            return source_fn
        }
    }
}

fn type_name_to_ast_expr(type_name string) ast.Expr {
    norm_name := normalize_header_type_name(type_name)
    return ast.Expr(ast.Ident{
        name: norm_name
    })
}

fn normalize_header_type_name(type_name string) string {
    mut name := type_name.trim_space()
    if name.starts_with('tuple ') {
        name = name['tuple '.len..]
    }
    return name
}

fn (b &Builder) module_name_to_path(module_name string) string {
    return match module_name {
        'bits' { 'math.bits' }
        'cmdline' { 'os.cmdline' }
        'binary' { 'encoding.binary' }
        'sha256' { 'crypto.sha256' }
        'textscanner' { 'strings.textscanner' }
        'termios' { 'term.termios' }
        'http' { 'net.http' }
        'chunked' { 'net.http.chunked' }
        'conv' { 'net.conv' }
        'openssl' { 'net.openssl' }
        'socks' { 'net.socks' }
        'ssl' { 'net.ssl' }
        'urllib' { 'net.urllib' }
        'gzip' { 'compress.gzip' }
        'zlib' { 'compress.zlib' }
        'zstd' { 'compress.zstd' }
        'crc32' { 'hash.crc32' }
        'big' { 'math.big' }
        'stdatomic' { 'sync.stdatomic' }
        'json2' { 'x.json2' }
        'html' { 'encoding.html' }
        'ast' { 'v2.ast' }
        'abi' { 'v2.abi' }
        'builder' { 'v2.builder' }
        'errors' { 'v2.errors' }
        'eval' { 'v2.eval' }
        'arm64' { 'v2.gen.arm64' }
        'c' { 'v2.gen.c' }
        'cleanc' { 'v2.gen.cleanc' }
        'v' { 'v2.gen.v' }
        'x64' { 'v2.gen.x64' }
        'insel' { 'v2.insel' }
        'markused' { 'v2.markused' }
        'mir' { 'v2.mir' }
        'parser' { 'v2.parser' }
        'pref' { 'v2.pref' }
        'scanner' { 'v2.scanner' }
        'ssa' { 'v2.ssa' }
        'optimize' { 'v2.ssa.optimize' }
        'token' { 'v2.token' }
        'transformer' { 'v2.transformer' }
        'types' { 'v2.types' }
        else { module_name }
    }
}

fn (b &Builder) lookup_alias_source_type_expr(module_name string, type_name string) ?ast.Expr {
    for file in b.source_files_for_module_name(module_name) {
        lines := os.read_lines(file) or { continue }
        for raw_line in lines {
            line := raw_line.trim_space()
            if line.len == 0 || line.starts_with('//') {
                continue
            }
            is_type_decl := line.starts_with('type ${type_name} ')
                || line.starts_with('pub type ${type_name} ')
            if !is_type_decl || !line.contains('=') {
                continue
            }
            rhs := line.all_after_first('=').trim_space()
            if rhs.len == 0 {
                continue
            }
            return type_name_to_ast_expr(rhs)
        }
    }
    return none
}

fn (b &Builder) header_const_type_expr(module_name string, field ast.FieldInit) ?ast.Expr {
    if header_const_value_is_safe(field.value) {
        return field.value
    }
    if typed_expr := b.lookup_const_type_expr(module_name, field.name) {
        return typed_expr
    }
    return infer_const_type_expr(field.value)
}

fn header_const_value_is_safe(expr ast.Expr) bool {
    return match expr {
        ast.BasicLiteral, ast.Ident {
            true
        }
        ast.StringLiteral {
            !expr.value.contains('\n') && !expr.value.contains('\r')
        }
        ast.StringInterLiteral {
            expr.values.all(!it.contains('\n') && !it.contains('\r'))
        }
        ast.SelectorExpr {
            header_const_selector_lhs_is_safe(expr.lhs)
        }
        ast.ParenExpr {
            header_const_value_is_safe(expr.expr)
        }
        ast.PrefixExpr {
            header_const_value_is_safe(expr.expr)
        }
        ast.CastExpr {
            header_const_value_is_safe(expr.expr)
        }
        ast.ModifierExpr {
            header_const_value_is_safe(expr.expr)
        }
        ast.InfixExpr {
            header_const_value_is_safe(expr.lhs) && header_const_value_is_safe(expr.rhs)
        }
        ast.CallOrCastExpr {
            if !is_type_expr(expr.lhs) {
                return false
            }
            header_const_value_is_safe(expr.expr)
        }
        ast.ComptimeExpr, ast.IfExpr {
            true
        }
        else {
            false
        }
    }
}

fn header_const_selector_lhs_is_safe(expr ast.Expr) bool {
    return match expr {
        ast.Ident {
            true
        }
        ast.SelectorExpr {
            header_const_selector_lhs_is_safe(expr.lhs)
        }
        else {
            false
        }
    }
}

fn (b &Builder) lookup_const_type_expr(module_name string, const_name string) ?ast.Expr {
    if b.env == unsafe { nil } {
        return none
    }
    scope := b.env.get_scope(module_name) or { return none }
    mut mod_scope := unsafe { scope }
    obj := mod_scope.lookup_parent(const_name, 0) or { return none }
    mut type_name := normalize_const_type_name(module_name, types.type_name(obj.typ()))
    if type_name.len == 0 || !header_type_name_is_sane(type_name) {
        return none
    }
    if !type_name.contains('.') && b.module_defines_c_type(module_name, type_name) {
        type_name = 'C.${type_name}'
    }
    return ast.Expr(ast.Ident{
        name: type_name
    })
}

fn normalize_const_type_name(module_name string, type_name string) string {
    mut name := normalize_header_type_name(type_name)
    if name.len == 0 || !name.contains('__') {
        return name
    }
    if name.starts_with('_option_') || name.starts_with('_result_') || name.starts_with('Array_')
        || name.starts_with('Map_') {
        return name
    }
    idx := name.index('__') or { return name }
    if idx <= 0 || idx + 2 >= name.len {
        return name
    }
    mod_prefix := name[..idx]
    rest := name[idx + 2..]
    if mod_prefix == module_name {
        return rest
    }
    return '${mod_prefix}.${rest}'
}

fn header_type_name_is_sane(type_name string) bool {
    for ch in type_name {
        if ch.is_space() {
            return false
        }
        if ch in [`+`, `-`, `*`, `/`, `%`, `=`, `,`, `;`, `:`, `(`, `)`, `{`, `}`] {
            return false
        }
    }
    return true
}

fn (b &Builder) module_defines_c_type(module_name string, type_name string) bool {
    mut patterns := []string{cap: 4}
    patterns << 'struct C.${type_name}'
    patterns << 'pub struct C.${type_name}'
    patterns << 'type C.${type_name}'
    patterns << 'pub type C.${type_name}'
    for file in b.source_files_for_module_name(module_name) {
        content := os.read_file(file) or { continue }
        for pattern in patterns {
            idx := content.index(pattern) or { continue }
            // Ensure whole-word match: char after pattern must not be alphanumeric or '_'.
            end := idx + pattern.len
            if end < content.len {
                c := content[end]
                if c == `_` || (c >= `a` && c <= `z`) || (c >= `A` && c <= `Z`)
                    || (c >= `0` && c <= `9`) {
                    continue
                }
            }
            return true
        }
    }
    return false
}

fn infer_const_type_expr(expr ast.Expr) ?ast.Expr {
    return match expr {
        ast.IfExpr, ast.ComptimeExpr {
            none
        }
        ast.Type {
            ast.Expr(expr)
        }
        ast.StringLiteral {
            ast.Expr(ast.Ident{
                name: 'string'
            })
        }
        ast.StringInterLiteral {
            ast.Expr(ast.Ident{
                name: 'string'
            })
        }
        ast.BasicLiteral {
            match expr.kind {
                .key_true, .key_false {
                    ast.Expr(ast.Ident{
                        name: 'bool'
                    })
                }
                .char {
                    ast.Expr(ast.Ident{
                        name: 'rune'
                    })
                }
                .number {
                    mut number_type := 'int'
                    if expr.value.contains('.') {
                        number_type = 'f64'
                    }
                    ast.Expr(ast.Ident{
                        name: number_type
                    })
                }
                else {
                    none
                }
            }
        }
        ast.ArrayInitExpr {
            if expr.typ !is ast.EmptyExpr {
                expr.typ
            } else if expr.exprs.len > 0 {
                elem_type := infer_const_type_expr(expr.exprs[0]) or { return none }
                ast.Expr(ast.Type(ast.ArrayType{
                    elem_type: elem_type
                }))
            } else {
                none
            }
        }
        ast.MapInitExpr {
            if expr.typ !is ast.EmptyExpr {
                expr.typ
            } else if expr.keys.len > 0 && expr.vals.len > 0 {
                key_expr := infer_const_type_expr(expr.keys[0]) or { return none }
                val_expr := infer_const_type_expr(expr.vals[0]) or { return none }
                ast.Expr(ast.Type(ast.MapType{
                    key_type:   key_expr
                    value_type: val_expr
                }))
            } else {
                none
            }
        }
        ast.InitExpr {
            expr.typ
        }
        ast.CallOrCastExpr {
            if is_type_expr(expr.lhs) {
                expr.lhs
            } else {
                none
            }
        }
        ast.CastExpr {
            expr.typ
        }
        ast.AsCastExpr {
            expr.typ
        }
        ast.InfixExpr {
            if lhs_expr := infer_const_type_expr(expr.lhs) {
                lhs_expr
            } else {
                infer_const_type_expr(expr.rhs)
            }
        }
        ast.ParenExpr {
            infer_const_type_expr(expr.expr)
        }
        ast.PrefixExpr {
            infer_const_type_expr(expr.expr)
        }
        else {
            none
        }
    }
}

fn is_type_expr(expr ast.Expr) bool {
    return match expr {
        ast.Type, ast.SelectorExpr {
            true
        }
        ast.Ident {
            name := expr.name
                name in ['bool', 'byte', 'char', 'f32', 'f64', 'i8', 'i16', 'i32', 'int', 'i64', 'isize', 'rune', 'string', 'u8', 'u16', 'u32', 'u64', 'usize', 'void', 'voidptr', 'byteptr', 'charptr']
                || name.starts_with('&') || name.starts_with('[]')
                || name.starts_with('?') || name.starts_with('!')
                || name.contains('[') || name.contains('__')
                || (name.len > 0 && name[0].is_capital())
        }
        else {
            false
        }
    }
}

fn import_stmt_cache_key(stmt ast.ImportStmt) string {
    mut key := '${stmt.name}|${stmt.alias}|${stmt.is_aliased}'
    if stmt.symbols.len > 0 {
        mut symbols := []string{cap: stmt.symbols.len}
        for symbol in stmt.symbols {
            symbols << symbol.name()
        }
        key += '|${symbols.join(',')}'
    }
    return key
}

fn header_fn_decl_is_usable(stmt ast.FnDecl) bool {
    if stmt.is_method && !header_type_expr_is_usable(stmt.receiver.typ) {
        return false
    }
    for param in stmt.typ.params {
        if !header_type_expr_is_usable(param.typ) {
            return false
        }
    }
    if stmt.typ.return_type !is ast.EmptyExpr && !header_type_expr_is_usable(stmt.typ.return_type) {
        return false
    }
    return true
}

fn header_type_expr_is_usable(expr ast.Expr) bool {
    return match expr {
        ast.EmptyExpr {
            false
        }
        ast.Ident {
            expr.name.len > 0
        }
        ast.SelectorExpr {
            header_type_expr_is_usable(expr.lhs) && expr.rhs.name.len > 0
        }
        ast.ModifierExpr {
            header_type_expr_is_usable(expr.expr)
        }
        ast.ParenExpr {
            header_type_expr_is_usable(expr.expr)
        }
        ast.PrefixExpr {
            header_type_expr_is_usable(expr.expr)
        }
        ast.IndexExpr {
            header_type_expr_is_usable(expr.lhs) && header_type_expr_is_usable(expr.expr)
        }
        ast.GenericArgs {
            if !header_type_expr_is_usable(expr.lhs) {
                return false
            }
            for arg in expr.args {
                if !header_type_expr_is_usable(arg) {
                    return false
                }
            }
            true
        }
        ast.GenericArgOrIndexExpr {
            header_type_expr_is_usable(expr.lhs) && header_type_expr_is_usable(expr.expr)
        }
        ast.Type {
            header_type_node_is_usable(expr)
        }
        else {
            false
        }
    }
}

fn header_type_node_is_usable(node ast.Type) bool {
    return match node {
        ast.ArrayType {
            header_type_expr_is_usable(node.elem_type)
        }
        ast.ArrayFixedType {
            header_type_expr_is_usable(node.elem_type)
        }
        ast.ChannelType {
            header_type_expr_is_usable(node.elem_type)
        }
        ast.FnType {
            for param in node.params {
                if !header_type_expr_is_usable(param.typ) {
                    return false
                }
            }
            if node.return_type !is ast.EmptyExpr {
                return header_type_expr_is_usable(node.return_type)
            }
            return true
        }
        ast.GenericType {
            header_type_expr_is_usable(node.name)
        }
        ast.MapType {
            header_type_expr_is_usable(node.key_type) && header_type_expr_is_usable(node.value_type)
        }
        ast.OptionType {
            node.base_type !is ast.EmptyExpr && header_type_expr_is_usable(node.base_type)
        }
        ast.PointerType {
            header_type_expr_is_usable(node.base_type)
        }
        ast.ResultType {
            node.base_type !is ast.EmptyExpr && header_type_expr_is_usable(node.base_type)
        }
        ast.ThreadType {
            node.elem_type is ast.EmptyExpr || header_type_expr_is_usable(node.elem_type)
        }
        ast.TupleType {
            for t in node.types {
                if !header_type_expr_is_usable(t) {
                    return false
                }
            }
            true
        }
        ast.AnonStructType {
            true
        }
        ast.NilType, ast.NoneType {
            true
        }
    }
}

struct FnReturnInfo {
    signature   string
    return_type string
}

fn parse_fn_signature_and_return(line string) ?FnReturnInfo {
    mut i := line.index('fn ') or { return none }
    i += 3
    for i < line.len && line[i].is_space() {
        i++
    }
    // Optional method receiver: fn (<receiver>) name(...)
    if i < line.len && line[i] == `(` {
        recv_end := header_find_matching_paren(line, i) or { return none }
        i = recv_end + 1
        for i < line.len && line[i].is_space() {
            i++
        }
    }
    mut generic_depth := 0
    for i < line.len {
        if line[i] == `[` {
            generic_depth++
        } else if line[i] == `]` && generic_depth > 0 {
            generic_depth--
        } else if line[i] == `(` && generic_depth == 0 {
            break
        }
        i++
    }
    if i >= line.len || line[i] != `(` {
        return none
    }
    params_end := header_find_matching_paren(line, i) or { return none }
    signature := line[..params_end + 1].trim_space()
    mut j := params_end + 1
    for j < line.len && line[j].is_space() {
        j++
    }
    mut return_type := line[j..].trim_space()
    if return_type.ends_with('{') {
        return_type = return_type[..return_type.len - 1].trim_space()
    }
    if return_type.ends_with(';') {
        return_type = return_type[..return_type.len - 1].trim_space()
    }
    return FnReturnInfo{
        signature:   signature
        return_type: return_type
    }
}

fn restore_fn_return_type_from_source(line string, source_fn_returns map[string]string) string {
    trimmed := line.trim_space()
    info := parse_fn_signature_and_return(trimmed) or { return line }
    if info.return_type.len > 0 {
        return line
    }
    return_type := source_fn_returns[info.signature] or { return line }
    mut indent_len := 0
    for indent_len < line.len && line[indent_len].is_space() {
        indent_len++
    }
    indent := line[..indent_len]
    return '${indent}${info.signature} ${return_type}'
}

fn merge_missing_source_fn_decls(header_source string, source_fn_decls map[string]string) string {
    if source_fn_decls.len == 0 || header_source.len == 0 {
        return header_source
    }
    mut existing := map[string]bool{}
    for line in header_source.split_into_lines() {
        info := parse_fn_signature_and_return(line.trim_space()) or { continue }
        existing[info.signature] = true
    }
    mut keys := source_fn_decls.keys()
    keys.sort()
    mut extra := []string{}
    for key in keys {
        if key in existing {
            continue
        }
        extra << source_fn_decls[key]
    }
    if extra.len == 0 {
        return header_source
    }
    mut merged := header_source
    if !merged.ends_with('\n') {
        merged += '\n'
    }
    merged += extra.join('\n')
    merged += '\n'
    return merged
}

fn header_struct_block_name(trimmed string) ?string {
    if !trimmed.ends_with('{') {
        return none
    }
    mut body := trimmed
    if body.starts_with('pub ') {
        body = body[4..].trim_space()
    }
    if body.starts_with('struct ') {
        name := body['struct '.len..].all_before('{').trim_space()
        return if name.len > 0 { name } else { none }
    }
    if body.starts_with('union ') {
        name := body['union '.len..].all_before('{').trim_space()
        return if name.len > 0 { name } else { none }
    }
    return none
}

fn leading_ws(line string) string {
    mut i := 0
    for i < line.len && line[i].is_space() {
        i++
    }
    return line[..i]
}

fn repair_missing_struct_field_types(header_source string, source_struct_fields map[string]string) string {
    if header_source.len == 0 || source_struct_fields.len == 0 {
        return header_source
    }
    lines := header_source.split_into_lines()
    mut out := []string{cap: lines.len}
    mut in_struct := false
    mut struct_name := ''
    for raw_line in lines {
        mut line := raw_line
        trimmed := line.trim_space()
        if !in_struct {
            if sname := header_struct_block_name(trimmed) {
                struct_name = sname
                in_struct = true
            }
            out << line
            continue
        }
        if trimmed.starts_with('}') {
            in_struct = false
            struct_name = ''
            out << line
            continue
        }
        if trimmed.len == 0 || trimmed.starts_with('//') || trimmed.starts_with('[')
            || trimmed == 'mut:' || trimmed == 'pub:' || trimmed == 'pub mut:' {
            out << line
            continue
        }
        mut no_comment := trimmed
        if comment_idx := no_comment.index('//') {
            no_comment = no_comment[..comment_idx].trim_space()
        }
        if no_comment.len == 0 {
            out << line
            continue
        }
        if eq_idx := no_comment.index('=') {
            lhs := no_comment[..eq_idx].trim_space()
            if header_token_count(lhs) == 1 {
                field_name := lhs
                field_type := source_struct_fields['${struct_name}.${field_name}'] or { '' }
                if field_type.len > 0 {
                    rhs := no_comment[eq_idx + 1..].trim_space()
                    out << '${leading_ws(line)}${field_name} ${field_type} = ${rhs}'
                    continue
                }
            }
        }
        out << line
    }
    return out.join('\n')
}

fn sanitize_header_source(source string, source_fn_returns map[string]string) string {
    lines := source.split_into_lines()
    mut out := []string{cap: lines.len}
    mut in_global_block := false
    mut global_start_line := ''
    mut global_body_lines := []string{}
    mut in_type_block := false
    mut in_enum_block := false
    mut in_interface_block := false
    for source_line in lines {
        mut line := source_line
        line = restore_fn_return_type_from_source(line, source_fn_returns)
        trimmed := line.trim_space()
        if !in_global_block {
            if header_starts_type_block(trimmed) {
                in_type_block = true
                in_enum_block = trimmed.starts_with('enum ') || trimmed.starts_with('pub enum ')
                in_interface_block = trimmed.starts_with('interface ')
                    || trimmed.starts_with('pub interface ')
                out << line
                continue
            }
            if in_type_block {
                if trimmed == '}' {
                    in_type_block = false
                    in_enum_block = false
                    in_interface_block = false
                    out << line
                    continue
                }
                if !in_enum_block
                    && header_type_block_line_is_malformed(trimmed, in_interface_block) {
                    continue
                }
            }
        }
        if header_starts_global_block(trimmed) {
            in_global_block = true
            global_start_line = line
            global_body_lines = []string{}
            continue
        }
        if in_global_block {
            if trimmed == ')' {
                in_global_block = false
                if global_body_lines.len > 0 {
                    out << global_start_line
                    out << global_body_lines
                    out << line
                }
                continue
            }
            if header_token_count(trimmed) < 2 {
                continue
            }
            global_body_lines << line
            continue
        }
        if (trimmed.starts_with('fn ') || trimmed.starts_with('pub fn '))
            && !header_is_c_fn_decl_line(trimmed) && header_fn_decl_line_is_malformed(trimmed) {
            continue
        }
        if (trimmed.starts_with('type ') || trimmed.starts_with('pub type '))
            && header_type_decl_line_is_malformed(trimmed) {
            continue
        }
        if (trimmed.starts_with('const ') || trimmed.starts_with('pub const '))
            && header_const_decl_line_is_malformed(trimmed) {
            continue
        }
        // Drop stray code lines that are not valid module-level declarations.
        // These can leak from the V gen output for complex modules.
        if !in_type_block && !in_global_block && trimmed.len > 0
            && !header_is_module_level_line(trimmed) {
            continue
        }
        out << line
    }
    return out.join('\n')
}

fn header_starts_global_block(trimmed string) bool {
    return trimmed == '__global (' || trimmed == 'pub __global ('
}

fn header_is_module_level_line(trimmed string) bool {
    if trimmed.len == 0 {
        return true
    }
    if trimmed.starts_with('//') || trimmed.starts_with('[') || trimmed.starts_with('@[') {
        return true
    }
    if trimmed == '}' || trimmed == ')' || trimmed == 'mut:' || trimmed == 'pub:'
        || trimmed == 'pub mut:' {
        return true
    }
    return trimmed.starts_with('module ') || trimmed.starts_with('import ')
        || trimmed.starts_with('fn ') || trimmed.starts_with('pub fn ')
        || trimmed.starts_with('struct ') || trimmed.starts_with('pub struct ')
        || trimmed.starts_with('enum ') || trimmed.starts_with('pub enum ')
        || trimmed.starts_with('type ') || trimmed.starts_with('pub type ')
        || trimmed.starts_with('const ') || trimmed.starts_with('pub const ')
        || trimmed.starts_with('interface ') || trimmed.starts_with('pub interface ')
        || trimmed.starts_with('union ') || trimmed.starts_with('pub union ')
        || trimmed.starts_with('__global') || trimmed.starts_with('pub __global')
}

fn header_starts_type_block(trimmed string) bool {
    if !trimmed.ends_with('{') {
        return false
    }
    return trimmed.starts_with('struct ') || trimmed.starts_with('pub struct ')
        || trimmed.starts_with('union ') || trimmed.starts_with('pub union ')
        || trimmed.starts_with('interface ') || trimmed.starts_with('pub interface ')
        || trimmed.starts_with('enum ') || trimmed.starts_with('pub enum ')
}

fn header_is_c_fn_decl_line(trimmed string) bool {
    return trimmed.starts_with('fn C.') || trimmed.starts_with('pub fn C.')
}

fn header_type_block_line_is_malformed(trimmed string, in_interface_block bool) bool {
    if trimmed.len == 0 {
        return false
    }
    if trimmed.starts_with('[') || trimmed.starts_with('@[') || trimmed.starts_with('//') {
        return false
    }
    if trimmed == 'mut:' || trimmed == 'pub:' || trimmed == 'pub mut:'
        || trimmed == 'pub module_mut:' {
        return false
    }
    if in_interface_block && header_interface_method_line_is_valid(trimmed) {
        return false
    }
    if (trimmed.starts_with('fn ') || trimmed.starts_with('pub fn '))
        && header_fn_decl_line_is_malformed(trimmed) {
        return true
    }
    if header_token_count(trimmed) >= 2 {
        return false
    }
    // Single-token lowercase lines in type blocks are almost always fields with missing types.
    token := trimmed.trim_space()
    if token.len == 0 {
        return false
    }
    first := token[0]
    return first >= `a` && first <= `z`
}

fn header_interface_method_line_is_valid(trimmed string) bool {
    open_idx := trimmed.index('(') or { return false }
    if open_idx <= 0 {
        return false
    }
    close_idx := header_find_matching_paren(trimmed, open_idx) or { return false }
    method_name := trimmed[..open_idx].trim_space()
    if method_name.len == 0 || method_name.contains(' ') {
        return false
    }
    after := trimmed[close_idx + 1..].trim_space()
    return after.len == 0 || !after.contains('{')
}

fn header_fn_decl_line_is_malformed(line string) bool {
    mut i := line.index('fn ') or { return false }
    i += 3
    for i < line.len && line[i].is_space() {
        i++
    }
    // Optional method receiver: fn (<receiver>) name(...)
    if i < line.len && line[i] == `(` {
        recv_end := header_find_matching_paren(line, i) or { return true }
        receiver := line[i + 1..recv_end].trim_space()
        if receiver.len == 0 {
            return true
        }
        if !header_receiver_decl_is_valid(receiver) {
            return true
        }
        i = recv_end + 1
        for i < line.len && line[i].is_space() {
            i++
        }
    }
    // Function name
    for i < line.len && !line[i].is_space() && line[i] != `(` {
        i++
    }
    for i < line.len && line[i].is_space() {
        i++
    }
    if i >= line.len || line[i] != `(` {
        return true
    }
    params_end := header_find_matching_paren(line, i) or { return true }
    params := line[i + 1..params_end]
    return header_params_are_malformed(params)
}

fn header_receiver_decl_is_valid(receiver string) bool {
    mut text := receiver
    if text.starts_with('mut ') {
        text = text[4..].trim_space()
    }
    if text.starts_with('shared ') {
        text = text[7..].trim_space()
    }
    return header_token_count(text) >= 2
}

fn header_params_are_malformed(params string) bool {
    mut start := 0
    mut depth := 0
    for i, ch in params {
        match ch {
            `(`, `[`, `{` {
                depth++
            }
            `)`, `]`, `}` {
                depth--
            }
            `,` {
                if depth == 0 {
                    part := params[start..i].trim_space()
                    if part.len > 0 && !header_param_decl_is_valid(part) {
                        return true
                    }
                    start = i + 1
                }
            }
            else {}
        }
    }
    last := params[start..].trim_space()
    if last.len > 0 && !header_param_decl_is_valid(last) {
        return true
    }
    return false
}

fn header_param_decl_is_valid(param string) bool {
    mut text := param
    if text.starts_with('mut ') {
        text = text[4..].trim_space()
    }
    if text.starts_with('shared ') {
        text = text[7..].trim_space()
    }
    if text.starts_with('...') {
        return text.len > 3
    }
    // Header declarations should always carry both parameter name and type.
    return header_token_count(text) >= 2
}

fn header_token_count(text string) int {
    mut count := 0
    for token in text.split_any(' \t') {
        if token.len > 0 {
            count++
        }
    }
    return count
}

fn header_find_matching_paren(text string, start int) ?int {
    if start < 0 || start >= text.len || text[start] != `(` {
        return none
    }
    mut depth := 0
    for i := start; i < text.len; i++ {
        ch := text[i]
        if ch == `(` {
            depth++
        } else if ch == `)` {
            depth--
            if depth == 0 {
                return i
            }
        }
    }
    return none
}

fn header_type_decl_line_is_malformed(line string) bool {
    if !line.contains('=') {
        return false
    }
    rhs := line.all_after_first('=').trim_space()
    return rhs.len == 0
}

fn header_const_decl_line_is_malformed(line string) bool {
    if !line.contains('=') {
        return false
    }
    rhs := line.all_after_first('=').trim_space()
    return rhs.len == 0
}