//! Radiance compiler front-end.

mod codegen;

use std::mem;

use std::fmt;

use std::io;

use std::lang::alloc;

use std::lang::ast;

use std::lang::parser;

use std::lang::scanner;

use std::lang::resolver;

use std::lang::module;

use std::lang::strings;

use std::lang::package;

use std::lang::il;

use std::lang::lower;

use std::arch::rv64;

use std::arch::rv64::asm;

use std::arch::rv64::emit;

use std::arch::rv64::printer;

use std::lang::sexpr;

use std::lang::gen::data;

use std::lang::il::binary;

use std::lang::il::binary::collect;

use std::lang::il::binary::program;

use std::lang::gen::labels;

use std::lang::gen::types;

use std::sys;

use std::sys::unix;

use std::collections::dict;

/// Maximum number of modules we can load per package.

constant MAX_LOADED_MODULES: u32 = 128;

/// Maximum number of packages we can compile.

constant MAX_PACKAGES: u32 = 4;

/// Source code buffer arena (4 MB).

constant MAX_SOURCES_SIZE: u32 = 4194304;

/// Maximum number of test functions we can discover.

constant MAX_TESTS: u32 = 1024;

/// Maximum number of assembly source paths we can load per package.

constant MAX_ASM_MODULES: u32 = 64;

/// AST arena size (64 MB) - retains parsed nodes throughout compilation.

constant TEMP_ARENA_SIZE: u32 = 67108864;

/// Per-function lowering and register-allocation arena size (16 MB).

constant FN_ARENA_SIZE: u32 = 16777216;

/// Main arena size (176 MB) - lives throughout compilation.

/// Used for: resolver data, types, symbols, global IL data, and codegen output.

constant MAIN_ARENA_SIZE: u32 = 184549376;

/// AST storage arena.

static TEMP_ARENA: [u8; TEMP_ARENA_SIZE] = [0; TEMP_ARENA_SIZE];

/// Scratch storage reclaimed after each generated function.

static FN_ARENA: [u8; FN_ARENA_SIZE] = [0; FN_ARENA_SIZE];

/// Main storage arena - persists throughout compilation.

static MAIN_ARENA: [u8; MAIN_ARENA_SIZE] = [0; MAIN_ARENA_SIZE];

/// Module source code.

static MODULE_SOURCES: [u8; MAX_SOURCES_SIZE] = [0; MAX_SOURCES_SIZE];

/// Module entries for all packages.

unsafe static MODULE_ENTRIES: [?*module::ModuleEntry; module::MAX_MODULES] = [nil; module::MAX_MODULES];

/// String pool.

unsafe static STRING_POOL: strings::Pool = strings::Pool { table: undefined, count: 0 };

/// Package scope.

unsafe static RESOLVER_PKG_SCOPE: resolver::Scope = undefined;

/// Errors emitted by resolver.

unsafe static RESOLVER_ERRORS: [resolver::Error; resolver::MAX_ERRORS] = undefined;

/// Code generation storage.

unsafe static CODEGEN_DATA_SYMS: [data::DataSym; data::MAX_DATA_SYMS] = undefined;

/// Hash table entries for data symbol lookup.

unsafe static CODEGEN_DATA_SYM_ENTRIES: [dict::Entry; data::DATA_SYM_TABLE_SIZE] = undefined;

/// Emitted instruction storage.

static CODEGEN_INSTRUCTIONS: [u32; emit::MAX_INSTRS] = [0; emit::MAX_INSTRS];

/// Local branch patch storage.

unsafe static CODEGEN_PENDING_BRANCHES: [emit::PendingBranch; emit::MAX_PENDING] = undefined;

/// Function call patch storage.

unsafe static CODEGEN_PENDING_CALLS: [emit::PendingCall; emit::MAX_PENDING] = undefined;

/// Assembly jump patch storage.

unsafe static CODEGEN_PENDING_JUMPS: [emit::PendingJump; emit::MAX_PENDING] = undefined;

/// Address load patch storage.

unsafe static CODEGEN_PENDING_ADDR_LOADS: [emit::PendingAddrLoad; emit::MAX_PENDING] = undefined;

/// Per-function block offset storage.

static CODEGEN_BLOCK_OFFSETS: [i32; labels::MAX_BLOCKS_PER_FN] = [0; labels::MAX_BLOCKS_PER_FN];

/// Function label hash table storage.

unsafe static CODEGEN_FUNC_ENTRIES: [dict::Entry; labels::FUNC_TABLE_SIZE] = undefined;

/// Printed function address storage.

