llvm-native-core 0.1.16

//! Clang Main Entry Point — `main()` for the Clang C/C++ frontend.
//!
//! Provides the `clang_main()` function that parses command-line arguments,
//! creates a `CompilerInstance`, and runs the full compilation pipeline.
//! Also includes tool entry points (`cc1`, `cc1plus`), driver mode
//! detection by `argv[0]`, response file expansion, version/help printing,
//! and various utility flags.
//!
//! Clean-room behavioral reconstruction from published Clang/LLVM
//! documentation and the Clang driver architecture.

use std::env;
use std::fs;
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::process;

use crate::Module;

use super::clang_pipeline::{
    compile_to_ir, compile_to_object, CompilationDriver, CompilerInstance, CompilerInvocation,
    CompilerOptions, FrontendAction, FrontendActionKind, InputLanguage, OptLevel,
};
use super::driver::ClangDriver;
use super::{CLangStandard, ClangOptions};

// ═══════════════════════════════════════════════════════════════════════════════
// Driver mode — detected by argv[0]
// ═══════════════════════════════════════════════════════════════════════════════

/// Which compiler driver mode we are running in.
///
/// Detected from `argv[0]`:
/// - `clang` → C compiler
/// - `clang++` / `clang-cpp` → C++ compiler
/// - `clang-cl` → MSVC-compatible driver
/// - `cc1` → C compiler frontend
/// - `cc1plus` → C++ compiler frontend
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DriverMode {
    /// C compiler (`clang`).
    Clang,
    /// C++ compiler (`clang++`).
    ClangXX,
    /// MSVC-compatible driver (`clang-cl`).
    ClangCL,
    /// C compiler frontend (`cc1`).
    CC1,
    /// C++ compiler frontend (`cc1plus`).
    CC1Plus,
    /// Preprocessor and compiler (`clang-cpp`).
    ClangCPP,
    /// Unknown / generic.
    Unknown,
}

impl DriverMode {
    /// Detect the driver mode from the program name (argv[0]).
    pub fn from_argv0(name: &str) -> Self {
        // Strip path prefix.
        let basename = std::path::Path::new(name)
            .file_name()
            .and_then(|s| s.to_str())
            .unwrap_or(name);

        match basename {
            "clang++" | "clang++-" | "clang-c++" => Self::ClangXX,
            "clang-cl" => Self::ClangCL,
            "cc1" => Self::CC1,
            "cc1plus" => Self::CC1Plus,
            "clang-cpp" | "clang-cpp-" => Self::ClangCPP,
            "clang" | "clang-" => Self::Clang,
            _ => {
                // Check prefixes for versioned executables like clang-18, clang++-18.
                if basename.starts_with("clang++") {
                    Self::ClangXX
                } else if basename.starts_with("clang-cpp") {
                    Self::ClangCPP
                } else if basename.starts_with("clang-cl") {
                    Self::ClangCL
                } else if basename.starts_with("cc1plus") {
                    Self::CC1Plus
                } else if basename.starts_with("cc1") {
                    Self::CC1
                } else if basename.starts_with("clang") {
                    Self::Clang
                } else {
                    Self::Unknown
                }
            }
        }
    }

    /// Get the default input language for this mode.
    pub fn default_language(&self) -> InputLanguage {
        match self {
            Self::Clang | Self::CC1 | Self::ClangCPP => InputLanguage::C,
            Self::ClangXX | Self::CC1Plus => InputLanguage::CXX,
            Self::ClangCL => InputLanguage::C,
            Self::Unknown => InputLanguage::C,
        }
    }

    /// Whether this mode is a C++ compiler.
    pub fn is_cxx(&self) -> bool {
        matches!(self, Self::ClangXX | Self::CC1Plus)
    }

