//! Radiance compiler front-end.

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::printer;

use std::lang::sexpr;

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

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 = 64;

/// Maximum number of packages we can compile.

constant MAX_PACKAGES: u32 = 4;

/// Total module entries across all packages.

constant MAX_TOTAL_MODULES: u32 = 192;

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

constant MAX_SOURCES_SIZE: u32 = 2097152;

/// 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 (40 MB) - retains parsed nodes throughout compilation.

constant TEMP_ARENA_SIZE: u32 = 41943040;

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

constant FN_ARENA_SIZE: u32 = 16777216;

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

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

constant MAIN_ARENA_SIZE: u32 = 83886080;

/// AST storage arena.

static TEMP_ARENA: [u8; TEMP_ARENA_SIZE] = undefined;

/// Scratch storage reclaimed after each generated function.

static FN_ARENA: [u8; FN_ARENA_SIZE] = undefined;

/// Main storage arena - persists throughout compilation.

static MAIN_ARENA: [u8; MAIN_ARENA_SIZE] = undefined;

/// Module source code.

static MODULE_SOURCES: [u8; MAX_SOURCES_SIZE] = undefined;

/// Module entries for all packages.

static MODULE_ENTRIES: [module::ModuleEntry; MAX_TOTAL_MODULES] = undefined;

/// String pool.

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

/// Package scope.

static RESOLVER_PKG_SCOPE: resolver::Scope = undefined;

/// Errors emitted by resolver.

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

/// Code generation storage.

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

/// Hash table entries for data symbol lookup.

static CODEGEN_DATA_SYM_ENTRIES: [dict::Entry; data::DATA_SYM_TABLE_SIZE] = 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] = undefined;

/// Read-write data buffer.

static RW_DATA_BUF: [u8; MAX_RW_DATA_SIZE] = undefined;

/// Assembly module source buffer.

static ASM_SOURCE_BUF: [u8; MAX_SOURCES_SIZE] = undefined;

/// Temporary assembly text buffer.

static ASM_TEXT_BUF: [u32; 262144] = undefined;

/// Temporary assembly data buffer.

static ASM_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = undefined;

/// Accumulated assembly read-only data.

static ASM_RO_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = undefined;

/// Assembly source file extension.

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

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

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>\n";

/// Compiler error.

union Error {

    Other,

}

/// What to dump during compilation.

union Dump {

    /// 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 {

    /// 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 {

    /// 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],

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

    debug: bool,

}

/// Root module info for a package.

record RootModule {

    entry: *module::ModuleEntry,

    ast: *mut ast::Node,

}

/// State carried by the streaming lowerer/codegen callback.

record CodegenSinkContext {

    /// RV64 generator receiving lowered functions.

    generator: *mut rv64::Generator,

    /// Arena holding the current function's lowered IL.

    fnArena: *mut alloc::Arena,

}

/// Entry handling for streamed code generation.

union CodegenEntryMode {

    /// 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 {

    /// 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: undefined,

        radPathCount: 0,

        asmPaths: undefined,

        asmPathCount: 0,

    };

}

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

fn processModule(

    pkg: *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, path) catch {

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

    };

    // Read file into remaining arena space.

    let buffer = alloc::remainingBuf(sourceArena);

    if buffer.len == 0 {

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

    }

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

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

    };

    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.

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 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 = &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 = &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, "-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"]);

        }

    }

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

    let mut ctx = CompileContext {

        packages: undefined,

        inputs,

        packageCount: pkgCount,

        entryPkgIdx,

        graph,

        config: resolver::Config { buildTest },

        dump,

        outputPath,

        debug: debugEnabled,

    };

    // Initialize and parse all packages.

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

    for i in 0..pkgCount {

        package::init(&mut ctx.packages[i], i as u16, ctx.inputs[i].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 = rootEntry.ast else {

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

    };

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

}

/// Dump the module graph.

fn dumpGraph(ctx: *CompileContext) {

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

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

}

/// Dump the parsed AST.

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.

fn lowerAllPackages(

    ctx: *mut CompileContext,

    res: *mut resolver::Resolver

) -> 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 mut low = lower::lowerer(

        res, &ctx.graph, entryPkg.name, &mut res.arena, &mut res.arena, options

    );

    try lowerAllPackagesInto(ctx, res, &mut low);

    // Finalize and return the unified program.

    return lower::finalize(&low);

}

/// Lower all packages into an existing lowerer.

fn lowerAllPackagesInto(

    ctx: *mut CompileContext,

    res: *mut resolver::Resolver,

    low: *mut lower::Lowerer

) throws (Error) {

    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, res, low, &mut ctx.packages[i], false);

        }

    }

    // Lower entry package.

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

}

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

fn lowerPackage(

    ctx: *CompileContext,

    res: *mut resolver::Resolver,

    low: *mut lower::Lowerer,

    pkg: *mut package::Package,

    isEntry: bool

) throws (Error) {

    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, &ctx.graph, pkg.name);

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

}

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