unsafe static CODEGEN_FUNCS: [types::FuncAddr; emit::MAX_FUNCS] = undefined;

/// Debug location storage.

unsafe static CODEGEN_DEBUG_ENTRIES: [types::DebugEntry; emit::MAX_DEBUG_ENTRIES] = undefined;

/// Maximum number of exported definitions in one binary package.

constant MAX_PACKAGE_EXPORTS: u32 = 8192;

/// Maximum number of indexed names in one binary package.

constant MAX_PACKAGE_SYMBOLS: u32 = 16384;

/// Export workspace reused for each binary package.

unsafe static PACKAGE_EXPORTS: [binary::Export; MAX_PACKAGE_EXPORTS] = undefined;

/// Symbol workspace reused for each binary package.

unsafe static PACKAGE_SYMBOLS: [*[u8]; MAX_PACKAGE_SYMBOLS] = undefined;

/// Debug info file extension.

constant DEBUG_EXT: *[u8] = ".debug";

/// Maximum rodata size (4MB).

constant MAX_RO_DATA_SIZE: u32 = 4194304;

/// Maximum rwdata size (4MB).

constant MAX_RW_DATA_SIZE: u32 = 4194304;

/// Maximum path length.

constant MAX_PATH_LEN: u32 = 256;

/// Read-only data buffer.

static RO_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = [0; MAX_RO_DATA_SIZE];

/// Read-write data buffer.

static RW_DATA_BUF: [u8; MAX_RW_DATA_SIZE] = [0; MAX_RW_DATA_SIZE];

/// Assembly module source buffer.

static ASM_SOURCE_BUF: [u8; MAX_SOURCES_SIZE] = [0; MAX_SOURCES_SIZE];

/// Temporary assembly text buffer.

static ASM_TEXT_BUF: [u32; 262144] = [0; 262144];

/// Temporary assembly data buffer.

static ASM_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = [0; MAX_RO_DATA_SIZE];

/// Accumulated assembly read-only data.

static ASM_RO_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = [0; MAX_RO_DATA_SIZE];

/// Assembly source file extension.

constant ASM_SOURCE_EXT: *[u8] = ".ras";

/// Symbol name exported for startup code to call the semantic entry function.

export constant DEFAULT_ENTRY_SYMBOL: *[u8] = "::default";

/// Usage string.

constant USAGE: *[u8] =

    "usage: radiance -pkg <name> [-start <input.ras>] -mod <input>.. [-pkg <name> -mod <input>..] -entry <pkg> [-o <output> | -ril <directory>]\n";

/// Compiler error.

union Error: Copy {

    Other,

}

/// What to dump during compilation.

union Dump: Copy {

    /// Don't dump anything.

    None,

    /// Dump the parsed AST before semantic analysis.

    Ast,

    /// Dump the module graph.

    Graph,

    /// Dump the IL.

    Il,

    /// Dump the generated assembly.

    Asm,

}

/// A discovered test function.

record TestDesc: Copy {

    /// Full module qualified path segments (eg. ["std", "tests"]).

    modPath: *[*[u8]],

    /// Test function name (eg. "testFoo").

    fnName: *[u8],

}

/// Source inputs belonging to one command-line package.

record PackageInput: Copy {

    /// Package name from the `-pkg` argument.

    name: *[u8],

    /// Optional startup assembly emitted before generated text.

    startupPath: ?*[u8],

    /// Radiance source paths for this package.

    radPaths: [*[u8]; MAX_LOADED_MODULES],

    /// Number of Radiance source paths.

    radPathCount: u32,

    /// Assembly source paths for this package.

    asmPaths: [*[u8]; MAX_ASM_MODULES],

    /// Number of assembly source paths.

    asmPathCount: u32,

}

/// Compilation context.

record CompileContext {

    /// Array of packages to compile.

    packages: [package::Package; MAX_PACKAGES],

    /// Driver inputs for each package slot.

    inputs: [PackageInput; MAX_PACKAGES],

    /// Number of packages.

    packageCount: u32,

    /// Index of entry package.

    entryPkgIdx: ?u32,

    /// Global module graph shared by all packages.

    graph: module::ModuleGraph,

    /// Resolver configuration.

    config: resolver::Config,

    /// What to dump during compilation.

    dump: Dump,

    /// Output path for binary.

    outputPath: ?*[u8],

    /// Output directory for separate binary RIL packages.

    rilDirectory: ?*[u8],

    /// Whether to emit debug info (.debug file).

    debug: bool,

}

/// Root module info for a package.

record RootModule: Copy {

    entry: *module::ModuleEntry,

    ast: *ast::Node,

}

/// Entry handling for streamed code generation.