    /// Get the driver name for display.
    pub fn display_name(&self) -> &'static str {
        match self {
            Self::Clang => "clang",
            Self::ClangXX => "clang++",
            Self::ClangCL => "clang-cl",
            Self::CC1 => "cc1",
            Self::CC1Plus => "cc1plus",
            Self::ClangCPP => "clang-cpp",
            Self::Unknown => "clang",
        }
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// Response file expansion
// ═══════════════════════════════════════════════════════════════════════════════

/// Expand response files in the argument list.
///
/// A response file is specified with `@filename` on the command line.
/// Its contents are read and each line (excluding comments starting with `#`)
/// is expanded as a separate argument.
pub fn expand_response_files(args: &[String]) -> Vec<String> {
    let mut result = Vec::new();
    for arg in args {
        if arg.starts_with('@') && arg.len() > 1 {
            let filename = &arg[1..];
            match fs::read_to_string(filename) {
                Ok(contents) => {
                    for line in contents.lines() {
                        let trimmed = line.trim();
                        if !trimmed.is_empty() && !trimmed.starts_with('#') {
                            result.push(trimmed.to_string());
                        }
                    }
                }
                Err(e) => {
                    eprintln!(
                        "clang: error: unable to read response file '{}': {}",
                        filename, e
                    );
                }
            }
        } else {
            result.push(arg.clone());
        }
    }
    result
}

// ═══════════════════════════════════════════════════════════════════════════════
// Version and help printing
// ═══════════════════════════════════════════════════════════════════════════════

/// Print the Clang version string.
///
/// Example output:
/// ```text
/// clang version 18.0.0 (based on LLVM-native)
/// Target: x86_64-unknown-linux-gnu
/// Thread model: posix
/// ```
pub fn print_version(driver_mode: DriverMode) {
    let name = driver_mode.display_name();
    println!("{} version 18.0.0 (based on LLVM-native)", name);
    println!("Target: x86_64-unknown-linux-gnu");
    println!("Thread model: posix");
}

/// Print a detailed help message with all supported flags.
pub fn print_help(driver_mode: DriverMode) {
    let name = driver_mode.display_name();
    println!("OVERVIEW: {} C/C++ compiler", name);
    println!();
    println!("USAGE: {} [options] file...", name);
    println!();
    println!("OPTIONS:");
    println!();

    // ── Output phase selection ──────────────────────────────────────────
    println!("  -E                    Preprocess only; do not compile, assemble, or link.");
    println!("  -S                    Compile only; do not assemble or link.");
    println!("  -c                    Compile and assemble, but do not link.");
    println!("  -fsyntax-only         Run the preprocessor, parser and semantic analysis.");
    println!("  -emit-llvm            Emit LLVM IR (text) to the output file.");
    println!("  -emit-llvm-bc         Emit LLVM bitcode to the output file.");
    println!("  -dump-ast             Dump the AST to stdout.");
    println!("  -dump-tokens          Dump tokens to stdout.");
    println!();

    // ── Output files ────────────────────────────────────────────────────
    println!("  -o <file>             Write output to <file>.");
    println!();

    // ── Language ────────────────────────────────────────────────────────
    println!("  -std=<standard>       Language standard to compile for.");
    println!("                         c89, c99, c11, c17, c23,");
    println!("                         gnu89, gnu99, gnu11, gnu17");
    println!("  -ansi                 Equivalent to -std=c89.");
    println!("  -x <language>         Treat subsequent input files as type <language>.");
    println!("                         c, c++, objective-c, assembler");
    println!();

    // ── Target ──────────────────────────────────────────────────────────
    println!("  -target <triple>      Set the target triple.");
    println!("  -march=<cpu>          Set the target CPU.");
    println!();

    // ── Optimization ────────────────────────────────────────────────────
    println!("  -O0                   No optimization.");
    println!("  -O1                   Moderate optimization.");
    println!("  -O2                   Aggressive optimization.");
    println!("  -O3                   Maximum optimization.");
    println!("  -Os                   Optimize for size.");
    println!("  -Oz                   Aggressively optimize for size.");
    println!("  -g                    Generate debug information.");
    println!();

    // ── Preprocessor ────────────────────────────────────────────────────
    println!("  -I<dir>               Add directory to include search path.");
    println!("  -D<macro>[=<value>]   Define a preprocessor macro.");
    println!("  -U<macro>             Undefine a preprocessor macro.");
    println!("  -nostdinc             Do not search standard system include dirs.");
    println!("  -include <file>       Include file before parsing.");
    println!();

    // ── Warnings ────────────────────────────────────────────────────────
    println!("  -w                    Suppress all warnings.");
    println!("  -Wall                 Enable most common warnings.");
    println!("  -Wextra               Enable extra warnings.");
    println!("  -Wpedantic            Issue warnings for non-standard code.");
    println!("  -Werror               Treat warnings as errors.");
    println!("  -Wno-<warning>        Disable specific warning.");
    println!("  -W<warning>           Enable specific warning.");
    println!();

    // ── Code generation ─────────────────────────────────────────────────
    println!("  -fPIC                 Generate position-independent code.");
    println!("  -fPIE                 Generate position-independent executable.");
    println!("  -fstack-protector     Enable stack protection.");
    println!("  -fsanitize=<type>     Enable sanitizer (address, undefined, etc.).");
    println!();

    // ── Miscellaneous ───────────────────────────────────────────────────
    println!("  -v                    Verbose mode.");
    println!("  --version             Print version information.");
    println!("  --help                Print this help message.");
    println!("  -print-resource-dir   Print the resource directory path.");
    println!("  -print-search-dirs    Print the search paths.");
    println!("  -dumpmachine          Print the target triple.");
}

/// Print the resource directory path.
pub fn print_resource_dir() {
    // In a real Clang, this is derived from the binary's location.
    // Here we use a reasonable default.
    println!("/usr/lib/clang/18");
}

/// Print the include and library search paths.
pub fn print_search_dirs() {
    println!("programs: =/usr/bin");
    println!("libraries: =/usr/lib/clang/18:/usr/lib");
    println!("includes: =/usr/lib/clang/18/include:/usr/include");
}

/// Print the target triple.
pub fn print_target_triple(triple: &str) {
    println!("{}", triple);
}

// ═══════════════════════════════════════════════════════════════════════════════
// Main entry point — clang_main()
// ═══════════════════════════════════════════════════════════════════════════════

/// Main entry point for the Clang C/C++ frontend.
///
/// Parses command-line arguments, detects the driver mode, and runs the
/// appropriate compilation pipeline.
///
/// Returns an exit code (0 for success, 1 for errors).
pub fn clang_main(args: &[String]) -> i32 {
    // Detect driver mode from argv[0].
    let driver_mode = if args.is_empty() {
        DriverMode::Clang
    } else {
        DriverMode::from_argv0(&args[0])
    };

    // Expand response files.
    let expanded = expand_response_files(args);

    // Check for special flags that exit immediately.
    for arg in &expanded {
        match arg.as_str() {
            "--version" | "-version" => {
                print_version(driver_mode);
                return 0;
            }
            "--help" | "-help" => {
                print_help(driver_mode);
                return 0;
            }
            "-print-resource-dir" => {
                print_resource_dir();
                return 0;
            }
            "-print-search-dirs" => {
                print_search_dirs();
                return 0;
            }
            _ => {}
        }
    }

    // Parse the compiler invocation.
    let invocation = CompilerInvocation::from_args(&expanded);

    // Handle dumps that were picked up by the invocation parser.
    if invocation.opts.print_version {
        print_version(driver_mode);
        return 0;
    }
    if invocation.opts.print_help {
        print_help(driver_mode);
        return 0;
    }
    if invocation.opts.print_resource_dir {
        print_resource_dir();
        return 0;
    }
    if invocation.opts.print_search_dirs {
        print_search_dirs();
        return 0;
    }
    if invocation.opts.print_target_triple {
        print_target_triple(&invocation.opts.target_triple);
        return 0;
    }

    // If no input files, check if we should print usage.
    if invocation.opts.input_files.is_empty() {
        eprintln!("clang: error: no input files");
        return 1;
    }

    // Create the compiler instance.
    let mut compiler = CompilerInstance::new(invocation);

    // Load input files.
    for input_file in &compiler.opts.input_files.clone() {
        if let Err(e) = compiler.source_manager.load_file(&input_file) {
            eprintln!("clang: error: {}", e);
            return 1;
        }
    }

    // Create the frontend action.
    let action_kind = compiler.opts.action;
    let mut action = FrontendAction::for_kind(action_kind);

    // Begin source file.
    if let Err(errs) = action.begin_source_file(&mut compiler) {
        for err in &errs {
            eprintln!("clang: error: {}", err);
        }
        return 1;
    }

    // Execute the action.
    if let Err(errs) = action.execute() {
        for err in &errs {
            eprintln!("clang: error: {}", err);
        }
        return 1;
    }

    // Check for errors.
    if compiler.options().preprocess_only {
        if let Some(output) = action.get_output() {
            print!("{}", output);
        }
    }

    // Write output if applicable.
    if let Some(output) = action.get_output() {
        let output_path = compiler.opts.output_file.as_ref();
        if let Some(path) = output_path {
            if let Err(e) = fs::write(path, &output) {
                eprintln!(
                    "clang: error: cannot write output to '{}': {}",
                    path.display(),
                    e
                );
                return 1;
            }
        } else {
            print!("{}", output);
        }
    }

    // Finish.
    let _ = action.end_source_file();

    0
}

/// Convenience function to run clang_main with string arguments.
pub fn run_clang<I, S>(args: I) -> i32
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
{
    let args: Vec<String> = args.into_iter().map(|s| s.as_ref().to_string()).collect();
    let code = clang_main(&args);
    code
}

// ═══════════════════════════════════════════════════════════════════════════════
// Tool entry points
// ═══════════════════════════════════════════════════════════════════════════════

/// Entry point for the `cc1` tool (C compiler frontend).
///
/// This is called by the Clang driver after it has determined the target
/// and options, and it handles the actual compilation phases.
pub fn cc1_main(args: &[String]) -> i32 {
    clang_main(args)
}

/// Entry point for the `cc1plus` tool (C++ compiler frontend).
///
/// Same as `cc1` but for C++ compilation.
pub fn cc1plus_main(args: &[String]) -> i32 {
    clang_main(args)
}

/// Entry point for the `clang` driver (C compiler).
pub fn clang_driver_main(args: &[String]) -> i32 {
    let mut expanded = expand_response_files(args);
    if expanded.len() > 1 {
        expanded[0] = "clang".to_string();
    }
    clang_main(&expanded)
}

/// Entry point for the `clang++` driver (C++ compiler).
pub fn clangxx_driver_main(args: &[String]) -> i32 {
    let mut expanded = expand_response_files(args);
    if expanded.len() > 1 {
        expanded[0] = "clang++".to_string();
    }
    clang_main(&expanded)
}

/// Entry point for the `clang-cl` driver (MSVC-compatible).
pub fn clang_cl_driver_main(args: &[String]) -> i32 {
    let mut expanded = expand_response_files(args);
    if expanded.len() > 1 {
        expanded[0] = "clang-cl".to_string();
    }
    clang_main(&expanded)
}

// ═══════════════════════════════════════════════════════════════════════════════
// Legacy driver integration
// ═══════════════════════════════════════════════════════════════════════════════

/// Compile a C source file using the legacy `ClangDriver` interface.
///
/// This uses the simpler `ClangDriver` struct (from `driver.rs`) for
/// backward compatibility.
pub fn compile_legacy(source: &str, opts: ClangOptions) -> Result<Vec<u8>, Vec<String>> {
    let mut driver = ClangDriver::new(opts);
    match driver.compile_string(source) {
        Ok(_module) => {
            // In a real implementation, this would emit object bytes.
            Ok(Vec::new())
        }
        Err(errs) => Err(errs),
    }
}

/// Compile a C source file to assembly using the legacy interface.
pub fn compile_to_assembly_legacy(source: &str, opts: ClangOptions) -> Result<String, Vec<String>> {
    let mut driver = ClangDriver::new(opts);
    driver.compile_to_assembly(source)
}

/// Compile C source to LLVM IR using the new pipeline interface.
pub fn compile_to_llvm_ir(source: &str, triple: &str) -> Result<String, Vec<String>> {
    compile_to_ir(source, triple)
}

/// Compile C source to object bytes using the new pipeline interface.
pub fn compile_to_object_bytes(source: &str, triple: &str) -> Result<Vec<u8>, Vec<String>> {
    compile_to_object(source, triple)
}

// ═══════════════════════════════════════════════════════════════════════════════
// Quick compile helpers for testing
// ═══════════════════════════════════════════════════════════════════════════════

/// Quick compile: compile a C source string and return the LLVM module.
///
/// Used primarily in tests and REPL environments.
pub fn quick_compile(source: &str, triple: &str) -> Result<(), Vec<String>> {
    let opts = CompilerOptions {
        target_triple: triple.to_string(),
        action: FrontendActionKind::EmitObj,
        syntax_only: true,
        ..CompilerOptions::default()
    };

    let inv = CompilerInvocation {
        opts,
        args: vec!["clang".to_string()],
        program_name: "clang".to_string(),
    };

    let mut compiler = CompilerInstance::new(inv);
    let _fid = compiler
        .source_manager
        .load_virtual_file("<input>", source.to_string())
        .map_err(|e| vec![e])?;

    let tokens = super::lexer::tokenize(source, compiler.opts.standard);
    let mut parser = super::parser::Parser::new(&tokens, compiler.opts.standard);
    let tu = parser.parse().map_err(|e| {
        e.into_iter()
            .map(|err| format!("parse: {}", err))
            .collect::<Vec<_>>()
    })?;

    let mut sema = super::sema::Sema::new(compiler.opts.standard);
    sema.analyze(&tu).map_err(|e| {
        e.iter()
            .map(|err| format!("sema: {}", err))
            .collect::<Vec<_>>()
    })?;
    if sema.has_errors() {
        return Err(sema.errors.clone());
    }

    Ok(())
}

// ═══════════════════════════════════════════════════════════════════════════════
// Extended main entry — full compilation orchestration
// ═══════════════════════════════════════════════════════════════════════════════

/// Driver job for a single compilation.
///
/// Each job represents one invocation of the compiler frontend (compile
/// one source file to one object file). The driver orchestrates multiple
/// jobs for multi-file compilations.
#[derive(Debug, Clone)]
pub struct DriverJob {
    /// The source file to compile.
    pub source_file: PathBuf,
    /// The output file (object file).
    pub output_file: PathBuf,
    /// The compiler options for this job.
    pub options: CompilerOptions,
    /// Whether this job is a header unit (for C++ modules).
    pub is_header_unit: bool,
    /// Whether to run the preprocessor only.
    pub preprocess_only: bool,
    /// Whether to save intermediate temporary files.
    pub save_temps: bool,
    /// Temporary file prefix for save-temps.
    pub temp_prefix: Option<String>,
}

impl DriverJob {
    /// Create a new compilation job.
    pub fn new(source: PathBuf, output: PathBuf, opts: CompilerOptions) -> Self {
        Self {
            source_file: source,
            output_file: output,
            options: opts,
            is_header_unit: false,
            preprocess_only: false,
            save_temps: false,
            temp_prefix: None,
        }
    }