fn lowerModuleTreeInto(

    ctx: *CompileContext,

    low: *mut lower::Lowerer,

    graph: *module::ModuleGraph,

    modId: u16,

    isRoot: bool,

    pkg: *package::Package

) throws (Error) {

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

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

    };

    let modAst = entry.ast else {

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

    };

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

    try lower::lowerModule(low, modId, modAst, isRoot) 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..entry.childrenLen {

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

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

    }

}

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

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 = entry.ast 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.

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 all parsed modules 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.

fn generateTestRunner(

    ctx: *mut CompileContext,

    arena: *mut ast::NodeArena

) throws (Error) {

    let entryPkg = try getEntryPackage(ctx);

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

    // Collect all test functions across all 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) {

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

        }

    }

    if testCount == 0 {

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

    }

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

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

    pkgLog(entryPkg, &["found", countStr, "test(s)"]);

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

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

    injectIntoBlock(root.ast, arena, fnDecl);

}

/// Synthesize the test entry point.

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, mutable: false,

    }));

    // 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 }));

    // Build: `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),

    };

    // `@default` attribute.

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

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

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

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

        name: fnName, params: ast::nodeSlice(arena, 0), sig: fnSig, body: fnBody, attrs: fnAttrs,

    }));

}

/// Append a declaration to a block node's statement list.

fn injectIntoBlock(

    blockNode: *mut ast::Node,

    arena: *mut ast::NodeArena,

    decl: *ast::Node

) {

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

        panic "injectIntoBlock: expected Block node";

    };

    let stmts = block.statements.append(decl, alloc::arenaAllocator(&mut arena.arena));

    set blockNode.value = ast::NodeValue::Block(ast::Block { statements: stmts });

}

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

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 headerWords = &header[..];

    let headerBytes = @sliceOf(headerWords.ptr as *u8, headerWords.len * rv64::WORD_SIZE as u32);

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

    return unix::writeFileParts(path, &[headerBytes, codeBytes, roData, rwData]);

}

/// 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] = undefined;

    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}`.

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(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.

fn runResolver(ctx: *mut CompileContext, nodeCount: u32) -> resolver::Resolver throws (Error) {

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

    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);

    let storage = resolver::ResolverStorage {

        arena: mainArena,

        nodeData,

        pkgScope: &mut RESOLVER_PKG_SCOPE,

        errors: &mut RESOLVER_ERRORS[..],

    };

    let mut res = resolver::resolver(storage, ctx.config);

    // Build the semantic package list consumed by the resolver.

    let mut resolverPkgs: [resolver::Pkg; MAX_PACKAGES] = undefined;

    let mut resolverPackageCount: u32 = 0;

    for i in 0..ctx.packageCount {

        let pkg = &ctx.packages[i];

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

        set resolverPkgs[resolverPackageCount] = resolver::Pkg {

            rootEntry: root.entry,

            rootAst: root.ast,

        };

        set resolverPackageCount += 1;

    }

    // Resolve all packages.

    // TODO: Fix this error printing dance.

    let diags = try resolver::resolve(&mut res, &ctx.graph, &resolverPkgs[..resolverPackageCount]) catch {

        let diags = resolver::Diagnostics { errors: res.errors };

        resolver::printer::printDiagnostics(&diags, &res);

        throw Error::Other;

    };

    if not resolver::success(&diags) {

        resolver::printer::printDiagnostics(&diags, &res);

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

        let countStr = fmt::formatU32(diags.errors.len, &mut countBuf[..]);

        throw error(&["failed:", countStr, "errors"]);

    }

    return res;

}

/// Emit one lowered function to machine code and reclaim its IL arena.

fn generateLoweredFn(ctxPtr: *mut opaque, func: *il::Fn, role: lower::FnRole) {

    let ctx = ctxPtr as *mut CodegenSinkContext;

    match role {

        case lower::FnRole::Default => {

            rv64::recordFunctionAlias(ctx.generator, DEFAULT_ENTRY_SYMBOL);

            match ctx.generator.entryPatch {

                case rv64::EntryPatch::Reserved(_) => {

                    set ctx.generator.entryPatch = rv64::EntryPatch::Reserved(func.name);

                }

                // No entry jump was reserved: startup assembly calls the

                // default function through `DEFAULT_ENTRY_SYMBOL` instead.

                case rv64::EntryPatch::None => {}

            }

        }

        else => {}

    }

    rv64::generateFunction(ctx.generator, func, ctx.fnArena);

    alloc::reset(ctx.fnArena);

}

/// Assemble one `.ras` input and merge it into the active code generator.

///

/// Text symbols are appended to `generator`. Data emitted by the assembler is

/// copied into `ASM_RO_DATA_BUF` at `*asmDataLen`, and `*asmDataLen` is advanced

/// so the next assembly module receives the correct rodata base address.

fn assembleAsmModule(

    generator: *mut rv64::Generator,

    pkg: *package::Package,

    path: *[u8],

    asmDataLen: *mut u32,

    arena: *mut alloc::Arena

) throws (Error) {

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

    let source = unix::readFile(path, &mut ASM_SOURCE_BUF[..]) else {

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

    };

    if source.len == ASM_SOURCE_BUF.len {