union CodegenEntryMode: Copy {

    /// Do not reserve an entry jump.

    None,

    /// Reserve and patch an entry jump to the `@default` function.

    DefaultEntry,

}

/// Options controlling streamed lowering and code generation.

record CodegenOptions: Copy {

    /// Optional output path used for progress logging.

    logPath: ?*[u8],

    /// Whether to emit debug source locations.

    debug: bool,

    /// How the generated program should handle entry.

    entryMode: CodegenEntryMode,

}

/// Print a driver error line.

fn error(msg: &[*[u8]]) -> Error {

    io::printError("radiance: ");

    for part, i in msg {

        io::printError(part);

        if i < msg.len - 1 {

            io::printError(" ");

        }

    }

    io::printError("\n");

    return Error::Other;

}

/// Print a log line for the given package.

fn pkgLog(pkg: &package::Package, msg: &[*[u8]]) {

    io::printError("radiance: ");

    io::printError(pkg.name);

    io::printError(": ");

    for part, i in msg {

        io::printError(part);

        if i < msg.len - 1 {

            io::printError(" ");

        }

    }

    io::printError("\n");

}

/// Return `true` when `path` ends with `ext`.

fn hasExtension(path: *[u8], ext: *[u8]) -> bool {

    if path.len < ext.len {

        return false;

    }

    let start = path.len - ext.len;

    return mem::eq(&path[start..], ext);

}

/// Create an empty source input set for one package.

fn packageInput(name: *[u8]) -> PackageInput {

    return PackageInput {

        name,

        startupPath: nil,

        radPaths: [""; MAX_LOADED_MODULES],

        radPathCount: 0,

        asmPaths: [""; MAX_ASM_MODULES],

        asmPathCount: 0,

    };

}

/// Register, load, and parse `path` within `pkg`.

unsafe fn processModule(

    pkg: *unsafe mut package::Package,

    graph: &mut module::ModuleGraph,

    path: *[u8],

    nodeArena: &mut ast::NodeArena,

    sourceArena: &mut alloc::Arena

) throws (Error) {

    pkgLog(pkg, &["parsing", "(", path, ")", ".."]);

    let moduleId = try package::registerModule(pkg, graph, &mut STRING_POOL, path) catch {

        throw error(&["error registering module"]);

    };

    // Read file into remaining arena space.

    let buffer = alloc::remainingBuf(&mut *sourceArena);

    if buffer.len == 0 {

        throw error(&["fatal:", "source arena exhausted"]);

    }

    let sourceLen = unix::readFile(path, buffer) else {

        throw error(&["error reading file"]);

    };

    let source = &buffer[..sourceLen];

    if source.len == buffer.len {

        throw error(&["fatal:", "source arena too small, file truncated:", path]);

    }

    // Commit only what was read.

    alloc::commit(sourceArena, source.len);

    let ast = try parser::parse(scanner::SourceLoc::File(path), source, nodeArena, &mut STRING_POOL) catch {

        throw Error::Other;

    };

    try module::setAst(graph, moduleId, ast) catch {

        throw error(&["error setting AST"]);

    };

    try module::setSource(graph, moduleId, source) catch {

        throw error(&["error setting source"]);

    };

}

/// Consume the next argument, or print an error and throw.

fn nextArg(args: *[*[u8]], idx: &mut u32, msg: &[*[u8]]) -> *[u8] throws (Error) {

    set *idx += 1;

    if *idx >= args.len {

        throw error(msg);

    }

    return args[*idx];

}

/// Parse CLI arguments and return compilation context.