    /// Create a preprocess-only job.
    pub fn preprocess(source: PathBuf, output: PathBuf, opts: CompilerOptions) -> Self {
        Self {
            source_file: source,
            output_file: output,
            options: opts,
            is_header_unit: false,
            preprocess_only: true,
            save_temps: false,
            temp_prefix: None,
        }
    }

    /// Enable saving temporary intermediate files.
    pub fn with_save_temps(mut self, prefix: &str) -> Self {
        self.save_temps = true;
        self.temp_prefix = Some(prefix.to_string());
        self
    }
}

/// A list of compilation jobs and an optional link step.
#[derive(Debug)]
pub struct DriverJobList {
    /// The jobs to execute.
    pub jobs: Vec<DriverJob>,
    /// Whether to link after compilation.
    pub link: bool,
    /// The output file for linking (executable or shared library).
    pub link_output: Option<PathBuf>,
    /// Additional linker arguments.
    pub linker_args: Vec<String>,
    /// Whether to create a shared library.
    pub shared: bool,
    /// Statistics enabled.
    pub stats: bool,
    /// Time compilation enabled.
    pub time_compilation: bool,
}

impl DriverJobList {
    /// Create an empty job list.
    pub fn new() -> Self {
        Self {
            jobs: Vec::new(),
            link: false,
            link_output: None,
            linker_args: Vec::new(),
            shared: false,
            stats: false,
            time_compilation: false,
        }
    }

    /// Add a compilation job.
    pub fn add_job(&mut self, job: DriverJob) {
        self.jobs.push(job);
    }

    /// Set linker output.
    pub fn set_link_output(&mut self, output: PathBuf) {
        self.link_output = Some(output);
        self.link = true;
    }

    /// Set shared library mode.
    pub fn set_shared(&mut self, shared: bool) {
        self.shared = shared;
    }

    /// Build driver jobs for all input files.
    ///
    /// Given the compiler options, creates one job per input file
    /// with appropriate output file names.
    pub fn build_jobs(opts: &CompilerOptions) -> Self {
        let mut job_list = Self::new();
        job_list.stats = opts.stats;
        job_list.time_compilation = opts.verbose;

        if opts.input_files.is_empty() {
            return job_list;
        }

        let is_single_file = opts.input_files.len() == 1;
        let output = opts.output_file.clone();

        for input in &opts.input_files {
            // Determine the output file for this job.
            let obj_output = if is_single_file {
                // Single file: use the user-specified output or derive from input.
                output.clone().unwrap_or_else(|| {
                    let mut p = input.clone();
                    p.set_extension("o");
                    p
                })
            } else {
                // Multiple files: derive object file from each input.
                let mut p = input.clone();
                p.set_extension("o");
                p
            };

            let job = DriverJob::new(input.clone(), obj_output, opts.clone());

            // Check save-temps flag.
            let job = if opts.asm_output.is_some()
                || opts.emit_llvm
                || opts.emit_bc
                || opts.preprocess_only
            {
                // Save intermediate files.
                let stem = input
                    .file_stem()
                    .and_then(|s| s.to_str())
                    .unwrap_or("output");
                job.with_save_temps(stem)
            } else {
                job
            };

            job_list.add_job(job);
        }

        // Determine link output.
        if opts.obj_output.is_none()
            && opts.asm_output.is_none()
            && !opts.emit_llvm
            && !opts.emit_bc
            && !opts.preprocess_only
            && !opts.syntax_only
        {
            let link_out = output.unwrap_or_else(|| PathBuf::from("a.out"));
            job_list.set_link_output(link_out);
        }

        job_list
    }

    /// Execute all compilation jobs.
    pub fn execute_all(&self) -> Result<Vec<Vec<u8>>, Vec<String>> {
        let mut results: Vec<Vec<u8>> = Vec::new();
        let mut all_errors: Vec<String> = Vec::new();

        for job in &self.jobs {
            match execute_driver_job(job) {
                Ok(object_bytes) => {
                    results.push(object_bytes);
                }
                Err(errors) => {
                    all_errors.extend(errors);
                }
            }
        }

        if all_errors.is_empty() {
            Ok(results)
        } else {
            Err(all_errors)
        }
    }

    /// Check if there are any jobs.
    pub fn is_empty(&self) -> bool {
        self.jobs.is_empty()
    }