unsafe fn processCommand(

    args: *[*[u8]],

    arena: &mut ast::NodeArena

) -> CompileContext throws (Error) {

    let mut buildTest = false;

    let mut debugEnabled = false;

    let mut outputPath: ?*[u8] = nil;

    let mut rilDirectory: ?*[u8] = nil;

    let mut dump = Dump::None;

    let mut entryPkgName: ?*[u8] = nil;

    // Per-package source path tracking.

    let mut inputs: [PackageInput; MAX_PACKAGES] = undefined;

    let mut pkgCount: u32 = 0;

    let mut currentPkgIdx: ?u32 = nil;

    if args.len == 0 {

        io::printError(USAGE);

        throw Error::Other;

    }

    let mut idx: u32 = 0;

    while idx < args.len {

        let arg = args[idx];

        if mem::eq(arg, "-pkg") {

            try nextArg(args, &mut idx, &["`-pkg` requires a package name"]);

            if pkgCount >= MAX_PACKAGES {

                throw error(&["too many packages specified"]);

            }

            set inputs[pkgCount] = packageInput(args[idx]);

            set currentPkgIdx = pkgCount;

            set pkgCount += 1;

        } else if mem::eq(arg, "-mod") {

            try nextArg(args, &mut idx, &["`-mod` requires a module path"]);

            let pkgIdx = currentPkgIdx else {

                throw error(&["`-mod` must follow a `-pkg` argument"]);

            };

            let input: *unsafe mut PackageInput = &mut inputs[pkgIdx];

            if hasExtension(args[idx], ASM_SOURCE_EXT) {

                if input.asmPathCount >= MAX_ASM_MODULES {

                    throw error(&["too many assembly modules specified"]);

                }

                set input.asmPaths[input.asmPathCount] = args[idx];

                set input.asmPathCount += 1;

            } else {

                if input.radPathCount >= MAX_LOADED_MODULES {

                    throw error(&["too many modules specified for package"]);

                }

                set input.radPaths[input.radPathCount] = args[idx];

                set input.radPathCount += 1;

            }

        } else if mem::eq(arg, "-start") {

            try nextArg(args, &mut idx, &["`-start` requires an assembly path"]);

            let pkgIdx = currentPkgIdx else {

                throw error(&["`-start` must follow a `-pkg` argument"]);

            };

            let input: *unsafe mut PackageInput = &mut inputs[pkgIdx];

            if input.startupPath <> nil {

                throw error(&["package", input.name, "has more than one startup file"]);

            }

            if not hasExtension(args[idx], ASM_SOURCE_EXT) {

                throw error(&["`-start` requires a `.ras` assembly file"]);

            }

            set input.startupPath = args[idx];

        } else if mem::eq(arg, "-entry") {

            try nextArg(args, &mut idx, &["`-entry` requires a package name"]);

            set entryPkgName = args[idx];

        } else if mem::eq(arg, "-test") {

            set buildTest = true;

        } else if mem::eq(arg, "-debug") {

            set debugEnabled = true;

        } else if mem::eq(arg, "-o") {

            try nextArg(args, &mut idx, &["`-o` requires an output path"]);

            set outputPath = args[idx];

        } else if mem::eq(arg, "-ril") {

            try nextArg(args, &mut idx, &["`-ril` requires an output directory"]);

            set rilDirectory = args[idx];

        } else if mem::eq(arg, "-dump") {

            try nextArg(args, &mut idx, &["`-dump` requires a mode (eg. ast)"]);

            let mode = args[idx];

            if mem::eq(mode, "ast") {

                set dump = Dump::Ast;

            } else if mem::eq(mode, "graph") {

                set dump = Dump::Graph;

            } else if mem::eq(mode, "il") {

                set dump = Dump::Il;

            } else if mem::eq(mode, "asm") {

                set dump = Dump::Asm;

            } else {

                throw error(&["unknown dump mode", mode, "(expected: ast, graph, il, asm)"]);

            }

        } else {

            throw error(&["unknown argument", arg]);

        }

        set idx += 1;

    }

    if pkgCount == 0 {

        throw error(&["no package specified"]);

    }

    for i in 0..pkgCount {

        if inputs[i].radPathCount == 0 {

            throw error(&["package", inputs[i].name, "has no Radiance modules specified"]);

        }

    }

    // Determine entry package index.

    let mut entryPkgIdx: ?u32 = nil;

    if pkgCount == 1 {

        // Single package: it is the entry.

        set entryPkgIdx = 0;

    } else {

        // Multiple packages: need -entry.

        let entryName = entryPkgName else {

            throw error(&["`-entry` required when multiple packages specified"]);

        };

        for i in 0..pkgCount {

            if mem::eq(inputs[i].name, entryName) {

                set entryPkgIdx = i;

                break;

            }

        }

        if entryPkgIdx == nil {

            throw error(&["fatal:", "entry package", entryName, "not found"]);

        }

    }

    let entryIdx = entryPkgIdx else {

        panic "processCommand: no entry package";

    };

    for i in 0..pkgCount {

        if i <> entryIdx and inputs[i].startupPath <> nil {

            throw error(&["`-start` is only supported on the entry package"]);

        }

    }

    if rilDirectory <> nil and (outputPath <> nil or dump <> Dump::None) {

        throw error(&["`-ril` requires a separate invocation from `-o` or `-dump`"]);

    }

    let graph = module::moduleGraph(&mut MODULE_ENTRIES[..], arena);

    let mut ctx = CompileContext {

        packages: undefined,

        inputs,

        packageCount: pkgCount,

        entryPkgIdx,

        graph,

        config: resolver::Config { buildTest },

        dump,

        outputPath,

        rilDirectory,

        debug: debugEnabled,

    };

    // Initialize and parse all packages.

    let mut sourceArena = alloc::new(&mut MODULE_SOURCES[..]);

    for i in 0..pkgCount {

        let name = ctx.inputs[i].name;

        package::init(&mut ctx.packages[i], i as u16, name, &mut STRING_POOL);

        for j in 0..ctx.inputs[i].radPathCount {

            let path = ctx.inputs[i].radPaths[j];

            try processModule(&mut ctx.packages[i], &mut ctx.graph, path, arena, &mut sourceArena);

        }

    }

    return ctx;

}

/// Get the entry package from the context.

fn getEntryPackage(ctx: &CompileContext) -> package::Package throws (Error) {

    let entryIdx = ctx.entryPkgIdx else {

        throw error(&["no entry package specified"]);

    };

    return ctx.packages[entryIdx];

}

/// Return the startup assembly path for the entry package, if one was supplied.

fn getEntryStartupPath(ctx: &CompileContext) -> ?*[u8] {

    let entryIdx = ctx.entryPkgIdx else {

        panic "getEntryStartupPath: no entry package";

    };

    return ctx.inputs[entryIdx].startupPath;

}

/// Get root module info from a package.

fn getRootModule(pkg: &package::Package, graph: &module::ModuleGraph) -> RootModule throws (Error) {

    let rootId = pkg.rootModuleId else {

        throw error(&["no root module found"]);

    };

    let rootEntry = module::get(graph, rootId) else {

        throw error(&["root module entry not found"]);

    };

    let rootAst = module::astFor(rootEntry) else {

        throw error(&["root module has no AST"]);

    };

    return RootModule { entry: rootEntry, ast: rootAst };

}

/// Dump the module graph.

unsafe fn dumpGraph(ctx: &CompileContext) {

    let mut arena = alloc::new(&mut MAIN_ARENA[..]);

    module::printer::printGraph(&ctx.graph, &mut arena);

}

/// Dump the parsed AST.

unsafe fn dumpAst(ctx: &CompileContext) throws (Error) {

    let pkg = try getEntryPackage(ctx);

    let root = try getRootModule(&pkg, &ctx.graph);

    let mut arena = alloc::new(&mut MAIN_ARENA[..]);

    ast::printer::printTree(root.ast, &mut arena);

}

/// Lower all packages into a single IL program.

/// Dependencies are lowered first, then the entry package.

unsafe fn lowerAllPackages 'arena (

    ctx: *unsafe mut CompileContext,

    res: *unsafe mut resolver::Resolver 'arena

) -> il::Program throws (Error) {

    let entryIdx = ctx.entryPkgIdx else {

        panic "lowerAllPackages: no entry package";

    };

    let entryPkg = &ctx.packages[entryIdx];

    // Create the lowerer accumulator using entry package's name.

    let options = lower::LowerOptions { debug: ctx.debug, buildTest: ctx.config.buildTest };

    let arena = (&mut *res.arena) as *unsafe mut alloc::Arena;

    let resolved: 'phase = &*res, graph = &ctx.graph where 'arena: 'phase in {

        let mut low = lower::lowerer(

            resolved, graph, entryPkg.name, arena, options

        );

        try lowerAllPackagesInto(ctx, &mut low, &mut *arena);

        // Finalize and return the unified program.

        return lower::finalize(low);

    }

}

/// Lower all packages into an existing lowerer.

unsafe fn lowerAllPackagesInto 'arena 'phase (

    ctx: &CompileContext,

    low: &mut lower::Lowerer 'arena 'phase,

    functionArena: &mut alloc::Arena

) throws (Error) where 'arena: 'phase {

    let entryIdx = ctx.entryPkgIdx else {

        panic "lowerAllPackagesInto: no entry package";

    };

    // Lower all packages except entry.

    for i in 0..ctx.packageCount {

        if i <> entryIdx {

            try lowerPackage(ctx, low, &ctx.packages[i], false, functionArena);

        }

    }

    // Lower entry package.

    try lowerPackage(ctx, low, &ctx.packages[entryIdx], true, functionArena);

}

/// Lower all modules in a package into the lowerer accumulator.

unsafe fn lowerPackage 'arena 'phase (

    ctx: &CompileContext,

    low: &mut lower::Lowerer 'arena 'phase,

    pkg: &package::Package,

    isEntry: bool,

    functionArena: &mut alloc::Arena

) throws (Error) where 'arena: 'phase {

    let rootId = pkg.rootModuleId else {

        throw error(&["no root module found"]);

    };

    // Set lowerer's package context for qualified name generation.

    // TODO: We shouldn't have to call this manually.

    lower::setPackage(low, pkg.name);

    try lowerModuleTreeInto(ctx, low, &ctx.graph, rootId, isEntry, pkg, functionArena);

}