    /// Get the number of jobs.
    pub fn len(&self) -> usize {
        self.jobs.len()
    }
}

impl Default for DriverJobList {
    fn default() -> Self {
        Self::new()
    }
}

/// Execute a single driver job: compile one source file to object bytes.
fn execute_driver_job(job: &DriverJob) -> Result<Vec<u8>, Vec<String>> {
    // Read the source file.
    let source = std::fs::read_to_string(&job.source_file)
        .map_err(|e| vec![format!("cannot read {}: {}", job.source_file.display(), e)])?;

    // Save preprocessed output if requested.
    if job.preprocess_only || (job.save_temps && job.options.preprocess_only) {
        let pp_output = run_preprocess_job(&source, &job.options)?;
        if let Some(ref prefix) = job.temp_prefix {
            let pp_file = format!("{}.i", prefix);
            std::fs::write(&pp_file, &pp_output)
                .map_err(|e| vec![format!("cannot write {}: {}", pp_file, e)])?;
        }
        if job.preprocess_only {
            return Ok(Vec::new());
        }
    }

    // Run the full compile pipeline.
    let tokens = super::lexer::tokenize(&source, job.options.standard);
    let mut parser = super::parser::Parser::new(&tokens, job.options.standard);
    let tu = parser.parse().map_err(|e| {
        e.into_iter()
            .map(|err| format!("parse error: {}", err))
            .collect::<Vec<_>>()
    })?;

    let mut sema = super::sema::Sema::new(job.options.standard);
    sema.analyze(&tu).map_err(|e| {
        e.iter()
            .map(|err| format!("sema error: {}", err))
            .collect::<Vec<_>>()
    })?;
    if sema.has_errors() {
        return Err(sema.errors.clone());
    }

    // Code generation.
    let triple = &job.options.target_triple;
    let mut cg = super::codegen::ClangCodeGen::new(
        job.source_file
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("input"),
        triple,
    );
    cg.compile(&tu).map_err(|e| {
        e.iter()
            .map(|err| format!("codegen error: {}", err))
            .collect::<Vec<_>>()
    })?;

    // Emit assembly if requested.
    if job.options.asm_output.is_some() {
        let asm = emit_assembly_text(&cg.module, &job.options);
        if let Some(ref prefix) = job.temp_prefix {
            let asm_file = format!("{}.s", prefix);
            std::fs::write(&asm_file, &asm)
                .map_err(|e| vec![format!("cannot write {}: {}", asm_file, e)])?;
        }
        // Write assembly to output file.
        std::fs::write(&job.output_file, &asm)
            .map_err(|e| vec![format!("cannot write {}: {}", job.output_file.display(), e)])?;
    }

    // Emit LLVM IR if requested.
    if job.options.emit_llvm {
        let ir = emit_llvm_ir_text(&cg.module, triple);
        if let Some(ref prefix) = job.temp_prefix {
            let ir_file = format!("{}.ll", prefix);
            std::fs::write(&ir_file, &ir)
                .map_err(|e| vec![format!("cannot write {}: {}", ir_file, e)])?;
        }
        std::fs::write(&job.output_file, &ir)
            .map_err(|e| vec![format!("cannot write {}: {}", job.output_file.display(), e)])?;
    }

    // Emit bitcode if requested.
    if job.options.emit_bc {
        let bc = emit_bitcode_bytes(&cg.module);
        if let Some(ref prefix) = job.temp_prefix {
            let bc_file = format!("{}.bc", prefix);
            std::fs::write(&bc_file, &bc)
                .map_err(|e| vec![format!("cannot write {}: {}", bc_file, e)])?;
        }
        std::fs::write(&job.output_file, &bc)
            .map_err(|e| vec![format!("cannot write {}: {}", job.output_file.display(), e)])?;
    }

    // Emit object file.
    let object_bytes = emit_object_bytes(&cg.module, &job.options);
    if job.options.asm_output.is_none() && !job.options.emit_llvm && !job.options.emit_bc {
        std::fs::write(&job.output_file, &object_bytes)
            .map_err(|e| vec![format!("cannot write {}: {}", job.output_file.display(), e)])?;
    }

    Ok(object_bytes)
}

/// Run only the preprocessor on source and return preprocessed text.
fn run_preprocess_job(source: &str, _opts: &CompilerOptions) -> Result<String, Vec<String>> {
    // In a real implementation, this runs the full preprocessor.
    // For now, return the source with only basic comment removal.
    let mut output = String::new();
    let mut in_block_comment = false;
    let chars: Vec<char> = source.chars().collect();
    let mut i = 0;
    while i < chars.len() {
        if in_block_comment {
            if chars[i] == '*' && i + 1 < chars.len() && chars[i + 1] == '/' {
                in_block_comment = false;
                i += 2;
                continue;
            }
            i += 1;
            continue;
        }

        if chars[i] == '/' && i + 1 < chars.len() && chars[i + 1] == '*' {
            in_block_comment = true;
            i += 2;
            continue;
        }

        if chars[i] == '/' && i + 1 < chars.len() && chars[i + 1] == '/' {
            // Line comment; skip to end of line.
            while i < chars.len() && chars[i] != '\n' {
                i += 1;
            }
            if i < chars.len() {
                output.push('\n');
                i += 1;
            }
            continue;
        }

        output.push(chars[i]);
        i += 1;
    }

    Ok(output)
}

/// Emit assembly text from a module.
fn emit_assembly_text(module: &Module, _opts: &CompilerOptions) -> String {
    let mut asm = String::new();
    asm.push_str("\t.text\n");
    asm.push_str(&format!("\t.file\t\"{}\"\n", module.name));
    asm.push_str("\n");
    for func in &module.functions {
        let func = func.borrow();
        asm.push_str(&format!("\t.globl\t{}\n", func.name));
        asm.push_str(&format!("\t.type\t{},@function\n", func.name));
        asm.push_str(&format!("{}:\n", func.name));
        for bb in &func.blocks {
            let bb = bb.borrow();
            if !bb.name.is_empty() {
                asm.push_str(&format!(".L{}:\n", bb.name));
            }
            for inst in &bb.instructions {
                let inst = inst.borrow();
                asm.push_str(&format!("\t; {:?}\n", inst.opcode));
            }
        }
        asm.push_str(&format!("\t.size\t{}, .-{}\n\n", func.name, func.name));
    }
    asm
}

/// Emit LLVM IR text from a module.
fn emit_llvm_ir_text(module: &Module, triple: &str) -> String {
    let mut ir = String::new();
    ir.push_str(&format!("; ModuleID = '{}'\n", module.name));
    ir.push_str(&format!("target triple = \"{}\"\n", triple));
    ir.push_str(&format!("target datalayout = \"e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-f80:128-n8:16:32:64-S128\"\n"));
    for func in &module.functions {
        let func = func.borrow();
        ir.push_str(&format!(
            "define {} @{} (",
            func.return_type
                .as_ref()
                .map(|t| t.to_string())
                .unwrap_or_else(|| "void".to_string()),
            func.name
        ));
        for (i, param) in func.params.iter().enumerate() {
            if i > 0 {
                ir.push_str(", ");
            }
            ir.push_str(&format!("{} %{}", param, i));
        }
        ir.push_str(") {\n");
        for bb in &func.blocks {
            let bb = bb.borrow();
            ir.push_str(&format!(
                "{}:\n",
                if bb.name.is_empty() {
                    "entry"
                } else {
                    &bb.name
                }
            ));
            for inst in &bb.instructions {
                let inst = inst.borrow();
                if let Some(ref r) = inst.result {
                    ir.push_str(&format!("  %{} = {:?} ", r, inst.opcode));
                } else {
                    ir.push_str(&format!("  {:?}", inst.opcode));
                }
                ir.push_str("\n");
            }
        }
        ir.push_str("}\n\n");
    }
    ir
}

/// Emit bitcode bytes from a module.
fn emit_bitcode_bytes(_module: &Module) -> Vec<u8> {
    // LLVM bitcode magic and placeholder content.
    let mut bc: Vec<u8> = Vec::new();
    bc.extend_from_slice(&[0xDE, 0xC0, 0x17, 0x0B]);
    bc.extend_from_slice(&[0; 64]);
    bc
}

/// Emit object bytes from a module.
fn emit_object_bytes(_module: &Module, opts: &CompilerOptions) -> Vec<u8> {
    let mut obj: Vec<u8> = Vec::new();
    if opts.target_triple.contains("x86_64") || opts.target_triple.contains("aarch64") {
        // Minimal ELF64 header.
        obj.extend_from_slice(&[0x7f, b'E', b'L', b'F']);
        obj.push(2);
        obj.push(1);
        obj.push(1);
        obj.push(0);
        obj.push(0);
        obj.extend_from_slice(&[0; 7]);
        obj.extend_from_slice(&[1, 0]); // ET_REL
        if opts.target_triple.contains("x86_64") {
            obj.extend_from_slice(&[0x3e, 0]); // x86_64
        } else {
            obj.extend_from_slice(&[0xB7, 0]); // aarch64
        }
        obj.extend_from_slice(&[1, 0, 0, 0]);
        obj.extend_from_slice(&[0; 8 + 8 + 4]);
        obj.extend_from_slice(&[64, 0]);
        obj.extend_from_slice(&[56, 0]);
        obj.extend_from_slice(&[0, 0]);
        obj.extend_from_slice(&[64, 0]);
        obj.extend_from_slice(&[0, 0]);
        obj.extend_from_slice(&[0, 0]);
    } else {
        obj.extend_from_slice(&[0; 64]);
    }
    obj
}

// ═══════════════════════════════════════════════════════════════════════════════
// Compiler execution with exit code and diagnostic summary
// ═══════════════════════════════════════════════════════════════════════════════

/// Result of executing a compilation.
#[derive(Debug)]
pub struct CompilationResult {
    /// The exit code (0 = success, 1 = errors, 2 = fatal).
    pub exit_code: i32,
    /// Number of errors produced.
    pub error_count: usize,
    /// Number of warnings produced.
    pub warning_count: usize,
    /// The output files generated.
    pub output_files: Vec<PathBuf>,
    /// Diagnostic summary text.
    pub diagnostic_summary: String,
    /// Compile time breakdown (if -ftime-report).
    pub time_breakdown: Option<CompileTimeBreakdown>,
    /// Compilation statistics (if -stats).
    pub statistics: Option<CompilationStatistics>,
}

/// Breakdown of time spent in each compilation phase.
#[derive(Debug, Clone)]
pub struct CompileTimeBreakdown {
    /// Time spent in lexing.
    pub lex_time_ms: u64,
    /// Time spent in preprocessing.
    pub preprocess_time_ms: u64,
    /// Time spent in parsing.
    pub parse_time_ms: u64,
    /// Time spent in semantic analysis.
    pub sema_time_ms: u64,
    /// Time spent in code generation.
    pub codegen_time_ms: u64,
    /// Time spent in optimization.
    pub opt_time_ms: u64,
    /// Time spent in emission.
    pub emit_time_ms: u64,
    /// Total wall-clock time.
    pub total_time_ms: u64,
}

impl CompileTimeBreakdown {
    /// Create a new empty breakdown.
    pub fn new() -> Self {
        Self {
            lex_time_ms: 0,
            preprocess_time_ms: 0,
            parse_time_ms: 0,
            sema_time_ms: 0,
            codegen_time_ms: 0,
            opt_time_ms: 0,
            emit_time_ms: 0,
            total_time_ms: 0,
        }
    }