/// Recursively lower a module and all its children into the accumulator.

unsafe fn lowerModuleTreeInto 'arena 'phase (

    ctx: &CompileContext,

    low: &mut lower::Lowerer 'arena 'phase,

    graph: &module::ModuleGraph,

    modId: u16,

    isRoot: bool,

    pkg: &package::Package,

    functionArena: &mut alloc::Arena

) throws (Error) where 'arena: 'phase {

    let entry = module::get(graph, modId) else {

        throw error(&["module entry not found"]);

    };

    let modAst = module::astFor(entry) else {

        throw error(&["module has no AST"]);

    };

    pkgLog(pkg, &["lowering", "(", entry.filePath, ")", ".."]);

    try lower::lowerModule(low, modId, modAst, isRoot, functionArena) catch err {

        io::printError("radiance: ");

        io::printError("internal error during lowering: ");

        lower::printError(err);

        io::printError("\n");

        throw Error::Other;

    };

    // Recurse into children.

    for i in 0..module::childCount(entry) {

        let childId = module::childAt(entry, i);

        try lowerModuleTreeInto(ctx, low, graph, childId, false, pkg, functionArena);

    }

}

/// Build a scope access chain: a::b::c from a slice of identifiers.

unsafe fn synthScopeAccess(arena: &mut ast::NodeArena, path: &[*[u8]]) -> *ast::Node {

    let mut result = ast::synthNode(

        arena,

        ast::NodeValue::Ident(strings::intern(&mut STRING_POOL, path[0]))

    );

    for i in 1..path.len {

        let child = ast::synthNode(

            arena,

            ast::NodeValue::Ident(strings::intern(&mut STRING_POOL, path[i]))

        );

        set result = ast::synthNode(arena, ast::NodeValue::ScopeAccess(ast::Access {

            parent: result, child,

        }));

    }

    return result;

}

/// Check if a function declaration has the `@test` attribute and return its name if so.

fn getTestFnName(decl: &ast::FnDecl) -> ?*[u8] {

    let attrs = decl.attrs else { return nil; };

    if not ast::attributesContains(&attrs, ast::Attribute::Test) {

        return nil;

    }

    let case ast::NodeValue::Ident(name) = decl.name.value

        else return nil;

    return name;

}

/// Scan a single module's AST for `@test` functions and append them to `tests`.

fn collectModuleTests(

    entry: *module::ModuleEntry,

    tests: &mut [TestDesc],

    testCount: &mut u32

) {

    let modAst = module::astFor(entry) else {

        return;

    };

    let case ast::NodeValue::Block(block) = modAst.value else {

        return;

    };

    let modPath = module::moduleQualifiedPath(entry);

    for stmt in block.statements {

        if let case ast::NodeValue::FnDecl(decl) = stmt.value {

            if let fnName = getTestFnName(&decl) {

                if *testCount < tests.len {

                    set tests[*testCount] = TestDesc { modPath, fnName };

                    set *testCount += 1;

                } else {

                    panic "collectModuleTests: too many tests";

                }

            }

        }

    }

}

/// Synthesize a `testing::test("mod", "name", mod::fn)` call for one test.

unsafe fn synthTestCall(arena: &mut ast::NodeArena, desc: &TestDesc) -> *ast::Node {

    let callee = synthScopeAccess(arena, &["testing", "test"]);

    let modStr = il::formatQualifiedName(

        &mut arena.arena,

        &desc.modPath[..desc.modPath.len - 1],

        desc.modPath[desc.modPath.len - 1]

    );

    let modArg = ast::synthNode(arena, ast::NodeValue::String(modStr));

    let nameArg = ast::synthNode(arena, ast::NodeValue::String(desc.fnName));

    // Intra-package path: skip the package name prefix.

    let mut funcPath: [*[u8]; 16] = undefined;

    for j in 1..desc.modPath.len {

        set funcPath[j - 1] = desc.modPath[j];

    }

    set funcPath[desc.modPath.len - 1] = desc.fnName;

    let funcArg = synthScopeAccess(arena, &funcPath[..desc.modPath.len]);

    let a = alloc::arenaAllocator(&mut arena.arena);

    let args = ast::nodeSlice(arena, 3)

        .append(modArg, a)

        .append(nameArg, a)

        .append(funcArg, a);

    return ast::synthNode(arena, ast::NodeValue::Call(ast::Call { callee, args }));

}

/// Inject a test runner into the entry package's root module.

///

/// Scans the entry package for `@test fn` declarations, then appends

/// a synthetic entry point to the root module's AST block:

///

/// ```

/// @default fn #testMain() -> i32 {

///     return testing::runAllTests(&[

///         testing::test("std::tests", "testFoo", tests::testFoo),

///         ...

///     ]);

/// }

/// ```

///

/// Uses `#`-prefixed names to avoid conflicts with user code.

unsafe fn generateTestRunner(

    ctx: *unsafe mut CompileContext,

    arena: &mut ast::NodeArena

) throws (Error) {

    let entryPkg = try getEntryPackage(ctx);

    let root = try getRootModule(&entryPkg, &ctx.graph);

    // Collect test functions from the entry package's modules.

    let mut tests: [TestDesc; MAX_TESTS] = undefined;

    let mut testCount: u32 = 0;

    for modIdx in 0..ctx.graph.entriesLen {

        if let entry = module::get(&ctx.graph, modIdx as u16) {

            if entry.packageId == entryPkg.id {

                collectModuleTests(entry, &mut tests[..], &mut testCount);

            }

        }

    }

    if testCount == 0 {

        throw error(&["fatal:", "no test functions found"]);

    }

    let mut countBuf: [u8; 10] = undefined;

    let start = fmt::formatU32(testCount, &mut countBuf[..]);

    io::printError("radiance: ");

    io::printError(entryPkg.name);

    io::printError(": found ");

    io::printError(&countBuf[start..]);

    io::printError(" test(s)\n");

    // Synthesize the `@default` function and append to the root module.

    let fnDecl = synthTestMainFn(arena, &tests[..testCount]);

    let updatedRoot = injectIntoBlock(root.ast, arena, fnDecl);

    try module::setAst(&mut ctx.graph, root.entry.id, updatedRoot) catch {

        throw error(&["failed to set test runner AST"]);

    };

}

/// Synthesize the test entry point.

unsafe fn synthTestMainFn(arena: &mut ast::NodeArena, tests: &[TestDesc]) -> *ast::Node {

    // Build array literal: `[testing::test(...), ...]`.

    let a = alloc::arenaAllocator(&mut arena.arena);

    let mut elements = ast::nodeSlice(arena, tests.len as u32);

    for i in 0..tests.len {

        elements.append(synthTestCall(arena, &tests[i]), a);

    }

    let arrayLit = ast::synthNode(arena, ast::NodeValue::ArrayLit(elements));

    // Build: `&[...]`.

    let testsRef = ast::synthNode(arena, ast::NodeValue::AddressOf(ast::AddressOf {

        target: arrayLit, kind: ast::AddressKind::Shared,

    }));

    // Build: `testing::runAllTests(&[...])`.

    let runFn = synthScopeAccess(arena, &["testing", "runAllTests"]);

    let callArgs = ast::nodeSlice(arena, 1).append(testsRef, a);

    let callExpr = ast::synthNode(arena, ast::NodeValue::Call(ast::Call {

        callee: runFn, args: callArgs,

    }));

    // Build: `return testing::runAllTests(&[...]);`

    let retStmt = ast::synthNode(arena, ast::NodeValue::Return { value: callExpr });

    let bodyStmts = ast::nodeSlice(arena, 1).append(retStmt, a);

    let fnBody = ast::synthNode(arena, ast::NodeValue::Block(ast::Block { statements: bodyStmts, isUnsafe: false }));

    // Build: `unsafe fn #testMain() -> i32`

    let fnName = ast::synthNode(arena, ast::NodeValue::Ident(strings::intern(&mut STRING_POOL, "#testMain")));

    let returnType = ast::synthNode(arena, ast::NodeValue::TypeSig(ast::TypeSig::Integer {

        width: 4, sign: ast::Signedness::Signed,

    }));

    let fnSig = ast::FnSig {

        params: ast::nodeSlice(arena, 0),

        returnType,

        throwList: ast::nodeSlice(arena, 0),

    };

    // Entry and function safety attributes.

    let attrNode = ast::synthNode(arena, ast::NodeValue::Attribute(ast::Attribute::Default));

    let unsafeAttr = ast::synthNode(arena, ast::NodeValue::Attribute(ast::Attribute::Unsafe));

    let attrList = ast::nodeSlice(arena, 2).append(attrNode, a).append(unsafeAttr, a);

    let fnAttrs = ast::Attributes { list: attrList };

    return ast::synthNode(arena, ast::NodeValue::FnDecl(ast::FnDecl {

        name: fnName, regions: &[], sig: fnSig, body: fnBody, attrs: fnAttrs,

    }));

}