    /// Format as a display string.
    pub fn format(&self) -> String {
        let mut out = String::new();
        out.push_str("=== Compile Time Breakdown ===\n");
        if self.lex_time_ms > 0 {
            out.push_str(&format!("  Lexing:        {:>6} ms\n", self.lex_time_ms));
        }
        if self.preprocess_time_ms > 0 {
            out.push_str(&format!(
                "  Preprocessing: {:>6} ms\n",
                self.preprocess_time_ms
            ));
        }
        out.push_str(&format!("  Parsing:       {:>6} ms\n", self.parse_time_ms));
        out.push_str(&format!("  Sema:          {:>6} ms\n", self.sema_time_ms));
        out.push_str(&format!(
            "  Codegen:       {:>6} ms\n",
            self.codegen_time_ms
        ));
        if self.opt_time_ms > 0 {
            out.push_str(&format!("  Optimization:  {:>6} ms\n", self.opt_time_ms));
        }
        out.push_str(&format!("  Emission:      {:>6} ms\n", self.emit_time_ms));
        out.push_str(&format!("  Total:         {:>6} ms\n", self.total_time_ms));
        out
    }
}

impl Default for CompileTimeBreakdown {
    fn default() -> Self {
        Self::new()
    }
}

/// Compilation statistics.
#[derive(Debug, Clone)]
pub struct CompilationStatistics {
    /// Number of source files processed.
    pub num_source_files: usize,
    /// Number of lines processed.
    pub num_lines: usize,
    /// Number of tokens produced.
    pub num_tokens: usize,
    /// Number of AST nodes created.
    pub num_ast_nodes: usize,
    /// Number of LLVM IR instructions generated.
    pub num_ir_instructions: usize,
    /// Number of target machine instructions emitted.
    pub num_machine_instructions: usize,
    /// Number of bytes of object code emitted.
    pub num_object_bytes: usize,
    /// Peak memory usage in bytes.
    pub peak_memory_bytes: usize,
    /// Number of include files processed.
    pub num_includes: usize,
    /// Number of macro expansions.
    pub num_macro_expansions: usize,
}

impl CompilationStatistics {
    /// Create empty statistics.
    pub fn new() -> Self {
        Self {
            num_source_files: 0,
            num_lines: 0,
            num_tokens: 0,
            num_ast_nodes: 0,
            num_ir_instructions: 0,
            num_machine_instructions: 0,
            num_object_bytes: 0,
            peak_memory_bytes: 0,
            num_includes: 0,
            num_macro_expansions: 0,
        }
    }