/// Build a block node with a declaration appended to its statement list.

unsafe fn injectIntoBlock(

    blockNode: *ast::Node,

    arena: &mut ast::NodeArena,

    decl: *ast::Node

) -> *ast::Node {

    let case ast::NodeValue::Block(block) = blockNode.value else {

        panic "injectIntoBlock: expected Block node";

    };

    let allocator = alloc::arenaAllocator(&mut arena.arena);

    let mut stmts = ast::nodeSlice(arena, block.statements.len + 1);

    for stmt in block.statements {

        stmts.append(stmt, allocator);

    }

    stmts.append(decl, allocator);

    return ast::allocNode(arena, blockNode.span, ast::NodeValue::Block(

        ast::Block { statements: stmts, isUnsafe: block.isUnsafe }

    ));

}

/// Write a self-contained RV64 image containing text and data sections.

unsafe fn writeImage(

    code: *[u32],

    roData: *[u8],

    rwData: *[u8],

    path: *[u8]

) -> bool {

    let mut header = rv64::imageHeader(code.len * rv64::INSTR_SIZE as u32, roData.len, rwData.len);

    let headerBytes: *unsafe [u8] = @sliceOf(&header[0] as *unsafe u8, header.len * rv64::WORD_SIZE as u32);

    let codeBytes = @sliceOf(code.ptr as *u8, code.len * rv64::INSTR_SIZE as u32);

    let fd = unix::openOpts(path, unix::OpenFlags(*unix::O_WRONLY | *unix::O_CREAT | *unix::O_TRUNC), 420);

    if fd < 0 { return false; }

    let written = unix::writeAll(fd, headerBytes) and unix::writeAll(fd, codeBytes)

        and unix::writeAll(fd, roData) and unix::writeAll(fd, rwData);

    let closed = unix::close(fd) == 0;

    return written and closed;

}

/// Write a data section to a file at `basePath` + `ext`.

/// Empty data truncates any stale sidecar left by an earlier build.

fn writeDataWithExt(

    data: *[u8],

    basePath: *[u8],

    ext: *[u8]

) throws (Error) {

    let mut path: [u8; MAX_PATH_LEN] = [0; MAX_PATH_LEN];

    let mut pos: u32 = 0;

    set pos += try! mem::copy(&mut path[pos..], basePath);

    set pos += try! mem::copy(&mut path[pos..], ext);

    set path[pos] = 0; // Null-terminate for syscall.

    if not unix::writeFile(&path[..pos], data) {

        throw error(&["fatal:", "failed to write data file"]);

    }

}

/// Serialize debug entries and write the `.debug` file.

/// Resolves module IDs to file paths via the module graph.

/// Format per entry is `{pc: u32,  offset: u32, filePath: [u8], NULL}`.

unsafe fn writeDebugInfo(

    entries: *[types::DebugEntry],

    graph: &module::ModuleGraph,

    basePath: *[u8],

    arena: &mut alloc::Arena

) throws (Error) {

    if entries.len == 0 {

        return;

    }

    // Use remaining arena space as serialization buffer.

    let buf = alloc::remainingBuf(&mut *arena);

    let mut pos: u32 = 0;

    for i in 0..entries.len {

        let entry = &entries[i];

        let modEntry = module::get(graph, entry.moduleId) else {

            panic "writeDebugInfo: module not found for debug entry";

        };

        set pos += try! mem::copy(&mut buf[pos..], @sliceOf(&entry.pc as *u8, 4));

        set pos += try! mem::copy(&mut buf[pos..], @sliceOf(&entry.offset as *u8, 4));

        set pos += try! mem::copy(&mut buf[pos..], modEntry.filePath);

        set buf[pos] = 0;

        set pos += 1;

    }

    try writeDataWithExt(&buf[..pos], basePath, DEBUG_EXT);

}

/// Run the resolver on the parsed modules.

unsafe fn runResolver 'arena (ctx: *unsafe mut CompileContext, mainArena: &'arena mut alloc::Arena, nodeCount: u32) -> resolver::Resolver 'arena throws (Error) {

    let entryPkg = try getEntryPackage(ctx);

    pkgLog(&entryPkg, &["resolving", ".."]);

    let nodeDataSize = nodeCount * @sizeOf(resolver::NodeData);

    let nodeDataPtr = try! alloc::alloc(&mut *mainArena, nodeDataSize, @alignOf(resolver::NodeData));

    let nodeData = @sliceOf(nodeDataPtr as *mut resolver::NodeData, nodeCount);