    /// Format as a display string.
    pub fn format(&self) -> String {
        let mut out = String::new();
        out.push_str("=== Compilation Statistics ===\n");
        out.push_str(&format!(
            "  Source files:        {:>6}\n",
            self.num_source_files
        ));
        out.push_str(&format!("  Lines of code:       {:>6}\n", self.num_lines));
        out.push_str(&format!("  Tokens:              {:>6}\n", self.num_tokens));
        out.push_str(&format!(
            "  AST nodes:           {:>6}\n",
            self.num_ast_nodes
        ));
        out.push_str(&format!(
            "  IR instructions:     {:>6}\n",
            self.num_ir_instructions
        ));
        out.push_str(&format!(
            "  Machine instrs:      {:>6}\n",
            self.num_machine_instructions
        ));
        out.push_str(&format!(
            "  Object bytes:        {:>6}\n",
            self.num_object_bytes
        ));
        out.push_str(&format!(
            "  Includes:            {:>6}\n",
            self.num_includes
        ));
        out.push_str(&format!(
            "  Macro expansions:    {:>6}\n",
            self.num_macro_expansions
        ));
        out.push_str(&format!(
            "  Peak memory (KB):    {:>6}\n",
            self.peak_memory_bytes / 1024
        ));
        out
    }
}

impl Default for CompilationStatistics {
    fn default() -> Self {
        Self::new()
    }
}

/// Execute a full compilation from parsed command-line arguments.
///
/// This is the core compilation function that:
/// 1. Parses flags via CompilerInvocation
/// 2. Creates a CompilerInstance
/// 3. Builds driver jobs
/// 4. Executes all jobs
/// 5. Invokes the linker if needed
/// 6. Returns a CompilationResult with exit code and diagnostics
pub fn execute_compilation(inv: &CompilerInvocation) -> CompilationResult {
    let mut error_count: usize = 0;
    let mut warning_count: usize = 0;
    let mut output_files: Vec<PathBuf> = Vec::new();

    // Build driver jobs.
    let job_list = DriverJobList::build_jobs(&inv.opts);

    // If no input files, report error.
    if job_list.is_empty() && inv.opts.input_files.is_empty() {
        return CompilationResult {
            exit_code: 1,
            error_count: 1,
            warning_count: 0,
            output_files: Vec::new(),
            diagnostic_summary: "clang: error: no input files\n".to_string(),
            time_breakdown: None,
            statistics: None,
        };
    }

    // Execute all compilation jobs.
    match job_list.execute_all() {
        Ok(objects) => {
            for job in &job_list.jobs {
                output_files.push(job.output_file.clone());
            }

            // If linking is needed, invoke the linker.
            if job_list.link {
                if let Some(ref link_output) = job_list.link_output {
                    match invoke_linker(&objects, link_output, &inv.opts, job_list.shared) {
                        Ok(()) => {
                            output_files.push(link_output.clone());
                        }
                        Err(errs) => {
                            error_count += errs.len();
                            return CompilationResult {
                                exit_code: 1,
                                error_count,
                                warning_count,
                                output_files,
                                diagnostic_summary: format!("linker errors:\n{}", errs.join("\n")),
                                time_breakdown: None,
                                statistics: None,
                            };
                        }
                    }
                }
            }
        }
        Err(errors) => {
            error_count = errors.len();
            return CompilationResult {
                exit_code: 1,
                error_count,
                warning_count,
                output_files,
                diagnostic_summary: format!("compilation errors:\n{}", errors.join("\n")),
                time_breakdown: None,
                statistics: None,
            };
        }
    }

    // Build diagnostic summary.
    let mut summary = String::new();
    if error_count > 0 {
        summary.push_str(&format!("{} error(s) generated.\n", error_count));
    }
    if warning_count > 0 {
        summary.push_str(&format!("{} warning(s) generated.\n", warning_count));
    }

    // Time breakdown.
    let time_breakdown = if inv.opts.verbose {
        let mut tb = CompileTimeBreakdown::new();
        tb.total_time_ms = 1; // placeholder
        Some(tb)
    } else {
        None
    };

    // Statistics.
    let statistics = if inv.opts.stats {
        let mut stats = CompilationStatistics::new();
        stats.num_source_files = inv.opts.input_files.len();
        Some(stats)
    } else {
        None
    };

    CompilationResult {
        exit_code: if error_count > 0 { 1 } else { 0 },
        error_count,
        warning_count,
        output_files,
        diagnostic_summary: summary,
        time_breakdown,
        statistics,
    }
}

/// Invoke the linker to produce a final executable or shared library.
///
/// In a real implementation, this would invoke LLD (the LLVM linker)
/// or the system linker (ld, ld64, link.exe).
fn invoke_linker(
    object_bytes_list: &[Vec<u8>],
    output: &PathBuf,
    opts: &CompilerOptions,
    shared: bool,
) -> Result<(), Vec<String>> {
    // In a real implementation:
    // 1. Write object files to temp files
    // 2. Invoke the linker (LLD or system linker)
    // 3. Pass linker args from opts

    // For now, simulate linking by concatenating object bytes.
    if object_bytes_list.is_empty() {
        return Err(vec!["no object files to link".to_string()]);
    }

    // Create a temporary directory for object files.
    let tmp_dir = std::env::temp_dir().join(format!("clang-link-{}", std::process::id()));
    if let Err(e) = std::fs::create_dir_all(&tmp_dir) {
        return Err(vec![format!("cannot create temp dir: {}", e)]);
    }

    let mut obj_files: Vec<PathBuf> = Vec::new();
    for (i, obj) in object_bytes_list.iter().enumerate() {
        let obj_path = tmp_dir.join(format!("obj_{}.o", i));
        if let Err(e) = std::fs::write(&obj_path, obj) {
            return Err(vec![format!("cannot write temp object: {}", e)]);
        }
        obj_files.push(obj_path);
    }

    // Simulate linker output.
    let mut linked: Vec<u8> = Vec::new();

    // Write ELF header for executable.
    if opts.target_triple.contains("x86_64") {
        linked.extend_from_slice(&[0x7f, b'E', b'L', b'F']);
        linked.push(2);
        linked.push(1);
        linked.push(1);
        linked.push(0);
        linked.push(0);
        linked.extend_from_slice(&[0; 7]);
        linked.extend_from_slice(&[2, 0]); // ET_EXEC
        linked.extend_from_slice(&[0x3e, 0]); // x86_64
        linked.extend_from_slice(&[1, 0, 0, 0]);
        linked.extend_from_slice(&[0; 24]);
        linked.extend_from_slice(&[64, 0]);
        linked.extend_from_slice(&[56, 0]);
        linked.extend_from_slice(&[1, 0]); // 1 program header
        linked.extend_from_slice(&[64, 0]);
        linked.extend_from_slice(&[0, 0]);
        linked.extend_from_slice(&[0, 0]);

        // Program header (PT_LOAD).
        linked.extend_from_slice(&[1, 0, 0, 0]);
        linked.extend_from_slice(&[5, 0, 0, 0]); // PF_R | PF_X
        linked.extend_from_slice(&[0; 8]);
        linked.extend_from_slice(&[0; 8]);
        linked.extend_from_slice(&[0; 8]);
        linked.extend_from_slice(&[0; 8]);
        linked.extend_from_slice(&[0; 8]);
        linked.extend_from_slice(&[0x00, 0x10, 0, 0, 0, 0, 0, 0]);
    }

    // Append all object bytes.
    for obj in object_bytes_list {
        linked.extend_from_slice(obj);
    }

    // Write linked output.
    std::fs::write(output, &linked)
        .map_err(|e| vec![format!("cannot write {}: {}", output.display(), e)])?;

    // Clean up temp files.
    let _ = std::fs::remove_dir_all(&tmp_dir);

    Ok(())
}

/// Print a diagnostic summary with N errors and M warnings.
pub fn print_diagnostic_summary(error_count: usize, warning_count: usize) -> String {
    let mut summary = String::new();
    if error_count > 0 || warning_count > 0 {
        if error_count > 0 {
            summary.push_str(&format!(
                "{} error{}",
                error_count,
                if error_count == 1 { "" } else { "s" }
            ));
            if warning_count > 0 {
                summary.push_str(", ");
            }
        }
        if warning_count > 0 {
            summary.push_str(&format!(
                "{} warning{}",
                warning_count,
                if warning_count == 1 { "" } else { "s" }
            ));
        }
        summary.push_str(" generated.\n");
    }
    summary
}

/// Run the compiler with the given arguments and return the exit code.
///
/// This is the main entry point for programmatic use.
/// Returns 0 on success, 1 on errors, 2 on fatal errors.
pub fn run_compiler(args: &[String]) -> i32 {
    // Parse command-line arguments.
    let inv = CompilerInvocation::from_args_native(args.iter().map(|s| s.as_str()));

    // Execute compilation.
    let result = execute_compilation(&inv);

    // Print diagnostic summary.
    if !result.diagnostic_summary.is_empty() {
        eprint!("{}", result.diagnostic_summary);
    }

    // Print time breakdown if available.
    if let Some(ref tb) = result.time_breakdown {
        eprint!("{}", tb.format());
    }

    // Print statistics if available.
    if let Some(ref stats) = result.statistics {
        eprint!("{}", stats.format());
    }

    result.exit_code
}

impl CompilerInvocation {
    /// Create a CompilerInvocation from native string slices.
    ///
    /// This is the version used by the driver.
    pub fn from_args_native<'a, I>(args: I) -> Self
    where
        I: IntoIterator<Item = &'a str>,
    {
        let args_vec: Vec<String> = args.into_iter().map(|s| s.to_string()).collect();
        Self::from_args(args_vec.iter().map(|s| s.as_str()))
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// Compilation job runner — orchestrates multi-file compilation
// ═══════════════════════════════════════════════════════════════════════════════

/// A runner that executes compilation jobs sequentially or in parallel.
#[derive(Debug)]
pub struct CompilationJobRunner {
    /// The jobs to execute.
    pub jobs: DriverJobList,
    /// Number of parallel jobs (0 = serial).
    pub parallel_jobs: usize,
    /// Whether to keep going after errors.
    pub keep_going: bool,
    /// Whether to print commands as they execute.
    pub verbose: bool,
    /// Results of each job execution.
    pub results: Vec<JobResult>,
}

/// Result of executing a single compilation job.
#[derive(Debug, Clone)]
pub struct JobResult {
    /// The source file.
    pub source_file: PathBuf,
    /// The output file.
    pub output_file: PathBuf,
    /// Whether the job succeeded.
    pub succeeded: bool,
    /// Error messages if the job failed.
    pub errors: Vec<String>,
    /// Wall-clock time for the job.
    pub duration_ms: u64,
    /// Number of warnings produced.
    pub warning_count: usize,
}

impl JobResult {
    /// Create a successful result.
    pub fn success(source: PathBuf, output: PathBuf) -> Self {
        Self {
            source_file: source,
            output_file: output,
            succeeded: true,
            errors: Vec::new(),
            duration_ms: 0,
            warning_count: 0,
        }
    }

    /// Create a failed result.
    pub fn failure(source: PathBuf, output: PathBuf, errors: Vec<String>) -> Self {
        Self {
            source_file: source,
            output_file: output,
            succeeded: false,
            errors,
            duration_ms: 0,
            warning_count: 0,
        }
    }
}

impl CompilationJobRunner {
    /// Create a new job runner.
    pub fn new(jobs: DriverJobList) -> Self {
        Self {
            jobs,
            parallel_jobs: 0,
            keep_going: false,
            verbose: false,
            results: Vec::new(),
        }
    }

    /// Set the number of parallel jobs.
    pub fn with_parallel(mut self, n: usize) -> Self {
        self.parallel_jobs = n;
        self
    }

    /// Enable keep-going mode.
    pub fn with_keep_going(mut self) -> Self {
        self.keep_going = true;
        self
    }

    /// Enable verbose mode.
    pub fn with_verbose(mut self) -> Self {
        self.verbose = true;
        self
    }

    /// Run all jobs.
    pub fn run(&mut self) -> Result<(), Vec<String>> {
        self.results.clear();

        for job in &self.jobs.jobs {
            if self.verbose {
                eprintln!("Compiling {}...", job.source_file.display());
            }

            let start = std::time::Instant::now();
            match execute_driver_job(job) {
                Ok(_bytes) => {
                    let duration = start.elapsed().as_millis() as u64;
                    self.results.push(JobResult {
                        source_file: job.source_file.clone(),
                        output_file: job.output_file.clone(),
                        succeeded: true,
                        errors: Vec::new(),
                        duration_ms: duration,
                        warning_count: 0,
                    });
                    if self.verbose {
                        eprintln!("  -> {} ({:?})", job.output_file.display(), start.elapsed());
                    }
                }
                Err(errors) => {
                    let duration = start.elapsed().as_millis() as u64;
                    self.results.push(JobResult {
                        source_file: job.source_file.clone(),
                        output_file: job.output_file.clone(),
                        succeeded: false,
                        errors: errors.clone(),
                        duration_ms: duration,
                        warning_count: 0,
                    });
                    if !self.keep_going {
                        return Err(errors);
                    }
                }
            }
        }

        // Check if any job failed.
        let all_errors: Vec<String> = self
            .results
            .iter()
            .filter(|r| !r.succeeded)
            .flat_map(|r| r.errors.clone())
            .collect();

        if all_errors.is_empty() {
            Ok(())
        } else {
            Err(all_errors)
        }
    }

    /// Get a summary of job results.
    pub fn summary(&self) -> String {
        let succeeded = self.results.iter().filter(|r| r.succeeded).count();
        let failed = self.results.iter().filter(|r| !r.succeeded).count();
        let total_time: u64 = self.results.iter().map(|r| r.duration_ms).sum();

        format!(
            "{} job(s) succeeded, {} failed, {} total time: {} ms",
            succeeded,
            failed,
            self.results.len(),
            total_time
        )
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// File cache — compilation cache for incremental builds
// ═══════════════════════════════════════════════════════════════════════════════

/// A simple compilation cache that maps source hashes to cached outputs.
#[derive(Debug, Clone)]
pub struct FileCache {
    /// Cache entries keyed by source file path.
    entries: std::collections::HashMap<PathBuf, CacheEntry>,
    /// Whether the cache is enabled.
    enabled: bool,
}

/// A single cache entry.
#[derive(Debug, Clone)]
pub struct CacheEntry {
    /// Hash of the source content.
    pub source_hash: u64,
    /// Hash of compiler flags.
    pub flags_hash: u64,
    /// Cached object bytes.
    pub object_bytes: Vec<u8>,
    /// Timestamp when the entry was created.
    pub timestamp: u64,
    /// Whether this entry is still valid.
    pub valid: bool,
}

impl CacheEntry {
    /// Create a new cache entry.
    pub fn new(source_hash: u64, flags_hash: u64, object_bytes: Vec<u8>) -> Self {
        Self {
            source_hash,
            flags_hash,
            object_bytes,
            timestamp: 0,
            valid: true,
        }
    }

    /// Invalidate this cache entry.
    pub fn invalidate(&mut self) {
        self.valid = false;
    }
}

impl FileCache {
    /// Create a new file cache.
    pub fn new() -> Self {
        Self {
            entries: std::collections::HashMap::new(),
            enabled: true,
        }
    }

    /// Enable or disable the cache.
    pub fn set_enabled(&mut self, enabled: bool) {
        self.enabled = enabled;
    }

    /// Look up a cached result for a source file.
    pub fn lookup(&self, source: &Path, source_hash: u64, flags_hash: u64) -> Option<&CacheEntry> {
        if !self.enabled {
            return None;
        }
        self.entries.get(source).and_then(|entry| {
            if entry.valid && entry.source_hash == source_hash && entry.flags_hash == flags_hash {
                Some(entry)
            } else {
                None
            }
        })
    }

    /// Insert a result into the cache.
    pub fn insert(&mut self, source: &Path, entry: CacheEntry) {
        if self.enabled {
            self.entries.insert(source.to_path_buf(), entry);
        }
    }

    /// Invalidate a cache entry.
    pub fn invalidate(&mut self, source: &Path) {
        if let Some(entry) = self.entries.get_mut(source) {
            entry.invalidate();
        }
    }

    /// Clear all cache entries.
    pub fn clear(&mut self) {
        self.entries.clear();
    }

    /// Get the number of cached entries.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Check if the cache is empty.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// Compute a hash for compiler flags.
    pub fn compute_flags_hash(flags: &[String]) -> u64 {
        let mut hash: u64 = 5381;
        for flag in flags {
            for b in flag.bytes() {
                hash = hash.wrapping_mul(33).wrapping_add(b as u64);
            }
        }
        hash
    }
}

impl Default for FileCache {
    fn default() -> Self {
        Self::new()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// Compilation session — per-invocation compilation state
// ═══════════════════════════════════════════════════════════════════════════════

/// A compilation session represents one invocation of the compiler
/// with a set of source files and flags.
#[derive(Debug)]
pub struct CompilationSession {
    /// The compiler invocation.
    pub invocation: CompilerInvocation,
    /// The driver mode.
    pub driver_mode: DriverMode,
    /// Compilation jobs.
    pub jobs: DriverJobList,
    /// Whether the session has started.
    pub started: bool,
    /// Whether the session has completed.
    pub completed: bool,
    /// Error tracker.
    pub errors: super::clang_pipeline::ErrorTracker,
    /// Optional file cache.
    pub cache: Option<FileCache>,
}

impl CompilationSession {
    /// Create a new compilation session.
    pub fn new(args: &[String]) -> Self {
        let mode = DriverMode::from_argv0(&args.first().cloned().unwrap_or_default());
        let expanded = expand_response_files(args);
        let inv = CompilerInvocation::from_args_native(expanded.iter().map(|s| s.as_str()));
        let jobs = DriverJobList::build_jobs(&inv.opts);

        Self {
            invocation: inv,
            driver_mode: mode,
            jobs,
            started: false,
            completed: false,
            errors: super::clang_pipeline::ErrorTracker::new(),
            cache: None,
        }
    }

    /// Enable caching for this session.
    pub fn with_cache(mut self, cache: FileCache) -> Self {
        self.cache = Some(cache);
        self
    }

    /// Start the compilation session.
    pub fn start(&mut self) {
        self.started = true;
    }

    /// Run the compilation session.
    pub fn run(&mut self) -> CompilationResult {
        self.started = true;
        let result = execute_compilation(&self.invocation);
        self.completed = true;
        result
    }

    /// Get the driver mode.
    pub fn mode(&self) -> DriverMode {
        self.driver_mode
    }

    /// Check if this is a C++ compilation.
    pub fn is_cxx(&self) -> bool {
        self.driver_mode.is_cxx()
    }

    /// Get the number of source files.
    pub fn num_source_files(&self) -> usize {
        self.invocation.opts.input_files.len()
    }

    /// Check if the session has started.
    pub fn is_started(&self) -> bool {
        self.started
    }

    /// Check if the session has completed.
    pub fn is_completed(&self) -> bool {
        self.completed
    }

    /// Report an error.
    pub fn report_error(&mut self, msg: &str) {
        self.errors.error(msg);
    }

    /// Report a warning.
    pub fn report_warning(&mut self, msg: &str) {
        self.errors.warning(msg);
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// Build orchestrator — high-level build system interface
// ═══════════════════════════════════════════════════════════════════════════════

/// A high-level interface for orchestrating builds.
#[derive(Debug)]
pub struct BuildOrchestrator {
    /// Build sessions.
    pub sessions: Vec<CompilationSession>,
    /// Whether to continue on error.
    pub keep_going: bool,
    /// Build statistics.
    pub stats: BuildStats,
    /// Whether to print build progress.
    pub show_progress: bool,
}

/// Build statistics for an orchestrated build.
#[derive(Debug, Clone, Default)]
pub struct BuildStats {
    /// Total sessions.
    pub total_sessions: usize,
    /// Successful sessions.
    pub successful: usize,
    /// Failed sessions.
    pub failed: usize,
    /// Total source files processed.
    pub total_files: usize,
    /// Total errors across all sessions.
    pub total_errors: usize,
    /// Total warnings across all sessions.
    pub total_warnings: usize,
    /// Total wall-clock time in ms.
    pub total_time_ms: u64,
}

impl BuildOrchestrator {
    /// Create a new build orchestrator.
    pub fn new() -> Self {
        Self {
            sessions: Vec::new(),
            keep_going: false,
            stats: BuildStats::default(),
            show_progress: false,
        }
    }

    /// Add a compilation session.
    pub fn add_session(&mut self, session: CompilationSession) {
        self.sessions.push(session);
    }

    /// Run all sessions.
    pub fn build_all(&mut self) -> Result<(), Vec<String>> {
        let mut all_errors: Vec<String> = Vec::new();
        self.stats.total_sessions = self.sessions.len();

        for session in &mut self.sessions {
            self.stats.total_files += session.num_source_files();

            if self.show_progress {
                eprintln!(
                    "Building {} file(s) with mode {:?}...",
                    session.num_source_files(),
                    session.driver_mode
                );
            }

            let result = session.run();
            self.stats.total_errors += result.error_count;
            self.stats.total_warnings += result.warning_count;

            if result.exit_code != 0 {
                self.stats.failed += 1;
                all_errors.push(result.diagnostic_summary);
                if !self.keep_going {
                    return Err(all_errors);
                }
            } else {
                self.stats.successful += 1;
            }
        }

        if all_errors.is_empty() {
            Ok(())
        } else {
            Err(all_errors)
        }
    }

    /// Get a summary of the build.
    pub fn summary(&self) -> String {
        format!(
            "Build complete: {} succeeded, {} failed out of {} session(s) ({} files, {} errors, {} warnings)",
            self.stats.successful,
            self.stats.failed,
            self.stats.total_sessions,
            self.stats.total_files,
            self.stats.total_errors,
            self.stats.total_warnings
        )
    }
}

impl Default for BuildOrchestrator {
    fn default() -> Self {
        Self::new()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// Tests
// ═══════════════════════════════════════════════════════════════════════════════

#[cfg(test)]
mod tests {
    use super::*;

    // ── DriverMode ───────────────────────────────────────────────────────

    #[test]
    fn test_driver_mode_from_argv0_clang() {
        assert_eq!(DriverMode::from_argv0("clang"), DriverMode::Clang);
        assert_eq!(DriverMode::from_argv0("/usr/bin/clang"), DriverMode::Clang);
        assert_eq!(
            DriverMode::from_argv0("/usr/bin/clang-18"),
            DriverMode::Clang
        );
    }

    #[test]
    fn test_driver_mode_from_argv0_clangxx() {
        assert_eq!(DriverMode::from_argv0("clang++"), DriverMode::ClangXX);
        assert_eq!(
            DriverMode::from_argv0("/usr/bin/clang++"),
            DriverMode::ClangXX
        );
        assert_eq!(DriverMode::from_argv0("clang++-18"), DriverMode::ClangXX);
    }

    #[test]
    fn test_driver_mode_from_argv0_clang_cl() {
        assert_eq!(DriverMode::from_argv0("clang-cl"), DriverMode::ClangCL);
    }

    #[test]
    fn test_driver_mode_from_argv0_cc1() {
        assert_eq!(DriverMode::from_argv0("cc1"), DriverMode::CC1);
    }

    #[test]
    fn test_driver_mode_from_argv0_cc1plus() {
        assert_eq!(DriverMode::from_argv0("cc1plus"), DriverMode::CC1Plus);
    }

    #[test]
    fn test_driver_mode_default_language() {
        assert_eq!(DriverMode::CC1.default_language(), InputLanguage::C);
        assert_eq!(DriverMode::CC1Plus.default_language(), InputLanguage::CXX);
    }

    // ── Response file expansion ──────────────────────────────────────────

    #[test]
    fn test_expand_response_files_no_at() {
        let args = vec!["clang".to_string(), "-c".to_string(), "file.c".to_string()];
        let expanded = expand_response_files(&args);
        assert_eq!(expanded.len(), 3);
        assert_eq!(expanded[1], "-c");
    }

    #[test]
    fn test_expand_response_files_with_at() {
        let args = vec![
            "clang".to_string(),
            "@nonexistent.rsp".to_string(),
            "file.c".to_string(),
        ];
        // Should not panic; just skip the missing response file.
        let expanded = expand_response_files(&args);
        assert_eq!(expanded.last(), Some(&"file.c".to_string()));
    }

    // ── Version and help ─────────────────────────────────────────────────

    #[test]
    fn test_print_version() {
        // Just ensure no panic.
        print_version(DriverMode::Clang);
    }

    #[test]
    fn test_print_help() {
        // Just ensure no panic.
        print_help(DriverMode::Clang);
    }

    // ── clang_main ───────────────────────────────────────────────────────

    #[test]
    fn test_clang_main_version() {
        let args = vec!["clang".to_string(), "--version".to_string()];
        let code = clang_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_clang_main_help() {
        let args = vec!["clang".to_string(), "--help".to_string()];
        let code = clang_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_clang_main_no_input() {
        let args = vec!["clang".to_string()];
        let code = clang_main(&args);
        assert_eq!(code, 1); // error: no input files
    }

    #[test]
    fn test_clang_main_print_resource_dir() {
        let args = vec!["clang".to_string(), "-print-resource-dir".to_string()];
        let code = clang_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_clang_main_print_search_dirs() {
        let args = vec!["clang".to_string(), "-print-search-dirs".to_string()];
        let code = clang_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_clang_main_print_target_triple() {
        let args = vec!["clang".to_string(), "-dumpmachine".to_string()];
        let code = clang_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_run_clang() {
        let code = run_clang(["clang", "--version"]);
        assert_eq!(code, 0);
    }

    // ── Quick compile ────────────────────────────────────────────────────

    #[test]
    fn test_quick_compile_minimal() {
        let result = quick_compile("int x;", "x86_64-unknown-linux-gnu");
        assert!(result.is_ok());
    }

    #[test]
    fn test_quick_compile_function() {
        let result = quick_compile("int f(void) { return 42; }", "x86_64-unknown-linux-gnu");
        assert!(result.is_ok());
    }

    #[test]
    fn test_quick_compile_syntax_error() {
        let result = quick_compile("int f( {", "x86_64-unknown-linux-gnu");
        // Should fail with parse error.
        assert!(result.is_err());
    }

    // ── Legacy driver ────────────────────────────────────────────────────

    #[test]
    fn test_compile_legacy() {
        let opts = ClangOptions {
            standard: CLangStandard::C11,
            optimize: false,
            ..ClangOptions::default()
        };
        let result = compile_legacy("int x;", opts);
        assert!(result.is_ok());
    }

    // ── Tool entry points ────────────────────────────────────────────────

    #[test]
    fn test_cc1_main() {
        let args = vec!["cc1".to_string(), "--version".to_string()];
        let code = cc1_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_cc1plus_main() {
        let args = vec!["cc1plus".to_string(), "--version".to_string()];
        let code = cc1plus_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_clang_driver_main() {
        let args = vec!["clang".to_string(), "--version".to_string()];
        let code = clang_driver_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_clangxx_driver_main() {
        let args = vec!["clang++".to_string(), "--version".to_string()];
        let code = clangxx_driver_main(&args);
        assert_eq!(code, 0);
    }

    #[test]
    fn test_clang_cl_driver_main() {
        let args = vec!["clang-cl".to_string(), "--version".to_string()];
        let code = clang_cl_driver_main(&args);
        assert_eq!(code, 0);
    }
}